Overview

Extrovert API (0.1.0-pre.6)

Extrovert gives an AI agent a persistent inbox that sends and receives mail. Create it in one call with an agent key whose permissions can expire or be revoked.

The surface has two planes:

• Agent plane (/v1/..., excluding /v1/admin) uses a permissioned agent key (pk_agent_...) as a Bearer token. customer_id is always derived from the key, never from client input, so the API is tenant-scoped by construction. The MCP server and TypeScript SDK map 1:1 onto this plane.

• Console / admin plane (/v1/admin/...) uses a Clerk session token and strictly customer-scoped. Backs the human console, including the shared-inbox viewer.

POST /v1/enroll and POST /v1/agent/sign-up are unauthenticated bootstrap endpoints. GET /healthz, GET /readyz, GET /openapi.yaml, and GET /openapi.json are public.

Review Loop contract. info.version, the SDK package version, and the SDK CONTRACT_VERSION all use 0.1.0-pre.6. The stable agent-facing Review Loop JSON shapes are published in the SDK contract module (CONTRACT_MANIFEST) and the Agent contract documentation.

• License: Proprietary
• OpenAPI version: 3.0.3

Authentication

AgentKey

Per-agent capability key (pk_agent_...) presented as Authorization: Bearer .... Scoped (mailbox:create / read / send / delete / quota / credentials; signup:verify; domain:manage; domain:purchase; commerce:request; review:act), revocable, and self-expiring. The customer/tenant and the fixed org/project binding are derived from the key, never from client input. Privileged scopes are opt-in and default-off: domain:manage gates onboarding for domains the customer already controls. commerce:request permits quotes, durable purchase/plan requests, and status reads but never approval or spend.

Security scheme type: http

ClerkSession

Clerk session token for the console/admin surface. Authority is derived from the identity’s membership in the org/project addressed in the PATH (/v1/admin/orgs/{org_id}/projects/{project_id}/…); there are no scope headers.

Security scheme type: http