# info.summary
Machine-first API for pull-based email events and controlled outbound.

# info.description
Canonical API surface for agent runtimes. Public boundary is provider-agnostic. OpenAPI can be fetched over HTTP GET/HEAD.

# paths./v1/examples/responses.get.responses.200.content.application/json.example.envelope.payload.text_preview
Hi, can your agent reply with SLA details?

# paths./v1/examples/responses.get.responses.200.content.application/json.example.events_poll_non_empty.events[].payload.text_preview
Hi, can your agent reply with SLA details?

# paths./v1/examples/responses.get.responses.200.content.application/json.example.thread_messages.messages[].text
Hi, can your agent reply with SLA details?

# paths./v1/examples/responses.get.responses.200.content.application/json.example.claim_x_start.suggested_post
I'm the human responsible for this THRD agent tenant.

thrd-claim:XXXXXXXXXXXX

/machine https://thrd.email/machine

# paths./v1/examples/responses.get.responses.200.content.application/json.example.claim_x_public_pending.suggested_post
I'm the human responsible for this THRD agent tenant.

thrd-claim:XXXXXXXXXXXX

/machine https://thrd.email/machine

# paths./v1/examples/responses.get.responses.200.content.application/json.example.por_required.challenge.prompt
Proof of Reasoning required (tier3 cold outbound).\nWords: agent inbox trust policy domain\nDigits: 123456\n\nAnswer format: "<letters>-<sum>".\nSteps: sort words alphabetically; take the first letter of each sorted word; append "-" + sum of all digits.

# paths./v1/examples/responses.get.responses.200.content.application/json.example.event_types.email.received.text_preview
Hi, can your agent reply with SLA details?

# paths./v1/public/agents/{ref}.get.summary
Public agent trust profile (shareable verification page data)

# paths./v1/public/agents/{ref}.get.parameters[].description
Agent reference: UUID (36 chars) or short base64url ref (22 chars).

# paths./v1/public/agents/{ref}/verify.get.summary
Public programmatic verification (boolean-ish + trust score)

# paths./v1/public/agents/{ref}/verify.get.parameters[].description
Agent reference: UUID (36 chars) or short base64url ref (22 chars).

# paths./v1/onboarding/instant.post.summary
Instant tenant + agent + API key provisioning (sandbox)

# paths./v1/onboarding/instant.post.description
Public self-serve bootstrap endpoint. Returns API key once. Persist it securely because it cannot be recovered later.

# paths./v1/onboarding/instant.post.requestBody.content.application/json.schema.properties.tenant_name.description
Optional tenant display name. If omitted or blank, server autogenerates one.

# paths./v1/onboarding/instant.post.requestBody.content.application/json.schema.properties.agent_name.description
Required sender display name (used in the From header).

# paths./v1/onboarding/instant.post.requestBody.content.application/json.schema.properties.inbox_prefix.description
Optional local-part base chosen by the agent. Server appends '-<4 alphanumeric>' to avoid duplicates.

# paths./v1/events.get.parameters[].description
Opaque cursor token (string-encoded int64 sequence).

# paths./v1/events.get.responses.200.content.application/json.schema.properties.events.items.properties.cursor.description
Opaque cursor token (string-encoded int64 sequence).

# paths./v1/events.get.responses.200.content.application/json.examples.non_empty.value.events[].payload.text_preview
Hi, can your agent reply with SLA details?

# paths./v1/threads/{id}/messages.get.summary
List messages in a thread (includes attachments refs)

# paths./v1/threads/{id}/messages.get.responses.200.content.application/json.example.messages[].text
Hi, can your agent reply with SLA details?

# paths./v1/outbound/{request_id}.get.summary
Get outbound request status by request_id

# paths./v1/reply.post.requestBody.content.application/json.schema.properties.cc.description
Additional CC recipients. Replies preserve historical thread CC and also keep recipients from the latest inbound To-line (reply-all behavior). Tier 1 (sandbox) may not add new CC addresses in cc[]; it can only keep thread history automatically.

# paths./v1/reply.post.requestBody.content.application/json.schema.properties.security_ack_token.description
Required only when source inbound message has high prompt-injection risk on Tier 2/3. Obtain via POST /v1/security/ack.

# paths./v1/send.post.summary
Start new outbound (Tier2+ policy-gated)

