{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"AgentAddress API","version":"0.1.0","description":"Provision a persistent return address for an ephemeral AI agent. Receive HTTP callbacks and inbound email, then retrieve both from one durable ordered event queue.","license":{"name":"Proprietary","identifier":"LicenseRef-Proprietary"}},"externalDocs":{"description":"Agent-readable protocol guide","url":"https://agentaddress.dev/docs.md"},"servers":[{"url":"https://agentaddress.dev","description":"Configured AgentAddress deployment"}],"tags":[{"name":"Addresses","description":"Task-scoped return addresses and credentials"},{"name":"Events","description":"Inbound delivery, ordered polling, and acknowledgement"}],"paths":{"/api/v1/addresses":{"post":{"tags":["Addresses"],"operationId":"createAddress","summary":"Create an AgentAddress without prior setup","description":"Returns an inbound email address, secret-bearing HTTPS inbox URL, protected events URL, and one-time read token. Persist the complete response before the current run exits.","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAddress"}}}},"responses":{"201":{"description":"AgentAddress created. The read token is returned only once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAddressResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"description":"Provisioning rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/addresses/{addressId}":{"get":{"tags":["Addresses"],"operationId":"getAddress","summary":"Get AgentAddress metadata","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AddressId"}],"responses":{"200":{"description":"AgentAddress metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressResponse"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"tags":["Addresses"],"operationId":"deleteAddress","summary":"Delete an AgentAddress and its events","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AddressId"}],"responses":{"204":{"description":"AgentAddress and queued events deleted"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/addresses/{addressId}/events":{"get":{"tags":["Events"],"operationId":"listEvents","summary":"Poll the ordered event queue","description":"Returns events after the supplied sequence cursor. Set wait to long-poll when the queue is empty.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AddressId"},{"name":"after","in":"query","description":"Return events with a sequence greater than this cursor","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"wait","in":"query","description":"Long-poll duration in seconds","schema":{"type":"integer","minimum":0,"maximum":25,"default":0}}],"responses":{"200":{"description":"Ordered event page and next cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventPage"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/addresses/{addressId}/events/{eventId}/ack":{"post":{"tags":["Events"],"operationId":"acknowledgeEvent","summary":"Acknowledge a handled event","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/AddressId"},{"$ref":"#/components/parameters/EventId"}],"responses":{"200":{"description":"Acknowledged event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventResponse"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/inbox/{addressId}/{secret}":{"post":{"tags":["Events"],"operationId":"deliverEvent","summary":"Deliver an event to an AgentAddress","description":"The secret-bearing URL grants write-only delivery access. Send Idempotency-Key when retries are possible.","security":[],"parameters":[{"$ref":"#/components/parameters/AddressId"},{"name":"secret","in":"path","required":true,"description":"Write-only ingress credential returned inside endpoints.inbox_url","schema":{"type":"string","pattern":"^aa_ingress_"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Deduplicates retried deliveries within this AgentAddress","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEvent"}}}},"responses":{"200":{"description":"Previously queued idempotent event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventDeliveryResponse"}}}},"202":{"description":"Event accepted and queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventDeliveryResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"aa_read_...","description":"The read token returned exactly once when the AgentAddress is created"}},"parameters":{"AddressId":{"name":"addressId","in":"path","required":true,"schema":{"type":"string","pattern":"^addr_"}},"EventId":{"name":"eventId","in":"path","required":true,"schema":{"type":"string","pattern":"^evt_"}}},"schemas":{"CreateAddress":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":100,"description":"Human-readable purpose"},"task_id":{"type":"string","maxLength":200,"description":"Caller-defined task identifier"},"expires_in_seconds":{"type":"integer","minimum":60,"maximum":31536000,"description":"AgentAddress lifetime"}}},"Address":{"type":"object","required":["id","slug","name","email","createdAt"],"properties":{"id":{"type":"string","pattern":"^addr_"},"slug":{"type":"string"},"name":{"type":"string"},"taskId":{"type":"string"},"email":{"type":"string","format":"email"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},"CreateAddressResponse":{"type":"object","required":["address","credentials","endpoints"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"credentials":{"type":"object","required":["read_token","note"],"properties":{"read_token":{"type":"string","pattern":"^aa_read_","description":"Returned once; cannot be recovered"},"note":{"type":"string"}}},"endpoints":{"type":"object","required":["inbox_url","events_url","mcp_url"],"properties":{"inbox_url":{"type":"string","format":"uri","description":"Secret-bearing write-only HTTPS endpoint"},"events_url":{"type":"string","format":"uri","description":"Bearer-protected ordered event queue"},"mcp_url":{"type":"string","format":"uri"}}}}},"AddressResponse":{"type":"object","required":["address"],"properties":{"address":{"$ref":"#/components/schemas/Address"}}},"CreateEvent":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","default":"message.received"},"source":{"type":"string","default":"https"},"data":true,"metadata":{"type":"object","additionalProperties":{"type":"string"}},"dedupe_key":{"type":"string"}}},"Event":{"type":"object","required":["id","address_id","sequence","type","source","data","created_at"],"properties":{"id":{"type":"string","pattern":"^evt_"},"address_id":{"type":"string","pattern":"^addr_"},"sequence":{"type":"integer","minimum":1},"type":{"type":"string"},"source":{"type":"string"},"data":true,"metadata":{"type":"object","additionalProperties":{"type":"string"}},"dedupe_key":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"acknowledged_at":{"type":"string","format":"date-time"}}},"EventPage":{"type":"object","required":["events","next_cursor","has_more"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"next_cursor":{"type":"integer","minimum":0},"has_more":{"type":"boolean"}}},"EventResponse":{"type":"object","required":["event"],"properties":{"event":{"$ref":"#/components/schemas/Event"}}},"EventDeliveryResponse":{"type":"object","required":["event","duplicate"],"properties":{"event":{"$ref":"#/components/schemas/Event"},"duplicate":{"type":"boolean"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"responses":{"Error":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}