Documentation

Management API

Everything the dashboard can do, over JSON. Authenticate with a personal API key (trz_pat_…) and manage organizations, sites, submissions, users, billing, and branding with exactly the permissions your account has in the UI. The API lives under https://gettrazo.app/api/v1 and its contract is English-only.

Authentication & API keys

Any user can create personal API keys from your account page under API keys. Creating or revoking a key sits behind a password confirmation, and each key gets a name so you can tell them apart. You can hold up to 10 active keys; revoke one at any time and it stops working immediately.

The key (trz_pat_…) is shown once, right after you create it, so copy it then; Trazo stores only a hash. Send it on every request in the Authorization header:

terminalbash
curl https://gettrazo.app/api/v1/me \
  -H "Authorization: Bearer trz_pat_your_key_here"

A key acts as you: same role (admin, seller, or owner) and same scope as the dashboard. Requests with a missing, invalid, or revoked key, or a key whose account is suspended, get a generic 401 unauthorized. Keys cannot create or revoke other keys; that only happens on the account page.

Requests & responses

Every response is JSON. A single resource comes wrapped in its name ({ "site": { … } }); collections come as an array plus a pagination object. Site create and key rotation additionally return the plaintext api_key once. Write requests take JSON bodies with the same top-level wrapper.

responsesjson
# Single resource: 200 (201 on create)
{ "site": { "id": 42, "name": "Acme Co", … } }

# Collection: 200
{
  "sites": [ { "id": 42, "name": "Acme Co", … } ],
  "pagination": { "page": 1, "pages": 3, "count": 120, "limit": 50, "prev": null, "next": 2 }
}

# Destroy: 200
{ "deleted": true, "id": 42 }

Collections paginate with ?page= and ?limit= (default 50, clamped to 1–100). The pagination object carries page, pages, count, limit, and prev/next page numbers (null at the edges).

Errors always use one shape: a code you can branch on, a human-readable message, and, for validation failures only, a details object mapping attributes to messages:

errorjson
{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed",
    "details": { "domain": ["can't be blank"] }
  }
}
Code HTTP When
bad_request 400 A required parameter is missing or malformed (for example an unknown label value).
unauthorized 401 Missing, invalid, or revoked API key, or a suspended account.
forbidden 403 Your role can't perform this action on this record.
not_found 404 No such record in your scope.
validation_failed 422 The record didn't pass validation; details maps each attribute to its messages.
rate_limited 429 Too many requests. Slow down and retry.
internal_error 500 Something broke on our side. Retry later.
upstream_error 502 Stripe rejected or failed a billing request.

Records outside your scope return 404 not_found, indistinguishable from records that do not exist.

Rate limits

Authenticated requests are limited to 120 per minute per API key. Requests without an Authorization header are limited to 60 per minute per IP. Over the limit you get 429 with the standard rate_limited error envelope. The public form-intake endpoint has its own separate limits.

Roles & permissions

The API enforces exactly the dashboard's rules: admins see everything, sellers see their organizations, owners see their sites. There are no API-only permissions, with one convenience: the users index is scoped for every role rather than admin-only.

Resource Admin Seller Owner
Dashboard Everything, plus organization warnings Their organizations Their sites
Organizations Full CRUD Through billing and branding only No access
Sites Full CRUD + all actions Their orgs' sites: create, update (can't move orgs), delete, rotate keys, activate/deactivate, billing Their sites: view, update name & domain, rotate key, send test
Submissions Read + review, all sites Read + review, their orgs' sites Read + review, their sites
Users Full management, bulk invites List & view their orgs' users; resend invites, invite links, password and 2FA resets for their owners Themselves only
Billing Every organization Their organizations No access
Branding Every organization Their organizations Their organization's icon only
Audit log & classifier stats Full access No access No access

Me

GET /api/v1/me works for any valid key and returns the calling user (id, email, role, status, and their organizations for sellers or sites for owners) plus the API key being used. Handy as a first call to verify a key and discover your scope.

GET /api/v1/mebash
curl https://gettrazo.app/api/v1/me \
  -H "Authorization: Bearer $TRAZO_KEY"

# 200
{
  "user": {
    "id": 7, "email": "you@example.com", "role": "seller", "status": "active",
    "organizations": [{ "id": 3, "name": "Acme Agency" }], "sites": []
  },
  "api_key": { "id": 1, "name": "CI deploys", "token_prefix": "trz_pat_abc12345", … }
}

