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:
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.
# 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:
{
"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.
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.
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. |
curl "https://gettrazo.app/api/v1/organizations?page=1&limit=50" \
-H "Authorization: Bearer $TRAZO_KEY"
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 } }'
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. |
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…"
}
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…" }
# 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 }. |
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 }
}
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. |
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]
}'
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/…" }
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. |
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. |
# 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.