Skip to content
Extrovert Extrovert Docs

Overview

Extrovert API (0.1.8)

Section titled “Extrovert API (0.1.8)”

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.

When shared storage metering is available, authenticated mail responses include X-Extrovert-Storage-Status (available or unavailable) and X-Extrovert-Storage-Threshold. From 90 percent, X-Extrovert-Storage-Used-Bytes, X-Extrovert-Storage-Limit-Bytes, X-Extrovert-Storage-Cleanup-URL and X-Extrovert-Storage-Billing-URL provide advisory usage and human actions. Missing measurements are not zero. Native writes enforce the cap; reads and deletion remain available. Avoid repeating upgrade suggestions.

The surface has two planes:

  • Agent plane (/v1/..., excluding /v1/admin) uses a scoped agent key (pk_agent_...), connection access token (ev_access_...), or independent connection credential (ev_credential_...) as a Bearer token. Tenant and resource boundaries are derived from authenticated authority. Resource selectors narrow that boundary and never confer access.

  • Console / admin plane (/v1/admin/...) accepts a Clerk session or an explicitly authorized connection with the API resource audience. Full-account control uses account:admin; project managers use agent:manage and credential:delegate for project-only resource administration. The authorizer’s current role limits every operation. Delegated operations are attributed to the connection, not a human click. Full control defaults to a fixed 24-hour lease; refresh cannot extend it. Explicit Until revoked and independently surviving created credentials are supported. Private platform-operator authority is never granted through these connections.

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.36. 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

Section titled “ Authentication ”

AgentKey

Section titled “AgentKey ”

Per-agent capability key (pk_agent_...), API-audience connection token (ev_access_...), or independent connection credential (ev_credential_...) 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. Explicit full-account account:admin connections additionally authorize customer administrative operations, including their own approvals, within the authorizer’s current role. They do not authorize private platform-operator endpoints.

Security scheme type: http

ClerkSession

Section titled “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