Dashboard

GET /api/v1/dashboard works for every role and returns the dashboard's numbers for your scope. review_queue_count is the number of submissions waiting in the Likely spam tab, and failed_email_count the notifications that could not be sent. Admins also get the expired, expiring, and over-quota organization lists.

GET /api/v1/dashboardbash
curl https://gettrazo.app/api/v1/dashboard \
  -H "Authorization: Bearer $TRAZO_KEY"

# 200
{
  "dashboard": {
    "role": "seller", "total_submissions": 1840, "active_sites": 12,
    "failed_email_count": 0, "review_queue_count": 3,
    "recent_submissions": [ … ]
  }
}

Organizations

Admin-only, mirroring the dashboard. Writable attributes, wrapped in an organization object: name, active, expires_at, max_sites, monthly_submission_limit, notes. Responses include computed billing state: free_tier, subscribed, submissions_used, submission_pool_limit, sites_count. POST /api/v1/onboarding is the dashboard's onboarding wizard: an organization plus a user email for its seller, created together or not at all.

Method Path Who Notes
GET /api/v1/organizations Admin Paginated list; ?q= searches name, slug, and brand name.
GET /api/v1/organizations/:id Admin One organization.
POST /api/v1/organizations Admin 201 with the new organization.
PATCH /api/v1/organizations/:id Admin Returns the updated organization.
DELETE /api/v1/organizations/:id Admin Deletes the organization and everything under it.
POST /api/v1/onboarding Admin Creates an organization and invites its seller in one step.
terminalbash
curl "https://gettrazo.app/api/v1/organizations?page=1&limit=50" \
  -H "Authorization: Bearer $TRAZO_KEY"
terminalbash
curl -X POST https://gettrazo.app/api/v1/organizations \
  -H "Authorization: Bearer $TRAZO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "organization": { "name": "Acme Agency", "max_sites": 3 } }'
terminalbash
curl -X POST https://gettrazo.app/api/v1/onboarding \
  -H "Authorization: Bearer $TRAZO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": { "name": "Acme Agency", "max_sites": 5 },
    "user": { "email": "seller@acme.example" }
  }'

# 201: the organization plus its invited seller
{ "organization": { "id": 9, … }, "user": { "id": 31, "status": "invited", … } }

Sites

Site payloads are wrapped in a site object: name, domain, notification_email, review_email, organization_id. Leads go to notification_email; the optional review_email gets the borderline-spam review nudges instead, so you can handle a client's spam review yourself. Owners can change only name and domain (other attributes are silently ignored for them). Sellers pick one of their own organizations on create and cannot move a site afterwards; only admins move sites between organizations. Admins and sellers manage the site's single owner with top-level owner_email (invites a new owner), owner_user_id (an existing owner), or "owner_user_id": null (removes access); on update the site object is optional. An owner left with no sites loses their login. Site keys (sk_live_…) are hashed at rest; the plaintext appears exactly once, in the create and rotate responses.

Method Path Who Notes
GET /api/v1/sites All roles (scoped) Optional ?organization_id= and ?q= (name, domain, notification email); ordered by name.
GET /api/v1/sites/:id All roles (scoped) One site.
POST /api/v1/sites Admin, seller 201; response includes the plaintext api_key once.
PATCH /api/v1/sites/:id All roles (scoped) Params sliced by role (see above).
DELETE /api/v1/sites/:id Admin, seller Deletes the site; an owner left with no sites is removed too.
POST /api/v1/sites/:id/rotate_key All roles (scoped) New key; the old one stops working immediately. Plaintext returned once.
PATCH /api/v1/sites/:id/toggle_active Admin, seller Flips active; suspends or reactivates an owner with no other active site.
POST /api/v1/sites/:id/send_test All roles (scoped) Creates a test submission and emails the notification address.
POST /api/v1/sites/:id/cancel_billing Admin, seller Stops billing; submissions accepted until end of month. 422 if already canceled.
POST /api/v1/sites/:id/uncancel_billing Admin, seller Undoes a pending cancellation. 422 if none pending.
terminalbash
curl -X POST https://gettrazo.app/api/v1/sites \
  -H "Authorization: Bearer $TRAZO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site": {
      "name": "Acme Co",
      "domain": "acme.example",
      "notification_email": "leads@acme.example",
      "organization_id": 7
    },
    "owner_email": "owner@acme.example"
  }'

