Documentation
Inth REST API
Use the REST API to manage Inth organizations, members, projects, and API keys, run Code Audit scans, and work the Inbox from a server, script, or CI job.
- Base URL.
https://api.inth.com - OpenAPI spec.
https://api.inth.com/openapi.json - Status.
GET /health
To connect Codex or another MCP client with your Inth account, use Inth MCP instead.
Authentication
Every request carries a bearer token. There are two kinds.
Organization API keys are service credentials for CI jobs, servers, and integrations. They belong to an organization, not a person, and keep working when the person who created them leaves.
Create a key in Organization settings > API keys. Inth shows the inth_...
secret once. Store it like a deployment credential and never expose it in
client-side code. Each key has access to its organization.
User tokens belong to a person. They are issued through the OAuth device
authorization grant: a client requests a code, you approve it in the
dashboard, and the client receives an access token plus a refresh token bound
to your account. Requests act with your own organization memberships and
roles, and stop working when you leave an organization. The endpoints are
advertised in the authorization server metadata at
https://api.inth.com/.well-known/oauth-authorization-server; use the
device_authorization_endpoint and token_endpoint it lists with the
inth-cli client. The Inth CLI handles this flow for terminal use.
Some operations act on behalf of a person rather than an organization and
accept only a user token: creating an organization, inviting or changing
members, creating, rolling, or deleting API keys, starting or unlocking Code
Audit scans, and changing Inbox findings. A scan spends credits and a status
change names who made it, so both are attributed to a person. An organization
API key belongs to one organization and cannot found another, so
POST /v1/organizations answers 403 to a key.
The request answers 201 with the new organization's id, slug, name,
and your owner role, and sets up billing on the free plan. Slugs are 3 to 20
characters of lowercase letters and numbers, with single hyphens between
groups. A taken slug answers 409 with CONFLICT.
See rate limits for the request limits and API key caps that apply to each kind of token.
Scopes
Product endpoints require a scope. Feedback intake requires only a valid bearer token. A token carries the scopes it was issued with, and a request still needs the membership role behind the token to allow the action.
| Scope | Grants |
|---|---|
organizations.read | List the organizations you belong to. |
organizations.write | Create organizations you will own. |
projects.read | Read projects, their consent configuration, and the vendors seen on them. |
projects.write | Create, update, and delete projects and their consent configuration. |
members.read | List organization members and pending invitations. |
members.write | Invite people, cancel invitations, change roles, and remove members. |
api-keys.read | List organization API keys. |
api-keys.write | Create, roll, and delete organization API keys. |
code-audit.read | Read connected repositories, scans, scan requests, and findings. |
code-audit.write | Start scans, approve prepared full-audit quotes and spend credits to unlock reports. |
inbox.read | Read Inbox findings and evidence. |
inbox.write | Update finding status or assignment and create GitHub issues. |
vendors.write | Approve or ignore vendors seen on a project. |
billing.read | Read the plan, credit balance, entitlements, top-up settings and retained settled usage. |
agents.read | Read your chats and chats shared with your organization. |
agents.write | Upload chat documents, start or message your chats, share them, or delete them. Replies use credits. |
consent.read | Read consent configuration, records, analytics and runtime status. Also requires projects.read. |
consent.write | Update consent settings, translations, IAB and policies. Also requires projects.read and projects.write. |
consent.keys.read | Read runtime key metadata. Secret key values are never returned. Also requires projects.read. |
website-audit.read | Read targets, scans, reports, checks, cookies and evidence. Also requires projects.read. |
website-audit.write | Manage targets, verify domains, review findings and start scans. Also requires projects.read. |
billing.details.read | Read invoices, billing profile, payment method summaries and provider configuration for organizations you own. |
account.read | Read your profile and PII masking preference. |
notifications.read | Read your notification preferences and permitted organization routing. |
organization-retention.read | Read the organization's provider retention controls. |
support.read | Read support conversations and attachments you can access through ownership or sharing. |
support.write | Create conversations, send replies, manage owned conversation status and upload support files. |
consent.lifecycle.write | Update, upgrade or delete a consent runtime. Also requires projects.read and projects.write. |
consent.keys.write | Create, rotate or revoke runtime keys. Also requires projects.read and projects.write. |
billing.write | Preview and approve billing changes, manage subscriptions and payment settings, and open hosted payment flows. Owner only. |
account.security.read | Read your browser sessions and connected OAuth devices. |
account.security.write | Revoke your browser sessions and connected OAuth devices. |
integrations.read | Read bounded provider connections, repositories, properties and verification proofs. |
integrations.write | Manage GitHub installation, sync, repository settings, scan policies and project links. Admin or owner only. |
account.write | Update your profile, avatar and PII masking preference. |
account.delete | Permanently delete your account under existing ownership and self-delete checks. |
notifications.write | Update your own account and organization email preferences. |
notifications.routing.write | Set organization role routing to current members. Admin or owner only. |
organization-retention.write | Update provider retention controls under existing plan and availability checks. Owner only. |
organizations.settings.write | Update organization name, logo and slug. Admin or owner only. |
organizations.delete | Permanently delete an organization under existing self-delete checks. Owner only. |
A user token carries the scopes you approved at sign-in, and GET /v1/me
lists them in scopes. Account and organization deletion scopes require an
explicit OAuth scope request. An authorization request that omits scopes
does not grant them. Organization API keys hold a fixed set:
organizations.read, projects.read, projects.write, api-keys.read,
inbox.read, and billing.read. A key cannot create
organizations, manage members, create keys, start or unlock scans, change
Inbox findings, approve or ignore vendors, or use Inth Agent chats. Code Audit scopes are excluded from organization API keys,
so these routes return 403 INSUFFICIENT_SCOPE before invoking Dashboard sync.
A request whose token lacks the scope answers 403 with the error code
INSUFFICIENT_SCOPE and names the missing scope in a header:
Resources
Every resource is top-level and every ID is global. A resource carries its own
id, name, and slug where it has one; references to other resources are
prefixed, such as organizationId on a project.
Most organization-owned lists and creates take an optional organizationId
query parameter. Task-specific bodies and organization settings paths declare
their selectors in OpenAPI. Direct resource IDs resolve their tenant and check
current access. Listing or creating top-level organizations uses no tenant selector:
Without it an OAuth token uses the account's saved Dashboard organization. If
that choice is unavailable and the account has multiple organizations, supply
organizationId explicitly to avoid acting in the wrong organization. A user
token with one organization uses that organization, and an organization
API key always acts in its own. A resource fetched by ID, such as a member,
scan, or Inbox item, resolves its own organization; one outside your
memberships answers 404, the same as an unknown ID. Consent settings live on
the project as a consent object: read them with GET /v1/projects/{id} and
change them with the same PATCH that renames the project.
Code Audit and the Inbox
A scan runs on the production branch of a repository the Inth GitHub App is
connected to. The first scan of a repository is a free preview: the report
shows a subset of the findings and reports how many are locked and what
unlocking costs in credits. Starting a scan answers 202 with the scan once
the workflow has created it, or with a scan request to poll when that takes
longer than a few seconds.
The repository decides the organization. Read the findings with
GET /v1/code-audit/scans/{scanId}/issues. A free preview answers the visible
findings plus lockedCount and unlockCredits;
POST /v1/code-audit/scans/{scanId}/unlock spends the credits, and answers
402 with INSUFFICIENT_CREDITS when the balance is short. Check the balance
first with GET /v1/billing.
Every scan also files its findings into the Inbox. Read them with
GET /v1/inbox, and set a status with PATCH /v1/inbox/{itemId}, sending
back the version you read so two people cannot overwrite each other.
Responses
Every JSON endpoint wraps its result in a stable envelope:
File downloads, such as invoice PDFs and screenshots (see Evidence and history), return the file's own bytes instead.
Most list endpoints return data as an array plus a pagination object. Pass
pagination.nextCursor as the cursor query parameter to fetch the next page.
Cursors are opaque and specific to the endpoint and filters that returned them.
Do not decode them or reuse them with another endpoint or filter set. Some
endpoints page differently: consent records use a numbered page and return
items and nextPage. The table under
Evidence and history gives each endpoint's own
pagination.
For example:
Errors use the same envelope with success: false and a machine-readable
error.code. Validation errors may include an error.details array.
Every response carries an X-Request-Id header. Include it when reporting an issue.
Versioning and deprecation
Changes within v1 are additive. Clients should ignore fields they do not
recognize. Breaking changes use a new version prefix.
The public API currently uses /v1. No retirement date is announced for this
version. A new version does not by itself mean that /v1 is deprecated.
Deprecation notices will be published in this documentation with the affected version or endpoints, the replacement, migration instructions, and the planned retirement date. No minimum notice period is currently guaranteed. Check the documentation before migrating; clients should not infer a sunset date from the API version number or the absence of a response header.
Treat resource IDs as opaque strings.
Agent feedback
Report an unexpected failure, misleading documentation, or a missing capability
with POST /v1/feedback. It accepts existing API keys and OAuth access tokens,
requires no product scope, and does not charge Credits.
Discover the endpoint and reporting guidance at
/.well-known/agent-feedback.json.
This uses the discovery idea from feedback.now.
Inth uses its own request and response schema, documented in OpenAPI. It does not
implement the full feedback.now protocol, anonymous intake, evidence uploads, or
receipt polling.
Only category and message are required. A new report returns 201 with
{ "success": true, "data": { "reference": "FDB-...", "alreadySubmitted": false } }.
Sending the same report again within the same UTC day returns 200 with the
same reference and alreadySubmitted: true, so retries are safe without an
idempotency key.
Categories are bug, friction, docs_mismatch, feature_request, and
performance. The optional surface is api, mcp, cli, docs, sdk,
dashboard, or other. Other optional fields are expected, actual,
reproduction, requestId, operation, clientName, and clientVersion.
Include the failed request's
X-Request-Id when available. Reports about local CLI failures or documentation
do not need a request ID.
The quota is ten new reports per authenticated user or API key per UTC clock
hour. Repeated reports do not consume that quota. Normal credential request limits still
apply. A 429 means the limit was reached; 503 means new feedback intake is
paused. Repeated reports still return the saved reference during a pause.
Hashed agent quota counters become eligible for deletion after 24 hours. The hourly support maintenance job removes up to 1,000 expired counters per run. This cleanup does not delete accepted reports or their retry references.
Submit once per distinct issue and continue the original task if reporting fails. Avoid routine validation errors. Do not include credentials, personal data, customer payloads, or full transcripts. Reports go to the Inth team, so agents should follow the user's permission to send feedback.
The API supports CLI reports now. A dedicated CLI command will ship separately.
Evidence and history
Resource IDs select one resource in your accessible organizations. An organization owner cannot read another person's private chat or support conversation. List responses contain one bounded page; use their continuation value to fetch the next page. A direct ID read does not depend on a recent synchronization window.
| Data | REST read | Detail and pagination |
|---|---|---|
| Code Audit | GET /v1/code-audit/scans/{scanId}/issues | detail=full includes every evidence block. Report decisions, context questions, coverage gaps and quotes are kept. access and lockedCount still control what is visible. |
| Inbox | GET /v1/inbox/{itemId} | Includes assignedToUserId, website evidence and every code evidence block. assignmentOptionsPath links to paginated member discovery, which requires members.read. |
| Consent | GET /v1/projects/{projectId}/consent | Summary links to full configuration/i18n, configuration/iab and configuration/policies reads. overview links to complete analytics. |
| Consent records | GET /v1/projects/{projectId}/consent/records | Numbered page, starting at 1; optional q, at most 256 characters. Returns items, page, fixed pageSize, total and nextPage. No limit or cursor parameter. |
| Runtime keys | GET /v1/projects/{projectId}/consent/runtime-keys | One provider page, limit from 1 to 100 and opaque cursor. Metadata only. |
| Website Audit | GET /v1/website-audit/targets and /v1/website-audit/scans | limit from 1 to 100, default 25, and opaque cursor bound to the organization and filters. Direct target and scan reads use their IDs. |
| Website evidence | GET /v1/website-audit/scans/{scanId}/results and /report | Checks, comparison with the previous comparable scan, and evidence data. Scan-scoped /cookies is paginated. |
| Support | GET /v1/support/conversations and /v1/support/conversations/{conversationId} | Lists up to 50 summaries. Detail returns up to 100 chronological messages, nextCursor, hasMore and a separate polling checkpoint. Continue until nextCursor is null; use checkpoint as cursor to poll for new messages. |
| Agent chats | GET /v1/agent-chats and /v1/agent-chats/{chatId} | Lists owned and organization-shared chats. limit from 1 to 100, default 50. Detail retains authors, attachments, activities and structured research. |
| Billing | GET /v1/billing/entitlements, /configuration and /credit-usage | Owner-only. /credit-usage covers 30 days. /credit-ledger pages all retained settled consumption with attribution, product and date filters. Pending/released holds and purchases are excluded. |
| Invoices | GET /v1/billing/invoices and /v1/billing/invoices/{invoiceId} | Opaque cursor. Invoice IDs come from the public list; direct detail checks provider customer ownership independently of recent history. |
| Payment methods | GET /v1/billing/payment-methods | One provider page, limit from 1 to 100, default 20. Follow nextCursor even after a short or empty page. Only safe Card and Link summaries are returned. |
| Integrations | GET /v1/integrations | Links to bounded GitHub installations, repository settings, project links, Search Console properties and verified domain proofs. Requires integrations.read. Members see only their own provider property listings; admins and owners can see organization listings. |
| Latest cookie inventory | GET /v1/website-audit/cookie-inventory | Latest completed owned-site scan per target, with optional projectId. Pages targets by ID. Follow each cookiesPath, or call list_website_scan_cookies with its scanId, to retrieve all cookie attributes and evidence. dataCompleteness: "latest-scan-index" describes this split. |
| Browser sessions and devices | GET /v1/account/sessions and /v1/account/connected-devices | Requires account.security.read. ID-ordered pages, default 20 and maximum 100. OAuth has no current browser session. Missing device activity timestamps are null. |
| Account and settings | GET /v1/account, /v1/notifications/preferences and /v1/organizations/{organizationId}/data-controls | Reads current authorized settings. Notification routing links to the separately scoped member list. |
dataCompleteness: "summary" means a detail read is available at the returned
path. A nullable value means no value is known or applicable. Optional historical
fields can be absent because the original record did not capture them. An absent
evidence field is not proof that no evidence exists. Use the full detail read.
Invoice PDFs, screenshots, support attachments and chat documents stream through authenticated API routes:
GET /v1/billing/invoices/{invoiceId}/pdf and
GET /v1/website-audit/scans/{scanId}/screenshots/{captureId} and
GET /v1/support/attachments/{attachmentId}/content and
GET /v1/agent-chat-attachments/{attachmentId}/content.
Invoice detail, screenshot discovery and support messages return these download paths. Send
the bearer only to the API origin; never forward it to a storage or payment
provider, and refuse redirects when downloading.
MCP clients can read the bytes over their authorized connection using
get_billing_invoice_pdf, get_website_scan_screenshot_content and
get_support_attachment_content and get_agent_chat_attachment_content.
These tools return base64 chunks, default
16 KiB and maximum 64 KiB, with etag, nextOffset, mediaType and byte counts.
Continue with offset: nextOffset and ifMatch: etag until hasMore is false.
A missing or changed continuation identity returns CONFLICT. No OAuth token
or storage URL is exposed. Large retained files remain retrievable through
successive chunks.
Updates and release controls
PATCH /v1/inbox/{itemId} requires version and at least one of status or
assignedToUserId. Omit a field to preserve it. assignedToUserId: null
unassigns the item; a user ID must belong to the same organization. An
assignment-only patch preserves the current status atomically. A stale version
returns CONFLICT unless the requested result already exists.
POST /v1/agent-chats/{chatId}/share permanently shares an owned chat with its
organization. There is no unshare operation. Only its owner can send messages or
delete it, including after sharing. DELETE /v1/agent-chats/{chatId} deletes its
attachments too. Confirm the target before either irreversible action.
The permanent allow-public-agent-writes switch defaults on. Operators turn it
off to pause public writes: the API returns SERVICE_UNAVAILABLE before any
effect, and reads and history remain available. The API evaluates it after
authorization using verified user and organization IDs. Scan starts also retain
the allow-audit-starts operational brake. Project creation retains
allow-project-creation.
User tokens must request and approve new scopes. Refreshing an old token never adds them. Organization API keys retain their existing six capabilities.
Prepared full-audit approval accepts an exact quote and maximum-credit cap, as described below. Completed-report unlock and chat replies have no cap input. A separate price read does not impose a spending cap on those operations.
Administration and approvals
All operations below require a user token. Organization API keys retain their six existing capabilities. New OAuth scopes require renewed approval.
| Task | REST operation | Scope and behavior |
|---|---|---|
| Runtime lifecycle | POST /v1/projects/{projectId}/consent/lifecycle/update, /upgrade; DELETE /v1/projects/{projectId}/consent/runtime | consent.lifecycle.write, projects.read, projects.write. Supply the exact expectedInstanceId and expectedBackendVersion read from lifecycle metadata. Existing role, entitlement and lifecycle checks remain. |
| Runtime keys | POST /v1/projects/{projectId}/consent/runtime-keys; DELETE /runtime-keys/{keyId}; POST /runtime-keys/{keyId}/rotate | consent.keys.write, projects.read, projects.write. Creation takes name. Rotation requires overlapSeconds, 0 to 86400. New secrets appear once. A zero overlap invalidates the old secret immediately. |
| Browser-session revocation | DELETE /v1/account/sessions/{id}; POST /v1/account/sessions/revoke | account.security.write. Bulk body takes mode: "all" or "others". OAuth has no current browser session and must use all with confirmation: "revoke-all-browser-sessions". This leaves OAuth grants active. A browser session can use others; single-ID revocation protects its actual current session. |
| Device revocation | DELETE /v1/account/connected-devices/{id} | account.security.write. Revokes your selected first-party or reviewed-partner OAuth grant and linked access tokens. Revoking the caller's grant can end this connection. |
| Support messages | POST /v1/support/conversations; POST /v1/support/conversations/{conversationId}/messages | support.write. Required clientMessageId and text; optional ordered unique attachmentIds, maximum 5. Reuse the UUID only for an identical retry. Changed payloads conflict. |
| Support visibility and status | POST /v1/support/conversations/{conversationId}/share, /close, /reopen | support.write. Creator-only sharing and status changes. Organization-shared members can reply. No admin override grants access to someone else's private conversation. |
| Support uploads | POST /v1/support/attachments; POST /v1/support/attachments/{attachmentId}/finalize; DELETE /v1/support/attachments/{attachmentId} | support.write. Create an upload with clientAttachmentId, fileName, mediaType and sizeBytes. PUT the exact declared bytes and media type to the returned short-lived private upload URL without an API bearer. Finalize verifies stored metadata. Images allow 10 MiB; screen recordings 100 MiB. Discard applies only to pending, owned uploads. |
| GitHub approval | POST /v1/integrations/github/install | integrations.write, admin/owner. Returns a signed provider approval URL and mode: "hosted-person". The person completes approval in a browser; return is fixed to organization integration settings. Do not send provider tokens to the API. |
| GitHub sync | POST /v1/integrations/github/sync; POST /v1/integrations/github/installations/{id}/sync | integrations.write, admin/owner. Uses an internal installation ID from discovery. Changes stored provider data and reports failed accounts. |
| Repository settings | PATCH /v1/integrations/github/repositories/{id} | integrations.write, admin/owner. Optional branchFilters and ignoredPaths; omission preserves a field and an empty array clears it. Existing first-organization automation ownership is enforced. |
| PR monitoring | PUT /v1/integrations/github/repositories/{id}/pull-request-scans | integrations.write, admin/owner. Required enabled, optional branchFilters. Enabling authorizes future continuous Code Audit scans, which use Credits, under existing entitlement, ownership and audit-start controls. |
| Project binding | PUT /v1/integrations/github/repositories/{id}/project-link | integrations.write, admin/owner. projectId must be active in the same organization. Reuses Dashboard behavior, replacing its repository binding and resetting root to / and production branch to null. |
| Scheduled-policy cleanup | POST /v1/integrations/github/scheduled-policies/cleanup | integrations.write, admin/owner. Deletes weekly and cron policies, retaining PR policies and history. |
| Financial preview and approval | POST /v1/billing/plans/preview, /plans/change, /credits/preview, /credits/purchase | billing.write, owner. Supply a stable checkout UUID. Approval includes the complete quote returned by preview. The shared payment boundary re-previews and refuses changed prices or a changed UTC renewal date before charging. |
| Financial settings | PUT /v1/billing/credit-auto-top-up, /profile, /payment-methods/default; POST /v1/billing/payment-methods/remove, /subscriptions/cancel, /subscriptions/uncancel, /portal | billing.write, owner. Recurring top-ups require an explicit monthly purchase limit. Cancellation and payment-method removal require target-specific confirmation fields. |
Deleting a Consent runtime archives it and removes runtime access. For v2, historical consent records remain in shared storage and this action does not schedule their purge. A completed lifecycle response confirms archival, not erasure of those records.
Financial operations can return a hosted-person flow. Open it in a browser for payment approval or provider-required authentication, then read the resulting billing state. Return destinations are fixed by the server. The API never accepts payment card data, provider tokens or caller-supplied redirects, and public responses omit embedded payment client secrets. An uncertain mutation must be reconciled with its stable request identity and current state before another purchase is attempted.
| Personal or organization setting | REST operation | Scope and input |
|---|---|---|
| Profile | PATCH /v1/account | account.write. At least one of trimmed name or boolean hidePII. Omission preserves a field; null is rejected. |
| Account avatar | PUT /v1/account/avatar; DELETE /v1/account/avatar | account.write. PUT accepts raw PNG, JPEG, WebP or GIF, at most 1 MiB, with matching MIME type and signature. MCP upload_account_avatar accepts canonical base64 up to 512 KiB decoded. |
| Account deletion | DELETE /v1/account | account.delete. confirmation must match the current email. Existing self-delete availability and sole-owner blockers remain authoritative. |
| Email preferences | PATCH /v1/notifications/preferences | notifications.write. scope is account or organization; both change the caller's own preferences. family, enabled and mode select the existing email family and delivery behavior. |
| Notification routing | PUT /v1/notifications/routing | notifications.routing.write, admin/owner. role, configured and unique current-member userIds, at most 500. configured: false requires an empty list and restores fallback routing. configured: true with an empty list selects no recipients. |
| Organization settings | GET and PATCH /v1/organizations/{organizationId}/settings | Reads use organizations.read; name changes use organizations.settings.write and admin/owner permission. PATCH takes a trimmed name, 2 to 255 characters. |
| Organization logo | PUT and DELETE /v1/organizations/{organizationId}/logo | organizations.settings.write, admin/owner. Same raw image formats and REST size limit as avatars. MCP upload_organization_logo accepts canonical base64 up to 512 KiB decoded. |
| Organization slug | POST /v1/organizations/{organizationId}/slug | organizations.settings.write, admin/owner and existing rename availability. newSlug and expectedSlug are canonical slugs, 3 to 20 characters. The shared transaction checks the current slug before reserving redirects and renaming. |
| Provider retention | PATCH /v1/organizations/{organizationId}/data-controls | organization-retention.write, owner. Takes stable mutationId, expectedVersion and providerRetention: "standard" or "strict-zdr". Existing enterprise, provider configuration, rollout and active-run checks remain. |
| Organization deletion | DELETE /v1/organizations/{organizationId} | organizations.delete, owner. confirmation must match the current slug. Existing self-delete availability and purge-service checks remain. |
These writes use the same public rollout and operational pause controls as the other administration actions. They accept no caller-supplied user identity. Deleting an account or organization permanently purges its dependent data. Confirm the specific account email or organization slug before submitting it.
Prepared Code Audit approval
GET /v1/code-audit/scans/{scanId}/quote requires code-audit.read and returns
the pinned plan, credit price, expiry, state and workflow approval availability.
It remains readable while new audit starts are paused.
POST /v1/code-audit/scans/{scanId}/quote/approve requires a person token with
code-audit.write, an admin or owner role and the existing plan checks. Supply
quoteId, candidatePlanChecksum, nonnegative integer maxCredits and a stable
UUID v4 requestId. An optional body organizationId asserts the tenant;
query parameters are rejected. The shared reservation boundary locks the stored
quote and checks its identity, plan, expiry and credit price before reserving.
A changed quote or exceeded cap returns CONFLICT. Keep the same request ID
when reconciling an uncertain response.
Approval retains allow-audit-starts and the public write controls. API-owned
workflows can continue through this operation. Older Dashboard-owned workflows
return requires_dashboard with a canonical Dashboard URL before reserving
credits. Their owning deployment has no receiving approval handler in this
checkout, so the public API cannot enforce the delegated cap there.
This operation approves a prepared full audit. The existing completed-report
unlock action remains separate and does not accept a credit cap.
Chat documents
POST /v1/agent-chat-attachments accepts either application/json with
{fileName, mediaType?, data} or multipart/form-data with exactly one file
field. JSON data is canonical padded base64 without a data URL prefix.
Both formats validate the complete original file, with a decoded limit of
20 MiB. The JSON route allows 27,962,028 base64 characters plus 64 KiB of
envelope overhead. Other JSON routes retain their 1 MiB request limit.
The upload requires a person token with agents.write, public write controls
and allow-document-processing. Upload and private storage verification finish
before the response returns a ready attachment ID. There is no finalize step.
The pending-file quota is ten files and 40 MiB per person and organization;
unused uploads expire after 24 hours. Upload retries create a new attachment ID.
Use GET /v1/agent-chat-attachments to recover a lost response, and
DELETE /v1/agent-chat-attachments/{attachmentId} to discard an owned draft.
Start and send accept ordered, unique attachmentIds, at most ten. An empty
message requires at least one document. Keep the same clientMessageId, text
and ordered attachments for an uncertain retry. Changed content conflicts.
New document-bearing turns honor the document-processing and public write
controls; accepted identical retries remain recoverable during pauses.
GET /v1/agent-chat-attachments/{attachmentId}/content returns original bytes
under agents.read. Drafts are owner-only. Accepted conversation attachments
follow the conversation's sharing rules. A running, unaccepted turn's documents
stay private. MCP uses get_agent_chat_attachment_content for bounded byte
chunks through the authorized connection.
Endpoints
System
- Health check:
GET /health - Get the calling credential:
GET /v1/me
Account
- Read your account profile:
GET /v1/account - Delete your account permanently:
DELETE /v1/account - Update your account profile:
PATCH /v1/account - Upload your account avatar:
PUT /v1/account/avatar - Remove your account avatar:
DELETE /v1/account/avatar - List your connected devices:
GET /v1/account/connected-devices - Disconnect a connected device:
DELETE /v1/account/connected-devices/{id} - List your browser sessions:
GET /v1/account/sessions - Sign out one browser session:
DELETE /v1/account/sessions/{id} - Sign out browser sessions:
POST /v1/account/sessions/revoke - Read notification preferences:
GET /v1/notifications/preferences - Update one email family preference:
PATCH /v1/notifications/preferences - Update notification role recipients:
PUT /v1/notifications/routing - Delete organization permanently:
DELETE /v1/organizations/{organizationId} - Read organization provider retention:
GET /v1/organizations/{organizationId}/data-controls - Update hosted Code Audit provider retention:
PATCH /v1/organizations/{organizationId}/data-controls - Upload organization logo:
PUT /v1/organizations/{organizationId}/logo - Remove organization logo:
DELETE /v1/organizations/{organizationId}/logo - Read organization settings:
GET /v1/organizations/{organizationId}/settings - Update organization name:
PATCH /v1/organizations/{organizationId}/settings - Rename organization URL:
POST /v1/organizations/{organizationId}/slug
Agent chats
- List your pending chat documents:
GET /v1/agent-chat-attachments - Upload and verify one private chat document:
POST /v1/agent-chat-attachments - Discard your unused chat document and revoke its private object:
DELETE /v1/agent-chat-attachments/{attachmentId} - Download original chat document bytes:
GET /v1/agent-chat-attachments/{attachmentId}/content
Inth Agent
- List readable Agent chats:
GET /v1/agent-chats - Delete an owned Agent chat:
DELETE /v1/agent-chats/{chatId} - Share an owned Agent chat:
POST /v1/agent-chats/{chatId}/share
Agent
- Start Agent chat:
POST /v1/agent-chats - Get Agent chat:
GET /v1/agent-chats/{chatId} - Send Agent message:
POST /v1/agent-chats/{chatId}/messages
API keys
- List API keys:
GET /v1/api-keys - Create API key:
POST /v1/api-keys - Delete API key:
DELETE /v1/api-keys/{keyId} - Roll API key:
POST /v1/api-keys/{keyId}/roll
Billing
- Get billing:
GET /v1/billing - Read billing configuration:
GET /v1/billing/configuration - Configure automatic credit purchases:
PUT /v1/billing/credit-auto-top-up - List lifetime settled credit consumption:
GET /v1/billing/credit-ledger - Read credit usage:
GET /v1/billing/credit-usage - Preview a credit purchase:
POST /v1/billing/credits/preview - Purchase credits:
POST /v1/billing/credits/purchase - Set billing email:
PUT /v1/billing/email - Read billing entitlements:
GET /v1/billing/entitlements - List billing invoices:
GET /v1/billing/invoices - Read billing invoice:
GET /v1/billing/invoices/{invoiceId} - Download invoice PDF:
GET /v1/billing/invoices/{invoiceId}/pdf - List billing payment methods:
GET /v1/billing/payment-methods - Choose default payment method:
PUT /v1/billing/payment-methods/default - Remove payment method:
POST /v1/billing/payment-methods/remove - Change a billing plan:
POST /v1/billing/plans/change - Preview a plan change:
POST /v1/billing/plans/preview - Create hosted billing portal link:
POST /v1/billing/portal - Read billing profile:
GET /v1/billing/profile - Replace billing identity:
PUT /v1/billing/profile - Cancel at period end:
POST /v1/billing/subscriptions/cancel - Undo scheduled cancellation:
POST /v1/billing/subscriptions/uncancel
Code Audit
- List connected repositories:
GET /v1/code-audit/repositories - Get scan request:
GET /v1/code-audit/scan-requests/{preparationId} - List scans:
GET /v1/code-audit/scans - Start scan:
POST /v1/code-audit/scans - Get scan:
GET /v1/code-audit/scans/{scanId} - Get scan issues:
GET /v1/code-audit/scans/{scanId}/issues - Read a prepared full-audit quote:
GET /v1/code-audit/scans/{scanId}/quote - Approve a prepared full audit:
POST /v1/code-audit/scans/{scanId}/quote/approve - Unlock scan report:
POST /v1/code-audit/scans/{scanId}/unlock
Feedback
- Submit agent feedback:
POST /v1/feedback
Inbox
- List Inbox items:
GET /v1/inbox - Get Inbox item:
GET /v1/inbox/{itemId} - Update Inbox item status:
PATCH /v1/inbox/{itemId} - Create GitHub issue:
POST /v1/inbox/{itemId}/github-issue
Integrations
- Read integration status:
GET /v1/integrations - List verified domain proofs:
GET /v1/integrations/domain-proofs - Start the GitHub App installation:
POST /v1/integrations/github/install - List GitHub installations:
GET /v1/integrations/github/installations - Sync one GitHub installation:
POST /v1/integrations/github/installations/{id}/sync - List repository link scan policies:
GET /v1/integrations/github/project-links/{id}/policies - List connected GitHub repositories:
GET /v1/integrations/github/repositories - Read a connected GitHub repository:
GET /v1/integrations/github/repositories/{id} - Update GitHub repository scan filters:
PATCH /v1/integrations/github/repositories/{id} - Link a repository to a project:
PUT /v1/integrations/github/repositories/{id}/project-link - List repository project links:
GET /v1/integrations/github/repositories/{id}/project-links - Turn pull request scans on or off:
PUT /v1/integrations/github/repositories/{id}/pull-request-scans - Remove scheduled scan policies:
POST /v1/integrations/github/scheduled-policies/cleanup - Sync the GitHub connection:
POST /v1/integrations/github/sync - List Search Console properties:
GET /v1/integrations/search-console/properties - List the latest cookie inventory:
GET /v1/website-audit/cookie-inventory
Members
- List invitations:
GET /v1/invitations - Invite member:
POST /v1/invitations - Cancel invitation:
DELETE /v1/invitations/{invitationId} - List members:
GET /v1/members - Remove member:
DELETE /v1/members/{memberId} - Update member role:
PATCH /v1/members/{memberId}
Organizations
- List organizations:
GET /v1/organizations - Create organization:
POST /v1/organizations - Get organization:
GET /v1/organizations/{organizationId}
Projects
- List projects:
GET /v1/projects - Create project:
POST /v1/projects - Get project:
GET /v1/projects/{projectId} - Delete project:
DELETE /v1/projects/{projectId} - Update project:
PATCH /v1/projects/{projectId} - List project vendors:
GET /v1/projects/{projectId}/vendors - Get project vendor:
GET /v1/projects/{projectId}/vendors/{vendorId} - Approve or ignore project vendor:
POST /v1/projects/{projectId}/vendors/{vendorId}/decision - Delete project website:
DELETE /v1/projects/{projectId}/websites/{websiteId} - List regions:
GET /v1/regions
Consent
- Read Consent configuration summary:
GET /v1/projects/{projectId}/consent - Update Consent settings:
PATCH /v1/projects/{projectId}/consent - Read Consent analytics breakdowns:
GET /v1/projects/{projectId}/consent/analytics - Read a complete stored configuration section:
GET /v1/projects/{projectId}/consent/configuration/{section} - Replace Consent translations:
PUT /v1/projects/{projectId}/consent/configuration/i18n - Replace selected IAB vendors:
PUT /v1/projects/{projectId}/consent/configuration/iab - Replace Consent policies:
PUT /v1/projects/{projectId}/consent/configuration/policies - Read runtime lifecycle metadata:
GET /v1/projects/{projectId}/consent/lifecycle - Update the Consent runtime backend:
POST /v1/projects/{projectId}/consent/lifecycle/update - Upgrade a legacy Consent runtime to v2 storage:
POST /v1/projects/{projectId}/consent/lifecycle/upgrade - Read Consent analytics totals:
GET /v1/projects/{projectId}/consent/overview - Search stored Consent records:
GET /v1/projects/{projectId}/consent/records - Delete the Consent runtime:
DELETE /v1/projects/{projectId}/consent/runtime - List runtime key metadata:
GET /v1/projects/{projectId}/consent/runtime-keys - Issue a Consent runtime key:
POST /v1/projects/{projectId}/consent/runtime-keys - Revoke a Consent runtime key:
DELETE /v1/projects/{projectId}/consent/runtime-keys/{keyId} - Rotate a Consent runtime key:
POST /v1/projects/{projectId}/consent/runtime-keys/{keyId}/rotate
Support
- Create support attachment upload:
POST /v1/support/attachments - Discard unused support attachment:
DELETE /v1/support/attachments/{attachmentId} - Download a support attachment:
GET /v1/support/attachments/{attachmentId}/content - Finalize support attachment upload:
POST /v1/support/attachments/{attachmentId}/finalize - List customer support conversations:
GET /v1/support/conversations - Create customer support conversation:
POST /v1/support/conversations - Read support conversation history:
GET /v1/support/conversations/{conversationId} - Close customer support conversation:
POST /v1/support/conversations/{conversationId}/close - Send customer support message:
POST /v1/support/conversations/{conversationId}/messages - Reopen customer support conversation:
POST /v1/support/conversations/{conversationId}/reopen - Share support conversation with organization:
POST /v1/support/conversations/{conversationId}/share
Website Audit
- List Website Audit history:
GET /v1/website-audit/scans - Get Website Audit status:
GET /v1/website-audit/scans/{scanId} - List cookies from a Website Audit:
GET /v1/website-audit/scans/{scanId}/cookies - Get Website Audit checks report:
GET /v1/website-audit/scans/{scanId}/report - Get Website Audit evidence:
GET /v1/website-audit/scans/{scanId}/results - Review Website Audit evidence:
POST /v1/website-audit/scans/{scanId}/review - Download private Website Audit screenshot:
GET /v1/website-audit/scans/{scanId}/screenshots/{captureId} - Discover Search Console websites:
POST /v1/website-audit/search-console/sync - List Website Audit targets:
GET /v1/website-audit/targets - Create a Website Audit target:
POST /v1/website-audit/targets - Get a Website Audit target:
GET /v1/website-audit/targets/{targetId} - Replace Website Audit target settings:
PUT /v1/website-audit/targets/{targetId} - Delete a Website Audit target:
DELETE /v1/website-audit/targets/{targetId} - Replace Website Audit policy pages:
PUT /v1/website-audit/targets/{targetId}/policy-pages - Start a Website Audit:
POST /v1/website-audit/targets/{targetId}/scans - Get domain ownership verification:
GET /v1/website-audit/targets/{targetId}/verification - Verify domain ownership:
POST /v1/website-audit/targets/{targetId}/verification