# paths./v1/send.post.requestBody.content.application/json.schema.properties.por_token.description
PoR token provided by server when required.

# paths./v1/send.post.requestBody.content.application/json.schema.properties.source_message_id.description
Optional inbound message context used for prompt-injection policy gating.

# paths./v1/send.post.requestBody.content.application/json.schema.properties.security_ack_token.description
Required on Tier 2/3 when source_message_id has high prompt-injection risk. Obtain via POST /v1/security/ack.

# paths./v1/send.post.responses.428.description
Proof of Reasoning or Security Ack required

# paths./v1/send.post.responses.428.content.application/json.examples.por_required.value.challenge.prompt
Proof of Reasoning required (tier3 cold outbound).\nWords: agent inbox trust policy domain\nDigits: 123456\n\nAnswer format: "<letters>-<sum>".\nSteps: sort words alphabetically; take the first letter of each sorted word; append "-" + sum of all digits.

# paths./v1/billing/checkout/self.post.summary
Create Paddle Checkout URL for current tenant subscription

# paths./v1/billing/checkout/self.post.description
Authenticated agent flow. Returns a Paddle Checkout URL the agent can forward to a human for payment. Supports Sandbox Starter (plan=sandbox) and higher-tier upgrades. Requires threads:read scope.

# paths./v1/usage.get.summary
Get monthly email usage and current quota state

# paths./v1/usage.get.description
Returns monthly sent-email units (recipient-based), remaining quota, warning/limit state, reset timestamp, and a machine-readable upgrade offer when relevant.

# paths./v1/wake/webhook.get.summary
Get wake webhook configuration for current agent

# paths./v1/wake/webhook.get.description
Returns the current wake webhook status. Wake webhooks receive signed inbox.pending pings so runtimes can pull /v1/events immediately.

# paths./v1/wake/webhook.put.summary
Create or update wake webhook for current agent

# paths./v1/wake/webhook.put.description
Upserts webhook URL and optional enabled flag. Returns signing_secret only on create or when rotate_secret=true.

# paths./v1/claim/x/start.post.description
Authenticated agent flow. Returns a human-facing claim URL. Human completes verification by posting the challenge on X and connecting via OAuth2.

# paths./v1/claim/x/start.post.responses.200.content.application/json.example.suggested_post
I'm the human responsible for this THRD agent tenant.

thrd-claim:XXXXXXXXXXXX

/machine https://thrd.email/machine

# paths./v1/claim/x/status.get.summary
Get Human Claiming status (X) for current tenant

# paths./v1/claim/x/revoke.post.description
Authenticated agent flow. Revokes the most recent claim for this tenant (or a provided token).

# paths./v1/claim/x/public/{token}.get.summary
Public claim metadata (X) used by web claim page

# paths./v1/claim/x/public/{token}.get.responses.200.content.application/json.example.suggested_post
I'm the human responsible for this THRD agent tenant.

thrd-claim:XXXXXXXXXXXX

/machine https://thrd.email/machine

# paths./v1/claim/x/authorize.get.description
Used by the web claim UI. Redirects to X authorization screen.

# paths./v1/claim/x/callback.get.description
Exchanges code, searches latest tweets for challenge, then redirects to thrd.email claim success/failure pages.

# paths./v1/messages/{id}/security.get.summary
Get prompt-injection security assessment for a message

# paths./v1/security/ack.post.summary
Create temporary security ack token for high-risk inbound context

# paths./v1/trust/score.get.summary
Get trust score (agent reputation factors)

# paths./v1/trust/score.get.description
Returns a transparent, evolving trust score derived from verification and recent sending outcomes. Used to tune spam friction (e.g., PoR requirements).

# paths./v1/agents/me.patch.description
Authenticated agent flow. Updates the name used in outbound From: headers.

# paths./v1/feedback/record.get.description
Public, recipient-facing. Validates signed token and records feedback. Redirects to thrd.email.

# paths./v1/inbound.post.summary
Canonical inbound ingress (standard.v1 payload)

# paths./v1/inbound.post.requestBody.content.application/json.schema.properties.payload.oneOf[].description
Legacy/raw payload mode. Prefer standard.v1 payload.

# webhooks.inbound_provider_event.post.summary
Inbound provider callback into Thrd (mapped to standard.v1)

# components.securitySchemes.bearerAuth.description
Agent API key: thrd.<prefix>.<secret>