# 201: the plaintext key appears once, on create and rotate only
{
  "site": { "id": 42, "name": "Acme Co", "api_key_prefix": "sk_live_abc1", … },
  "api_key": "sk_live_abc123…"
}
terminalbash
curl -X POST https://gettrazo.app/api/v1/sites/42/rotate_key \
  -H "Authorization: Bearer $TRAZO_KEY"

# 200
{ "site": { "id": 42, … }, "api_key": "sk_live_new456…" }
terminalbash
# Hand the site to a different client (the site object is optional here)
curl -X PATCH https://gettrazo.app/api/v1/sites/42 \
  -H "Authorization: Bearer $TRAZO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "owner_email": "new-owner@acme.example" }'

# Remove owner access
curl -X PATCH https://gettrazo.app/api/v1/sites/42 \
  -H "Authorization: Bearer $TRAZO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "owner_user_id": null }'

Submissions

Read and review only: submissions are created by the public form-intake endpoint, never through the management API. The index takes the dashboard's filters: site_id, organization_id, from, to, email_sent, free-text q, and tab (all, not_spam, likely_spam, spam), and includes per-tab counts. Labeling a withheld submission not_spam delivers it.

Method Path Who Notes
GET /api/v1/submissions All roles (scoped) Filters + tab; payload includes counts and pagination.
GET /api/v1/submissions/export All roles (scoped) Same filters and tab as the index, as CSV (up to 10,000 rows).
GET /api/v1/submissions/:id All roles (scoped) One submission with its classification verdict.
POST /api/v1/submissions/:id/label All roles (scoped) label = "not_spam" or "spam". The authoritative correction; moves tabs.
POST /api/v1/submissions/:id/rate All roles (scoped) rating = "up" or "down". Model feedback only.
POST /api/v1/submissions/:id/resend_email All roles (scoped) Re-enqueues the notification email.
POST /api/v1/submissions/retry_failed_emails All roles (scoped) Re-enqueues failed emails in your scope; returns { "retried": n }.
terminalbash
curl "https://gettrazo.app/api/v1/submissions?site_id=42&tab=not_spam&from=2026-08-01&q=quote" \
  -H "Authorization: Bearer $TRAZO_KEY"

# 200
{
  "submissions": [ { "id": 1234, "name": "Jane Doe", "email": "jane@example.com", … } ],
  "counts": { "all": 128, "not_spam": 110, "likely_spam": 6, "spam": 12 },
  "pagination": { "page": 1, "pages": 3, "count": 110, "limit": 50, "prev": null, "next": 2 }
}
terminalbash
curl -X POST https://gettrazo.app/api/v1/submissions/1234/label \
  -H "Authorization: Bearer $TRAZO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "not_spam" }'

Users

The index is scoped for every role: admins list everyone, sellers list their organizations' users, owners see only themselves. Filters (q, role, status, organization_id, site_id) narrow that scope and never widen it. Creating a user (admin only) sends an invitation email; user takes email and role, plus top-level organization_ids / site_ids to assign memberships. The admin role can never be assigned through the API. Sellers manage their owners through the site endpoints and support them with the invite and reset actions.

Method Path Who Notes
GET /api/v1/users All roles (scoped) Scoped for every role; filters q, role, status, organization_id, site_id.
GET /api/v1/users/:id Admin, self, managing seller One user with organizations and sites.
POST /api/v1/users Admin 201; sends the invitation email. admin role not assignable.
POST /api/v1/users/bulk Admin Invites up to 200 emails with one role; returns invited, skipped, and invalid lists.
PATCH /api/v1/users/:id Admin Partial. email, role (never admin); membership lists you leave out stay as they are.
DELETE /api/v1/users/:id Admin Deletes the user.
POST /api/v1/users/:id/resend_invitation Admin, managing seller Re-sends the invite email with a fresh token.
POST /api/v1/users/:id/invite_link Admin, managing seller Returns { "invite_url": … }. 422 if already accepted.
POST /api/v1/users/:id/reset_password Admin, managing seller Emails a password reset link.
POST /api/v1/users/:id/reset_2fa Admin, managing seller Emails a two-factor reset link.
POST /api/v1/users/:id/suspend Admin Blocks sign-in and API use immediately.
POST /api/v1/users/:id/reactivate Admin Lifts a suspension.
terminalbash
curl -X POST https://gettrazo.app/api/v1/users \
  -H "Authorization: Bearer $TRAZO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": { "email": "seller@example.com", "role": "seller" },
    "organization_ids": [7]
  }'
terminalbash
curl -X POST https://gettrazo.app/api/v1/users/9/invite_link \
  -H "Authorization: Bearer $TRAZO_KEY"

# 200
{ "invite_url": "https://gettrazo.app/login/invite/…" }
terminalbash
curl -X POST https://gettrazo.app/api/v1/users/bulk \
  -H "Authorization: Bearer $TRAZO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["a@example.com", "b@example.com"], "role": "owner", "site_ids": [42] }'

# 201
{ "invited": ["a@example.com"], "skipped": ["b@example.com"], "invalid": [] }

Billing

The billing page, over JSON. Each organization reports whether it is subscribed, its billable sites, the estimated monthly price, and submissions_used against submission_pool_limit. Checkout and the billing portal return a short-lived Stripe URL for a person to open; nothing is paid through the API. Per-site cancellation lives on the site (cancel_billing).

Method Path Who Notes
GET /api/v1/billing Admin, seller Every organization in your scope; ?q= searches. Owners get 403.
GET /api/v1/billing/:organization_id Admin, seller One organization's billing state.
POST /api/v1/billing/:organization_id/checkout Admin, seller Starts the subscription; returns { "url": … }. 422 if already subscribed.
POST /api/v1/billing/:organization_id/portal Admin, seller Opens the Stripe portal (cards, invoices, cancel). 422 without a billing account.
terminalbash
curl -X POST https://gettrazo.app/api/v1/billing/7/checkout \
  -H "Authorization: Bearer $TRAZO_KEY"

# 200: a Stripe page for a human to open
{ "url": "https://checkout.stripe.com/c/pay/cs_…" }

Branding

White-label what your site owners see: brand_name, brand_color (#rrggbb), and an icon (PNG, JPEG, WebP, or SVG up to 1 MB), wrapped in branding. Send the icon as a multipart upload or as a base64 data URI in JSON. Blank name or color resets to Trazo's default.

Method Path Who Notes
GET /api/v1/branding Admin, seller Every organization in your scope. Owners get 403.
GET /api/v1/branding/:organization_id Admin, seller One organization's branding.
PATCH /api/v1/branding/:organization_id Admin, seller brand_name, brand_color, icon.
GET /api/v1/branding/:organization_id/icon Admin, seller, the org's owners The icon itself.
DELETE /api/v1/branding/:organization_id/icon Admin, seller Removes the icon.
terminalbash
# Multipart upload
curl -X PATCH https://gettrazo.app/api/v1/branding/7 \
  -H "Authorization: Bearer $TRAZO_KEY" \
  -F "branding[brand_name]=Acme Studio" \
  -F "branding[brand_color]=#2e7d52" \
  -F "branding[icon]=@logo.png;type=image/png"

# Or JSON with a base64 data URI
curl -X PATCH https://gettrazo.app/api/v1/branding/7 \
  -H "Authorization: Bearer $TRAZO_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"branding\": { \"icon\": \"data:image/png;base64,$(base64 -w0 logo.png)\" } }"

Audit log & classifier stats

Admin-only views of the security audit log and the spam classifier's quality. The audit log filters by user_id and event_type and flags anomalies; the stats include precision and recall against human labels, calibration, cost, and a page of disagreements.

Method Path Who Notes
GET /api/v1/auth_events Admin Newest first; ?user_id=, ?event_type=.
GET /api/v1/classifier_stats Admin Quality, review-queue trend, cost, disagreements.
GET /api/v1/classifier_stats/training_data Admin CSV of every human-evaluated submission.

Deliberately not in the API

A few things stay in the dashboard on purpose: creating or revoking personal API keys (a stolen key must not be able to mint more keys), your own password, email, and second factors, creating admin users (CLI only), and creating or editing submissions (the intake endpoint is the only way in). Billing calls hand back Stripe links rather than taking payment.