{ "openapi": "3.1.0", "info": { "title": "HelpfulAI ACP (agent communications)", "version": "0.1.0", "summary": "Agent phone numbers, inbound SMS/voice/email events, agent calendars and private agent meshes.", "description": "The communications APIs HelpfulAI runs today, as Supabase Edge Functions. Each path is one\nfunction under `supabase/functions//`. Most answer `POST` with a JSON body; the public\nagent-calendar resources (`agent-calendar-availability`, `-bookings`, `-events`, `-grants`, `-shares`)\nuse GET / POST / PATCH / DELETE, with the calendar's owner in the query string.\n\nThis spec is checked against the handlers by `node scripts/check-openapi-specs.mjs`\n(TypeScript AST, no regex): the set of paths must equal the in-scope functions (the checker's\n`ACP_HANDLER_SCOPE` in `scripts/openapi/acp-scope/`, not this file) that register a `serve(...)` handler, each operation's\nmethod must be the one the handler guards on, each `x-handler.contracts` schema must be the\noperation's request body (or a `oneOf` member of it), and its top-level keys, required keys,\nenum or union variants must equal the zod schema or action set the handler validates with. Response bodies are documented\nfrom the code and are not machine-checked yet.\n\nLayout: this metadata root and one file per path, tag and schema area under `openapi/acp/`.\nThe index is generated from those directories at build time; adding a path or schema does not\nedit this root. `node scripts/check-openapi-specs.mjs --bundle openapi/acp.yaml` prints the\nsingle-file document used by the developer portal.\n\nErrors from `_shared/errorResponse.ts` are `{ \"error\": string, \"code\"?: string, \"details\"?: object }`.\nCarrier webhooks (Telnyx, LiveKit, Resend) answer plain text on some failures.\n", "license": { "name": "Proprietary", "identifier": "LicenseRef-HelpfulAI-Proprietary" } }, "servers": [ { "url": "https://{projectRef}.supabase.co/functions/v1", "variables": { "projectRef": { "description": "Supabase project. `mqqsoutginqsajeuttyp` is the dev project; `bqrrisyunrqjqefgvncr` is production.", "default": "mqqsoutginqsajeuttyp", "enum": [ "mqqsoutginqsajeuttyp", "bqrrisyunrqjqefgvncr" ] } } } ], "tags": [ { "name": "Phone numbers", "description": "Quote, approve, activate, provision and cancel an avatar's exact phone number." }, { "name": "Inbound events", "description": "Signed vendor webhooks that deliver SMS, voice and email to an avatar." }, { "name": "Email", "description": "The assistant mailbox reply path." }, { "name": "Calendar", "description": "Appointment calendars, delegated calendar setup, and agent calendars (agentcalendar.one)." }, { "name": "Agent claims", "description": "An agent with no account claims a .one resource; its human approves once; it collects an API key once (#5342)." }, { "name": "Agent mesh", "description": "An organization's private agent mesh (agentsmesh.one): quote, approve, status, and enroll,\nbind or revoke its members. Callable with a developer key (`developerKey`); a key always\nacts on its own organization.\n" } ], "paths": { "/acp-claim-approve": { "post": { "operationId": "decideAcpClaim", "tags": [ "Agent claims" ], "summary": "Read, approve or decline an agent's claim (the approve page)", "description": "`view` is open to anyone with the link; with `organization_id` and a company admin's JWT it\nadds the quote and price. `approve` (company admin of `organization_id`) is single-use:\nincluded in the plan → the product's order runs now (200, phase `approved`); billed → 402\n`payment_required` with `details.checkout_url` (Stripe Checkout) and nothing ordered; an\nunconfigured price → 409 `price_unavailable`; an uncertain order → 503 `order_uncertain`, the\nclaim reopened. `deny` needs any signed-in user.\n", "security": [ { "supabaseUser": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/acp-claim-approve/handler.ts", "const": "ApproveBody", "schema": "ClaimApproveRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimApproveRequest" } } } }, "responses": { "200": { "description": "The claim as it now stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimDecision" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/acp-claim": { "get": { "operationId": "readAcpClaim", "tags": [ "Agent claims" ], "summary": "Start a claim from a URL, poll a claim, or read a site's llms.txt", "description": "Anonymous (#5342). Exactly one of:\n`?start=&agent_name=…[&display_name&time_zone]` starts a claim (the same as POST, for\nassistants whose browsing can only fetch a URL; 201 `ClaimStarted`), `?poll=`\nanswers where it stands (`ClaimPoll`; the API key on the first ready poll only; 429\n`slow_down` when polled too fast), `?site=` the site's llms.txt (`text/markdown`).\n", "security": [], "parameters": [ { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "calendar" ] } }, { "name": "agent_name", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "display_name", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "time_zone", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "name": "poll", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "site", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "calendar" ] } } ], "responses": { "200": { "description": "The claim's state, or the llms.txt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPoll" } }, "text/markdown": { "schema": { "type": "string" } } } }, "201": { "description": "Started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimStarted" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "startAcpClaim", "tags": [ "Agent claims" ], "summary": "Start a claim on a .one resource (calendar first)", "description": "Anonymous, rate-limited per caller address (10 an hour). Records a pending claim; nothing is ordered or charged.", "security": [], "x-handler": { "contracts": [ { "file": "supabase/functions/acp-claim/handler.ts", "const": "ClaimBody", "schema": "ClaimRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRequest" } } } }, "responses": { "201": { "description": "Started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimStarted" } } } }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/acp-mcp": { "post": { "operationId": "acpMcp", "tags": [ "Agent claims" ], "summary": "The ACP remote MCP server (Streamable HTTP), calendar tools first", "description": "One MCP endpoint (#5342 slice 5b), stateless: POST a JSON-RPC message, get `application/json`\nback (no SSE, no sessions; GET/DELETE are 405). Tools: request_calendar, calendar_status\n(→ acp-claim), get_available_slots (→ agent-calendar-availability), list_events, create_event\n(→ agent-calendar-events), create_booking, reschedule_booking, cancel_booking\n(→ agent-calendar-bookings). The caller's `hpx_` bearer is forwarded to those functions.\n401 carries `WWW-Authenticate: Bearer`; an Origin that is not allowed is 403; an unsupported\n`MCP-Protocol-Version` is 400. OAuth 2.1 for the Claude.ai / ChatGPT connectors is pending.\n", "security": [ { "developerKey": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/acp-mcp/handler.ts", "const": "McpMessageBody", "schema": "McpMessage" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/McpMessage" }, { "type": "array", "items": { "$ref": "#/components/schemas/McpMessage" } } ] } } } }, "responses": { "200": { "description": "The JSON-RPC response(s).", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Notifications only; no body." }, "400": { "description": "Parse error, an invalid request, an unsupported MCP-Protocol-Version, or a header that disagrees with the body." }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agent-calendar-approve": { "post": { "operationId": "approveAgentCalendarRequest", "tags": [ "Calendar" ], "summary": "Approve or dismiss an agent's calendar request", "description": "A company admin's click. The request moves `proposed` to `approved` through the caller's RLS\nclient, then the calendar is ordered as that admin: the native identity, the CalDAV principal\nand calendar, the read share and the `calendar` routing row. A re-click answers the settled\nstate (202 creating, or 200 completed with `store_calendar_href`).\n", "security": [ { "supabaseUser": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-approve/request.ts", "const": "CalendarApproveBody", "schema": "CalendarApproveRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarApproveRequest" } } } }, "responses": { "200": { "description": "The click was recorded, or the request had already completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "approved": { "type": "boolean", "const": true }, "cancelled": { "type": "boolean", "const": true }, "requestId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "store_calendar_href": { "type": [ "string", "null" ] }, "result_code": { "type": [ "string", "null" ] } }, "required": [ "requestId" ] } } } }, "202": { "description": "The calendar is being created." }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } } } }, "/agent-calendar-availability": { "get": { "operationId": "agentCalendarAvailability", "tags": [ "Calendar" ], "summary": "The free slots of one day on an agent calendar", "description": "From the native booking core (the calendar's slot rules minus confirmed bookings); on a\n`delegated_google` calendar (#5340) the Google calendar's busy time (freeBusy) is removed too,\nand a Google token that is revoked or lacks the calendar scope is 409\n`google_reconnect_required` / `google_scope_missing` (fail closed). Name the\nowner with exactly one of `avatar_type` or `external_agent_id`; the organization is the key's.\n", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "day", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The day's free slots.", "content": { "application/json": { "schema": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "start_at": { "$ref": "#/components/schemas/Instant" }, "end_at": { "$ref": "#/components/schemas/Instant" } } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agent-calendar-bookings": { "get": { "operationId": "listAgentCalendarBookings", "tags": [ "Calendar" ], "summary": "List bookings on an agent calendar in a window (at most 92 days)", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "from", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Instant" } }, { "name": "to", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Instant" } } ], "responses": { "200": { "description": "The bookings overlapping the window.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createAgentCalendarBooking", "tags": [ "Calendar" ], "summary": "Book a slot on an agent calendar", "description": "A developer key's booking is charged one credit (refunded when the core refuses); the avatar's own (service lane) is not. `Idempotency-Key` is required: a retry\nwith the same key and slot answers 200 `replayed: true` and charges nothing again. The booking\nis projected onto the agent's CalDAV calendar (`projection_state`) and `booking.created` is\nsent to the owner's webhook. On a `delegated_google` calendar (#5340) it is projected into the\nGoogle calendar instead (same states; a Google-side edit is `conflict`, never overwritten), and\na slot Google shows busy is 409 `slot_taken` before any charge.\n", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-bookings/handler.ts", "const": "CreateBookingBody", "schema": "CreateBookingRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingRequest" } } } }, "responses": { "200": { "description": "A replay of the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResult" } } } }, "201": { "description": "Booked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "moveAgentCalendarBooking", "tags": [ "Calendar" ], "summary": "Move a booking (revision-guarded)", "description": "A stale `expected_revision` is 409 `stale_revision` with `details.current_revision`; a taken slot is 409 `slot_taken`.", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-bookings/handler.ts", "const": "MoveBookingBody", "schema": "MoveBookingRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveBookingRequest" } } } }, "responses": { "200": { "description": "Moved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "cancelAgentCalendarBooking", "tags": [ "Calendar" ], "summary": "Cancel a booking (revision-guarded)", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "booking_id", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "expected_revision", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agent-calendar-events": { "get": { "operationId": "readAgentCalendarEvent", "tags": [ "Calendar" ], "summary": "Read one event on the agent's calendar", "description": "Answers the VCALENDAR text (managed, CalDAV) or the Google event's fields (`delegated_google`,\n#5340, routed to the Google calendar) and its ETag (also in the `ETag` header).\n", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "uid", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "from", "in": "query", "required": false, "description": "List: range start (required without uid).", "schema": { "$ref": "#/components/schemas/Instant" } }, { "name": "to", "in": "query", "required": false, "description": "List: range end (required without uid).", "schema": { "$ref": "#/components/schemas/Instant" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 500 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "The event, or a page of the range's events.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/StoredEvent" }, { "$ref": "#/components/schemas/EventPage" } ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createAgentCalendarEvent", "tags": [ "Calendar" ], "summary": "Create an event on the agent's own CalDAV calendar", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-events/handler.ts", "const": "CreateEventBody", "schema": "CreateEventRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventRequest" } } } }, "responses": { "201": { "description": "Created (`uid` is `evt-`; on a delegated Google calendar `evt` + 32 hex, a Google event id).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventWritten" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "replaceAgentCalendarEvent", "tags": [ "Calendar" ], "summary": "Replace an event (If-Match its ETag)", "description": "Without `If-Match` 428; a moved ETag 412. A booking's projection (a uuid UID; on Google `bk` + 32 hex) is 409 `booking_event`.", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" } } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-events/handler.ts", "const": "UpdateEventBody", "schema": "UpdateEventRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEventRequest" } } } }, "responses": { "200": { "description": "Replaced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventWritten" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "412": { "$ref": "#/components/responses/Error" }, "428": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteAgentCalendarEvent", "tags": [ "Calendar" ], "summary": "Delete an event (If-Match its ETag)", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "uid", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200 } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uid": { "type": "string" }, "deleted": { "type": "boolean", "const": true } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "412": { "$ref": "#/components/responses/Error" }, "428": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agent-calendar-feed/{feed_token}.ics": { "get": { "operationId": "readAgentCalendarFeed", "tags": [ "Calendar" ], "summary": "The private ICS feed of one shared agent calendar (subscribe in Google, Apple, Outlook)", "description": "The `acf_…` token minted by `agent-calendar-shares` is the last path segment (calendar clients\ncannot send a header or a JWT; Supabase routes the sub-path to the function). The token is stored only as its SHA-256 and names one calendar; a revoked share, an\nunknown token or a calendar that is no longer active answers 404. The body is one RFC 5545\nVCALENDAR (METHOD:PUBLISH) of the calendar's events from 30 days back to 365 days ahead,\nwithout cancelled events or alarms. Read-only: any other method is 405. `ETag` is a strong\nvalidator over the body; `If-None-Match` answers 304. Rate-limited per client address and per\ntoken (429 with `Retry-After`).\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/FeedToken" }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The calendar.", "headers": { "ETag": { "schema": { "type": "string" } }, "Last-Modified": { "schema": { "type": "string" } } }, "content": { "text/calendar": { "schema": { "type": "string" } } } }, "304": { "description": "The client's copy (If-None-Match) is current." }, "404": { "description": "Not a live share's token." }, "405": { "description": "The feed is read-only (Allow: GET, HEAD)." }, "429": { "description": "Rate limited (Retry-After)." }, "500": { "description": "Unexpected failure." }, "503": { "description": "The calendar store did not answer (Retry-After)." } } }, "head": { "operationId": "headAgentCalendarFeed", "tags": [ "Calendar" ], "summary": "The feed's validators without its body", "security": [], "parameters": [ { "$ref": "#/components/parameters/FeedToken" } ], "responses": { "200": { "description": "The feed's headers (ETag, Last-Modified)." }, "304": { "description": "The client's copy is current." }, "404": { "description": "Not a live share's token." }, "429": { "description": "Rate limited." }, "503": { "description": "The calendar store did not answer." } } } }, "/agent-calendar-grants": { "get": { "operationId": "listAgentCalendarGrants", "tags": [ "Calendar" ], "summary": "Who may book on an agent calendar", "description": "The key's user must be a company admin or manager (checked in SQL).", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" } ], "responses": { "200": { "description": "Current staff grants.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/Grant" } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "putAgentCalendarGrant", "tags": [ "Calendar" ], "summary": "Grant or change a staff member's booking rights", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-grants/handler.ts", "const": "GrantBody", "schema": "GrantRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRequest" } } } }, "responses": { "200": { "description": "The grant now in force.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "revokeAgentCalendarGrant", "tags": [ "Calendar" ], "summary": "Revoke a staff member's booking rights", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "user_id", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "const": true }, "user_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agent-calendar-projector": { "post": { "operationId": "runAgentCalendarProjectorPass", "tags": [ "Calendar" ], "summary": "Re-drive booking projections and detect external edits on agent calendars", "description": "Service-only scheduled pass. For each active agent calendar's upcoming bookings: a pending or\nfailed projection is written again; a projected one is read back, and an event changed or\ndeleted on the store by someone else becomes `conflict` (never overwritten) and sends\n`booking.conflict` to the owner's webhook.\n", "security": [ { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-projector/index.ts", "const": "Body", "schema": "CalendarPassRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarPassRequest" } } } }, "responses": { "200": { "description": "The pass summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectorSummary" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agent-calendar-quote": { "post": { "operationId": "quoteAgentCalendar", "tags": [ "Calendar" ], "summary": "The exact calendar an agent's calendar approval card offers", "description": "The avatar worker's service-role call for a recorded `proposed` request. Computes and checks\nthe calendar the admin's click would get; creates nothing.\n", "security": [ { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-quote/index.ts", "const": "Body", "schema": "CalendarQuoteRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarQuoteRequest" } } } }, "responses": { "200": { "description": "The quote (`available: false` names its `reason`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarQuote" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/agent-calendar-release-scheduler": { "post": { "operationId": "runAgentCalendarReleasePass", "tags": [ "Calendar" ], "summary": "Release the calendars of organizations unpaid past the 7-day grace", "description": "Service-only daily pass. Default-off: 423 until `AGENT_CALENDAR_RELEASE_ENABLED=1` is in the\nVault platform store (`vendor`), because a release destroys the calendar's store principal.\n", "security": [ { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-release-scheduler/index.ts", "const": "Body", "schema": "CalendarPassRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarPassRequest" } } } }, "responses": { "200": { "description": "The pass summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LapseSummary" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "423": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agent-calendar-shares": { "get": { "operationId": "listAgentCalendarShares", "tags": [ "Calendar" ], "summary": "The calendar's live shares (never a token)", "description": "Three callers: a developer key (owner in the query), the avatar worker's service key\n(`organization_id`, the owner, and `requested_by`, a company admin), or a signed-in company\nadmin's Supabase JWT from the staff workspace (`organization_id` + `identity_id`).\n", "security": [ { "developerKey": [] }, { "serviceRole": [] }, { "supabaseUser": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "requested_by", "in": "query", "required": false, "description": "Service lane: the session's signed-in user; must be a company admin.", "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "identity_id", "in": "query", "required": false, "description": "Staff lane: the calendar's native identity (with organization_id).", "schema": { "$ref": "#/components/schemas/Uuid" } } ], "responses": { "200": { "description": "Live shares, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "shares": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarShare" } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createAgentCalendarShare", "tags": [ "Calendar" ], "summary": "Share the calendar with an email address", "description": "Mints a private ICS feed URL (returned here once, and emailed; stored only as a SHA-256) and\nemails the subscribe links (Google Calendar, `webcal://` for Apple Calendar and Outlook, and\nthe https URL). With `caldav_account` (the recipient's own store login, `local@domain`) the\ncalendar's WebDAV ACL also grants that principal read. Sharing again with the same email\nrotates the URL (the old one answers 404). A failed email keeps the share\n(`email_status: failed`). At most 20 new shares per calendar an hour (429).\n", "security": [ { "developerKey": [] }, { "serviceRole": [] }, { "supabaseUser": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "requested_by", "in": "query", "required": false, "description": "Service lane: the session's signed-in user; must be a company admin.", "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "identity_id", "in": "query", "required": false, "description": "Staff lane: the calendar's native identity (with organization_id).", "schema": { "$ref": "#/components/schemas/Uuid" } } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-shares/handler.ts", "const": "CreateShareBody", "schema": "CreateShareRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareRequest" } } } }, "responses": { "201": { "description": "Shared. The feed URLs appear only in this answer and the email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedShare" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "revokeAgentCalendarShare", "tags": [ "Calendar" ], "summary": "Revoke a share (its feed URL answers 404 from then on)", "description": "A share with CalDAV access also leaves the calendar's ACL; if the store cannot be reached that is 503 `acl_not_updated` (the feed is already revoked) and a repeat DELETE retries it.", "security": [ { "developerKey": [] }, { "serviceRole": [] }, { "supabaseUser": [] } ], "parameters": [ { "$ref": "#/components/parameters/OwnerAvatarType" }, { "$ref": "#/components/parameters/OwnerExternalAgentId" }, { "$ref": "#/components/parameters/ServiceOrganizationId" }, { "name": "requested_by", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "identity_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "share_id", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "revoked": { "type": "boolean", "const": true } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agent-calendar-status": { "post": { "operationId": "agentCalendarStatus", "tags": [ "Calendar" ], "summary": "Where an agent's own calendar stands", "description": "The avatar worker's service-role read. Never the credential.", "security": [ { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-calendar-status/index.ts", "const": "Body", "schema": "CalendarStatusRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarStatusRequest" } } } }, "responses": { "200": { "description": "The live calendar's state and readiness.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarStatus" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/agent-mesh-approve": { "post": { "operationId": "approveAgentMeshRequest", "tags": [ "Agent mesh" ], "summary": "Approve or dismiss the organization's agent mesh request", "description": "The approval card's click, or the same decision by a developer key. A request is opened by the\norganization's avatar; approving it provisions the mesh (up to ~90 s) and enrolls the\nrequesting avatar as the first member. The outcome is recorded on the request.\n\n- A signed-in company admin's JWT moves the request through their own RLS client.\n- A developer key may approve or dismiss only a request its own organization holds and that\n exists (another organization's request is 404). It acts on behalf of the admin who created\n the key: the order still requires that person to be a company admin of the organization\n (403 otherwise), and each click is recorded in `developer_audit_events` before the request\n moves (503 when that record cannot be written).\n", "security": [ { "developerKey": [] }, { "supabaseUser": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-mesh-approve/keyClick.ts", "const": "MeshApproveBody", "schema": "MeshApproveRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshApproveRequest" } } } }, "responses": { "200": { "description": "The click was recorded; a re-click on a completed request answers its `slug`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "approved": { "type": "boolean", "const": true }, "cancelled": { "type": "boolean", "const": true }, "requestId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "completed" }, "slug": { "type": [ "string", "null" ] }, "result_code": { "type": [ "string", "null" ] } }, "required": [ "requestId" ] } } } }, "202": { "description": "Already approved; the mesh is being created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "approved": { "type": "boolean", "const": true }, "requestId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "creating" } }, "required": [ "approved", "requestId", "status" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agent-mesh-enroll": { "post": { "operationId": "enrollAgentMeshMember", "tags": [ "Agent mesh" ], "summary": "Invite an agent to the mesh, or re-mint an invited member's token", "description": "Two forms. **Invite** (`MeshInviteRequest`): admits an avatar or an external agent and returns\na one-use bootstrap token, valid 24 h and shown once, for `agentmesh-node join`. **Re-mint**\n(`MeshMemberRef`): a fresh token for an existing invited member; no new row.\n\nA developer key may use both forms, always on its own organization (a body `organization_id`\nis ignored). A signed-in company admin may invite. The service role (cowork's mesh runner)\nmay use both.\n", "security": [ { "developerKey": [] }, { "supabaseUser": [] }, { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-mesh-enroll/index.ts", "const": "InviteBody", "schema": "MeshInviteRequest" }, { "file": "supabase/functions/agent-mesh-enroll/index.ts", "const": "ReissueBody", "schema": "MeshMemberRef" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/MeshInviteRequest" }, { "$ref": "#/components/schemas/MeshMemberRef" } ] } } } }, "responses": { "201": { "description": "The member and its bootstrap token (`Cache-Control: no-store`).", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshEnrollment" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error", "description": "`no_mesh`, or no such member.", "__uniqueRefKey": "#/components/responses/Error__0" }, "409": { "$ref": "#/components/responses/Error", "description": "`mesh_not_active`, or the principal is already enrolled.", "__uniqueRefKey": "#/components/responses/Error__1" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error", "description": "`control_plane_unreachable`.", "__uniqueRefKey": "#/components/responses/Error__2" } } }, "put": { "operationId": "confirmAgentMeshMemberJoined", "tags": [ "Agent mesh" ], "summary": "Bind a member's publish role once its node has joined", "description": "After `agentmesh-node join` with the member's token: looks the node up on the control plane\nand binds the member's own `a2a://` publish role to its peer id. 409 `not_joined`\nbefore the join. The service role, or a developer key on its own organization (the external\nagent's developer calls this after the join, as cowork does for avatars).\n", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-mesh-enroll/index.ts", "const": "ReissueBody", "schema": "MeshMemberRef" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshMemberRef" } } } }, "responses": { "200": { "description": "The member is enrolled under its peer id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshJoined" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "revokeAgentMeshMember", "tags": [ "Agent mesh" ], "summary": "Revoke a member of the mesh", "description": "Bans the member's node when its peer id is known, revokes its unused token otherwise, and marks\nthe member `revoked`. A developer key (its own organization), a signed-in company admin, or\nthe service role.\n", "security": [ { "developerKey": [] }, { "supabaseUser": [] }, { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-mesh-enroll/index.ts", "const": "RevokeBody", "schema": "MeshRevokeRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshRevokeRequest" } } } }, "responses": { "200": { "description": "The member is revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshRevoked" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } } } }, "/agent-mesh-quote": { "post": { "operationId": "quoteAgentMesh", "tags": [ "Agent mesh" ], "summary": "Quote the organization's private agent mesh", "description": "Search only, never a side effect: the mesh's public name (`slug`), the host it would run on\nand the plan gate, plus the existing mesh if there is one. A mesh is provisioned only when a\nrequest is approved (`/agent-mesh-approve`).\n\nA developer key is always quoted for its own organization; a body `organization_id` is\nignored. The service role (the avatar worker) names the organization in the body.\n", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-mesh-quote/index.ts", "const": "Body", "schema": "MeshQuoteRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshQuoteRequest" } } } }, "responses": { "200": { "description": "The quote. `available` is false with a `reason` when the mesh cannot be ordered now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshQuote" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/agent-mesh-status": { "post": { "operationId": "getAgentMeshStatus", "tags": [ "Agent mesh" ], "summary": "Read where the organization's agent mesh stands", "description": "Reads, never acts; never a credential. POST with a body, like the other ACP reads. A developer\nkey reads its own organization's mesh; a body `organization_id` is ignored. The service role\n(worker, cowork) names the organization in the body.\n", "security": [ { "developerKey": [] }, { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/agent-mesh-status/index.ts", "const": "Body", "schema": "MeshStatusRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshStatusRequest" } } } }, "responses": { "200": { "description": "The mesh and its live members.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeshStatus" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error", "description": "`no_mesh`: the organization has no agent mesh.", "__uniqueRefKey": "#/components/responses/Error__3" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/appointment-calendar-action": { "post": { "operationId": "redeemAppointmentAction", "tags": [ "Calendar" ], "summary": "Redeem a signed, short-lived appointment cancellation proof", "description": "Public. The signed claims, never request fields, select the calendar and event.", "security": [], "x-handler": { "contracts": [ { "file": "supabase/functions/appointment-calendar-action/index.ts", "const": "Body", "schema": "AppointmentActionRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentActionRequest" } } } }, "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoSendResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "424": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/appointment-calendar": { "post": { "operationId": "appointmentCalendar", "tags": [ "Calendar" ], "summary": "Selected Google appointment calendar (no-send setup, sync, staff follow-up, reschedule, cancel)", "description": "One action per call. A signed-in staff member calls with their JWT; the avatar worker may\ncall with the service key for `staff_queue`, `link_contact`, `dismiss`,\n`available_slots`, `issue_reschedule_proof` and `reschedule`, naming the staff member in\n`actorUserId`. Every action re-checks membership, the receptionist and its owner's\nconnected Google Calendar. Nothing here sends a message (`noSend: true`).\n", "security": [ { "supabaseUser": [] }, { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/appointment-calendar/index.ts", "const": "ACTIONS", "schema": "AppointmentCalendarRequest", "property": "action" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppointmentCalendarRequest" } } } }, "responses": { "200": { "description": "The action's result. Shape depends on `action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoSendResult" } } } }, "201": { "description": "`select_calendar` created the calendar identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoSendResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "424": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/avatar-inbound-email": { "post": { "operationId": "receiveInboundEmail", "tags": [ "Inbound events" ], "summary": "Resend inbound email webhook", "description": "Verifies the Svix signature, fetches the body from Resend and claims the message before\nacknowledging. Mail for a domain outside `AVATAR_INBOUND_EMAIL_DOMAINS` (default\n`avatars.helpfulai.app`) is acked and ignored. `x-worker-secret` selects the redrive lane.\n", "security": [ { "svixSignature": [] }, { "workerSecret": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/avatar-inbound-email/index.ts", "const": "ResendEvent", "schema": "ResendWebhookEvent" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ResendWebhookEvent" }, { "$ref": "#/components/schemas/InboundRedriveRequest" } ] } } } }, "responses": { "200": { "description": "Claimed, duplicate, or skipped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundReceipt" } } } }, "401": { "description": "Signature or worker secret rejected." }, "503": { "description": "Body fetch or claim failed; Resend redelivers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundReceipt" } } } } } } }, "/avatar-inbound-sms": { "post": { "operationId": "receiveInboundSms", "tags": [ "Inbound events" ], "summary": "Telnyx inbound SMS webhook", "description": "Verifies the Ed25519 signature, journals instance controls and usage, then claims the\nmessage durably before acknowledging. Non-`message.received` events are acked and skipped.\nA request with `x-worker-secret` is the reaper's redrive of a stalled claim instead.\n", "security": [ { "telnyxSignature": [] }, { "workerSecret": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/avatar-inbound-sms/index.ts", "const": "TelnyxEvent", "schema": "TelnyxMessagingEvent" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TelnyxMessagingEvent" }, { "$ref": "#/components/schemas/InboundRedriveRequest" } ] } } } }, "responses": { "200": { "description": "Claimed, duplicate, or skipped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundReceipt" } } } }, "401": { "description": "Signature or worker secret rejected." }, "503": { "description": "The claim or journal could not be written; Telnyx redelivers." } } } }, "/avatar-instance-phone-approve": { "post": { "operationId": "approveInstancePhoneQuote", "tags": [ "Phone numbers" ], "summary": "Approve an exact instance quote", "description": "Binds the caller's unexpired quote to an approved phone intent after a fresh availability\ncheck. Never orders a number; when every release switch is on, the intent is queued for\nactivation (`activation_queued`).\n", "security": [ { "supabaseUser": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/avatar-instance-phone-approve/index.ts", "const": "Body", "schema": "InstancePhoneApproveRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstancePhoneApproveRequest" } } } }, "responses": { "202": { "description": "Approved; no order placed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstancePhoneApproval" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/avatar-phone-activate": { "post": { "operationId": "activateAvatarPhone", "tags": [ "Phone numbers" ], "summary": "Collect first rent, then order the approved exact number", "description": "Service-only and default-off. Runs `avatar-phone-billing` then `avatar-phone-provision`\nfor one released approval; a failed or action-required payment never buys a number.\n", "security": [ { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/avatar-phone-activate/index.ts", "const": "Body", "schema": "ActivateRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateRequest" } } } }, "responses": { "200": { "description": "Rent paid and the number is ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Activation" } } } }, "202": { "description": "Rent paid; the order or routing is still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Activation" } } } }, "402": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "423": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/avatar-phone-approve": { "post": { "operationId": "approveAvatarPhoneRequest", "tags": [ "Phone numbers" ], "summary": "Approve or dismiss a persona avatar's phone-number request", "description": "A company admin's click. Approve passes two holds first: the quoted number must still be\norderable (409 with a fresh candidate otherwise) and the organization must carry the\nphone number plan (402 with `details.checkout_url` for a first buyer). Then the request\nmoves `proposed` to `approved` through the caller's RLS client and the order runs as that\nadmin (`avatar-phone/approved` event).\n", "security": [ { "supabaseUser": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/avatar-phone-approve/request.ts", "const": "PhoneApproveBody", "schema": "PhoneApproveRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneApproveRequest" } } } }, "responses": { "200": { "description": "The click was recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "approved": { "type": "boolean", "const": true }, "cancelled": { "type": "boolean", "const": true }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "requestId" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/avatar-phone-cancel": { "post": { "operationId": "cancelAvatarPhone", "tags": [ "Phone numbers" ], "summary": "Cancel an instance's phone identity and stop routing now", "description": "Ends registered calls, then reconciles rent (refund before an order, port-out window after one).", "security": [ { "supabaseUser": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/avatar-phone-cancel/index.ts", "const": "Body", "schema": "CancelRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "200": { "description": "Cancelled and settled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cancellation" } } } }, "202": { "description": "Cancelled; call teardown or rent reconciliation still pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cancellation" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/avatar-phone-provision": { "post": { "operationId": "provisionAvatarPhone", "tags": [ "Phone numbers" ], "summary": "Order and route a paid, released exact number", "description": "Service-only and default-off (`INSTANCE_PHONE_ORDER_ENABLED`). Never searches for a\nreplacement: it orders the one approved E.164 number, then reconciles SMS compliance, the\nSMS route, the voice route and the LiveKit dispatch.\n", "security": [ { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/avatar-phone-provision/index.ts", "const": "Body", "schema": "ProvisionRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionRequest" } } } }, "responses": { "200": { "description": "Ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provisioning" } } } }, "202": { "description": "Ordered; routing not yet ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provisioning" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "423": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/avatar-phone-quote": { "post": { "operationId": "quoteAvatarPhone", "tags": [ "Phone numbers" ], "summary": "Quote one exact, currently available phone number", "description": "Search only, never a purchase. Two callers share the function:\nan owner or company admin with their own JWT quoting for one avatar instance\n(`InstanceQuoteRequest`), or the avatar worker's service-role JWT quoting the number a\npersona avatar's recorded request will show (`PersonaQuoteRequest`, chosen when the body\nhas `request_id` and no `customer_assistant_id`). A quote expires after 5 minutes.\n", "security": [ { "supabaseUser": [] }, { "serviceRole": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/avatar-phone-quote/index.ts", "const": "Body", "schema": "InstanceQuoteRequest" }, { "file": "supabase/functions/avatar-phone-quote/personaRequestQuote.ts", "const": "PersonaBody", "schema": "PersonaQuoteRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InstanceQuoteRequest" }, { "$ref": "#/components/schemas/PersonaQuoteRequest" } ] } } } }, "responses": { "200": { "description": "The quoted number and its price.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InstanceQuote" }, { "$ref": "#/components/schemas/PersonaQuote" } ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/avatar-phone-voice-webhook": { "post": { "operationId": "receiveVoiceEvent", "tags": [ "Inbound events" ], "summary": "LiveKit SIP join/leave receipts for instance phone usage", "description": "Verifies the LiveKit webhook JWT in `Authorization`, then records voice usage for the inbound trunk.", "security": [ { "livekitWebhook": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/avatar-phone-voice-webhook/index.ts", "const": "Event", "schema": "LivekitWebhookEvent" } ] }, "requestBody": { "required": true, "content": { "application/webhook+json": { "schema": { "$ref": "#/components/schemas/LivekitWebhookEvent" } } } }, "responses": { "200": { "description": "Recorded.", "content": { "text/plain": { "schema": { "type": "string", "const": "OK" } } } }, "401": { "description": "Missing or invalid LiveKit signature." }, "503": { "description": "Webhook unavailable or the receipt needs reconciliation." } } } }, "/delegated-calendar-setup": { "post": { "operationId": "delegatedCalendarSetup", "tags": [ "Calendar" ], "summary": "Connect an installed Employee, or an approved agent calendar, to a Google Calendar", "description": "`operation` selects the step: read `status`, `list_connections`, `list_calendars` on one\nconnection, `select_calendar`, or `replace_calendar` (swap a revoked or changed\nselection). Errors carry the contract code (`calendar/forbidden`, `calendar/conflict`,\n`calendar/invalid`, `calendar/unavailable`, `calendar/unsupported`) as both `error` and `code`.\n\n#5340: an agent calendar ordered with `provider: delegated_google` completes here after the\napproving admin's Google consent (the existing `oauth-connect` flow): `agent_calendar_connections`,\n`agent_calendar_calendars`, then `agent_calendar_bind`, keyed by the approved request. Their\nrefusals carry their own codes (see AgentCalendarBind).\n", "security": [ { "supabaseUser": [] } ], "x-handler": { "contracts": [ { "file": "supabase/functions/delegated-calendar-setup/schema.ts", "const": "delegatedSetupRequest", "schema": "DelegatedSetupRequest" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegatedSetupRequest" } } } }, "responses": { "200": { "description": "The operation's result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoSendResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "501": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/process-assistant-email": { "post": { "operationId": "processAssistantEmail", "tags": [ "Email" ], "summary": "Draft and send (or draft only) the reply to one assistant mailbox email", "description": "Internal dispatch from scheduled-runner's email monitor and execute-ai-agent. Only the\nservice-role key or the avatar service token may call it. Replies once per\n`(userAgentId, messageId)`; a repeat returns `skipped`. The handler does not check the\nHTTP method; dispatchers send `POST`.\n", "security": [ { "serviceRole": [] }, { "avatarServiceToken": [] } ], "x-handler": { "unguardedMethod": true, "contracts": [ { "file": "supabase/functions/process-assistant-email/input.ts", "const": "EmailProcessRequest", "schema": "AssistantEmailDispatch" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantEmailDispatch" } } } }, "responses": { "200": { "description": "Replied, drafted, or skipped.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "skipped": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "already_replied", "in_progress", "duplicate" ] }, "messageId": { "type": "string" }, "replyMessageId": { "type": [ "string", "null" ] }, "creditsUsed": { "type": "integer" } }, "required": [ "success" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "supabaseUser": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A signed-in user's Supabase access token." }, "serviceRole": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The project's service role (server-to-server only). Which form a route takes follows its\ngateway setting in supabase/config.toml, and the two are not interchangeable:\n - verify_jwt = true (e.g. agent-calendar-quote / -status / -projector / -release-scheduler,\n avatar-phone-*, appointment-calendar): the legacy service-role JWT. The gateway verifies\n it; an opaque `sb_secret_` key is refused before the handler runs.\n - verify_jwt = false (the four public agent-calendar functions -availability, -bookings,\n -events, -grants): the runtime's own `SUPABASE_SERVICE_ROLE_KEY`, compared byte for byte\n in the handler (`isExactServiceKey`).\n - verify_jwt = false agent-mesh-quote / -approve / -status / -enroll (#5314): the runtime key or\n the legacy service-role JWT, each compared verbatim (`actionsAuth.isTrustedServiceCaller`).\n" }, "avatarServiceToken": { "type": "http", "scheme": "bearer", "description": "The avatar worker's `AVATAR_SERVICE_TOKEN`." }, "workerSecret": { "type": "apiKey", "in": "header", "name": "x-worker-secret", "description": "The reaper's shared secret; selects the redrive lane." }, "telnyxSignature": { "type": "apiKey", "in": "header", "name": "telnyx-signature-ed25519", "description": "Ed25519 signature over `telnyx-timestamp|body`, verified with `TELNYX_PUBLIC_KEY`." }, "svixSignature": { "type": "apiKey", "in": "header", "name": "svix-signature", "description": "Svix HMAC-SHA256 over `svix-id.svix-timestamp.body` (Resend webhooks)." }, "developerKey": { "type": "http", "scheme": "bearer", "bearerFormat": "hpx_", "description": "A developer API key (`hpx_…`) with the `acp` scope. The organization is the key's; the key acts as the user who minted it." }, "livekitWebhook": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "LiveKit webhook token in `Authorization`, signed with the project API secret and carrying the body hash." } }, "parameters": { "OwnerAvatarType": { "name": "avatar_type", "in": "query", "required": false, "description": "The calendar's owner when it is a roster avatar (exactly one of this or `external_agent_id`).", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$" } }, "OwnerExternalAgentId": { "name": "external_agent_id", "in": "query", "required": false, "description": "The calendar's owner when it is an external agent (exactly one of this or `avatar_type`).", "schema": { "type": "string", "format": "uuid" } }, "ServiceOrganizationId": { "name": "organization_id", "in": "query", "required": false, "description": "The service lane (the avatar worker, bearer = the service-role key) names its subject organization here; required on that lane, ignored for a developer key (the key's organization is used).", "schema": { "type": "string", "format": "uuid" } }, "FeedToken": { "name": "feed_token", "in": "path", "required": true, "description": "The private feed token (`acf_` + 43 base64url characters) from an `agent-calendar-shares` create; the URL ends `.ics`.", "schema": { "type": "string", "pattern": "^acf_[A-Za-z0-9_-]{43}$" } } }, "responses": { "Error": { "description": "An error from `_shared/errorResponse.ts`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "CalendarQuoteRequest": { "type": "object", "properties": { "request_id": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "request_id" ] }, "CalendarQuote": { "type": "object", "properties": { "calendar_href": { "type": [ "string", "null" ], "description": "`/dav/cal//agent` on the calendar store; null for `delegated_google` (#5340: the Google calendar is chosen after the admin's consent)." }, "provider": { "type": "string", "enum": [ "managed", "delegated_google" ] }, "available": { "type": "boolean" }, "display_name": { "type": "string" }, "reason": { "type": "string", "description": "`provider_not_orderable` is no longer answered (#5340 orders delegated_google); it stays for requests recorded before.", "enum": [ "calendar_limit_reached", "unknown_avatar", "unknown_owner", "unknown_external_agent", "payment_not_confirmed", "provider_not_orderable", "unknown_provider", "store_unconfigured", "calendar_being_released", "calendar_on_other_provider" ] } }, "required": [ "calendar_href", "provider", "available", "display_name" ] }, "CalendarApproveRequest": { "type": "object", "properties": { "requestId": { "$ref": "#/components/schemas/Uuid" }, "action": { "type": "string", "enum": [ "approve", "cancel" ] } }, "required": [ "requestId", "action" ] }, "CalendarStatusRequest": { "type": "object", "properties": { "organization_id": { "$ref": "#/components/schemas/Uuid" }, "avatar_type": { "type": "string", "description": "A roster avatar type, or an external agent's subject `agent:`." } }, "required": [ "organization_id", "avatar_type" ] }, "CalendarStatus": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "reserved", "provisioning", "active", "releasing", "failed" ] }, "provider": { "type": "string", "enum": [ "managed", "delegated_google" ] }, "calendar_href": { "type": [ "string", "null" ] }, "ready": { "type": "boolean" }, "readiness": { "type": "object", "properties": { "identity": { "type": "boolean" }, "store": { "type": "boolean" }, "share": { "type": "boolean" } } }, "last_error": { "type": [ "string", "null" ] } } }, "CalendarPassRequest": { "type": "object", "properties": {}, "additionalProperties": false }, "LapseSummary": { "type": "object", "properties": { "examined": { "type": "integer" }, "graceStarted": { "type": "integer" }, "graceCleared": { "type": "integer" }, "released": { "type": "integer" }, "failed": { "type": "integer" } } }, "ProjectorSummary": { "type": "object", "properties": { "calendars": { "type": "integer" }, "examined": { "type": "integer" }, "projected": { "type": "integer" }, "failed": { "type": "integer" }, "conflicts": { "type": "integer" }, "calendarFailures": { "type": "integer" } } }, "Instant": { "type": "string", "format": "date-time", "description": "ISO 8601 instant with an offset." }, "ProjectionState": { "type": "string", "enum": [ "pending", "projected", "failed", "conflict" ], "description": "Where the booking stands on the agent's CalDAV calendar (ADR-003): `conflict` means the event\nwas changed or deleted there by someone else; the booking still holds and the event is not\noverwritten until reviewed.\n" }, "Booking": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "revision": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "confirmed", "cancelled" ] }, "start_at": { "$ref": "#/components/schemas/Instant" }, "end_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "id", "revision", "status", "start_at", "end_at" ] }, "BookingResult": { "type": "object", "properties": { "booking": { "$ref": "#/components/schemas/Booking" }, "replayed": { "type": "boolean" }, "projection_state": { "$ref": "#/components/schemas/ProjectionState" } }, "required": [ "booking" ] }, "CreateBookingRequest": { "type": "object", "properties": { "start_at": { "$ref": "#/components/schemas/Instant" }, "end_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "start_at", "end_at" ] }, "MoveBookingRequest": { "type": "object", "properties": { "booking_id": { "$ref": "#/components/schemas/Uuid" }, "expected_revision": { "type": "integer", "minimum": 1, "description": "The booking's current revision; a stale one is 409 `stale_revision`." }, "start_at": { "$ref": "#/components/schemas/Instant" }, "end_at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "booking_id", "expected_revision", "start_at", "end_at" ] }, "CreateEventRequest": { "type": "object", "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 500 }, "start_at": { "$ref": "#/components/schemas/Instant" }, "end_at": { "$ref": "#/components/schemas/Instant" }, "description": { "type": [ "string", "null" ], "maxLength": 8000 } }, "required": [ "summary", "start_at", "end_at" ] }, "UpdateEventRequest": { "type": "object", "properties": { "uid": { "type": "string", "minLength": 1, "maxLength": 200 }, "summary": { "type": "string", "minLength": 1, "maxLength": 500 }, "start_at": { "$ref": "#/components/schemas/Instant" }, "end_at": { "$ref": "#/components/schemas/Instant" }, "description": { "type": [ "string", "null" ], "maxLength": 8000 }, "sequence": { "type": "integer", "minimum": 0, "description": "RFC 5545 SEQUENCE; bump it on every change." } }, "required": [ "uid", "summary", "start_at", "end_at", "sequence" ] }, "EventWritten": { "type": "object", "properties": { "uid": { "type": "string" }, "etag": { "type": [ "string", "null" ] } }, "required": [ "uid" ] }, "StoredEvent": { "type": "object", "description": "A managed calendar answers `ics`; a delegated Google calendar (#5340) answers `event`.", "properties": { "uid": { "type": "string" }, "ics": { "type": "string", "description": "The VCALENDAR text the store holds (managed)." }, "event": { "type": "object", "description": "The Google event's fields (delegated_google).", "properties": { "uid": { "type": "string" }, "kind": { "type": "string", "enum": [ "booking", "event" ] }, "summary": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "start_at": { "type": [ "string", "null" ] }, "end_at": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "etag": { "type": [ "string", "null" ] } } }, "etag": { "type": [ "string", "null" ] } }, "required": [ "uid" ] }, "EventPage": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string" }, "kind": { "type": "string", "enum": [ "booking", "event" ] }, "summary": { "type": [ "string", "null" ] }, "start_at": { "type": [ "string", "null" ], "description": "ISO for a UTC time, YYYY-MM-DD for a date, else the raw local value." }, "end_at": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "etag": { "type": [ "string", "null" ] } } } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "events", "next_cursor" ] }, "GrantRequest": { "type": "object", "properties": { "user_id": { "$ref": "#/components/schemas/Uuid" }, "can_create": { "type": "boolean" }, "can_move": { "type": "boolean" }, "can_cancel": { "type": "boolean" } }, "required": [ "user_id", "can_create", "can_move", "can_cancel" ] }, "Grant": { "type": "object", "properties": { "userId": { "$ref": "#/components/schemas/Uuid" }, "canCreate": { "type": "boolean" }, "canMove": { "type": "boolean" }, "canCancel": { "type": "boolean" } } }, "BookingWebhookEvent": { "type": "object", "description": "Sent to an external-agent owner's `webhook_url`, signed with its webhook secret (Standard\nWebhooks: `webhook-id` = `id`, `webhook-timestamp`, `webhook-signature: v1,`).\n", "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "type": { "type": "string", "enum": [ "booking.created", "booking.moved", "booking.cancelled", "booking.conflict" ] }, "created_at": { "$ref": "#/components/schemas/Instant" }, "data": { "type": "object", "properties": { "calendar_id": { "$ref": "#/components/schemas/Uuid" }, "owner": { "type": "object" }, "booking": { "$ref": "#/components/schemas/Booking" } } } }, "required": [ "id", "type", "created_at", "data" ] }, "CreateShareRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "caldav_account": { "type": [ "string", "null" ], "format": "email", "maxLength": 320, "description": "The recipient's own login on the calendar store (local@domain), granted CalDAV read." } }, "required": [ "email" ] }, "CalendarShare": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "recipient_email": { "type": "string" }, "email_status": { "type": "string", "enum": [ "pending", "sent", "failed" ] }, "caldav": { "type": "boolean" }, "created_at": { "$ref": "#/components/schemas/Instant" }, "last_fetched_at": { "oneOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "revoked": { "type": "boolean" } } }, "CreatedShare": { "type": "object", "properties": { "share": { "$ref": "#/components/schemas/CalendarShare" }, "feed": { "type": "object", "properties": { "https_url": { "type": "string", "format": "uri" }, "webcal_url": { "type": "string" }, "google_url": { "type": "string", "format": "uri" } } }, "rotated": { "type": "integer", "minimum": 0, "description": "How many earlier shares to this email were revoked." } } }, "MeshAvatarType": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$", "description": "An avatar type from the persona registry, e.g. `language_tutor`." }, "MeshOrganizationRef": { "description": "Required of service-role and signed-in callers. Ignored for a developer key: the key's own\norganization is always the one acted on.\n", "type": "string", "format": "uuid" }, "MeshQuoteRequest": { "type": "object", "properties": { "organization_id": { "$ref": "#/components/schemas/MeshOrganizationRef" }, "avatar_type": { "$ref": "#/components/schemas/MeshAvatarType" } }, "required": [ "avatar_type" ] }, "MeshStatusRequest": { "type": "object", "properties": { "organization_id": { "$ref": "#/components/schemas/MeshOrganizationRef" } } }, "MeshApproveRequest": { "type": "object", "properties": { "requestId": { "$ref": "#/components/schemas/Uuid" }, "action": { "type": "string", "enum": [ "approve", "cancel" ] } }, "required": [ "requestId", "action" ] }, "MeshPrincipal": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "avatar" }, "avatar_type": { "$ref": "#/components/schemas/MeshAvatarType" } }, "required": [ "kind", "avatar_type" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "external_agent" }, "external_agent_id": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "kind", "external_agent_id" ] } ], "discriminator": { "propertyName": "kind" } }, "MeshInviteRequest": { "type": "object", "additionalProperties": false, "properties": { "organization_id": { "$ref": "#/components/schemas/MeshOrganizationRef" }, "principal": { "$ref": "#/components/schemas/MeshPrincipal" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 80 }, "labels": { "type": "array", "maxItems": 16, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,62}=[a-zA-Z0-9_.-]{1,63}$", "description": "`key=value`" } } }, "required": [ "principal" ] }, "MeshMemberRef": { "type": "object", "additionalProperties": false, "description": "An existing member of the organization's mesh (re-mint its token, or confirm its node joined).", "properties": { "organization_id": { "$ref": "#/components/schemas/MeshOrganizationRef" }, "mesh_id": { "$ref": "#/components/schemas/Uuid" }, "member_id": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "mesh_id", "member_id" ] }, "MeshRevokeRequest": { "type": "object", "properties": { "organization_id": { "$ref": "#/components/schemas/MeshOrganizationRef" }, "member_id": { "$ref": "#/components/schemas/Uuid" }, "reason": { "type": "string", "maxLength": 200 } }, "required": [ "member_id" ] }, "MeshMember": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "principal_kind": { "type": "string", "enum": [ "avatar", "external_agent" ] }, "avatar_type": { "type": [ "string", "null" ] }, "external_agent_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "service": { "type": "string", "description": "The name the member publishes, e.g. `a2a://language_tutor`." }, "state": { "type": "string", "enum": [ "invited", "enrolled", "revoked" ] }, "peer_id": { "type": [ "string", "null" ], "description": "The member node's libp2p peer id once it has joined." } } }, "MeshStatus": { "type": "object", "description": "Where the organization's mesh stands. Never a credential.", "properties": { "mesh_id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "enum": [ "reserved", "provisioning", "active", "releasing", "released", "failed" ] }, "slug": { "type": "string", "description": "The mesh's public name, `-<4 hex>`." }, "host": { "type": "string", "enum": [ "fly", "local" ] }, "control_plane_url": { "type": [ "string", "null" ], "format": "uri" }, "ready": { "type": "boolean" }, "last_error": { "type": [ "string", "null" ] }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/MeshMember" } } }, "required": [ "mesh_id", "state", "slug", "host", "control_plane_url", "ready", "last_error", "members" ] }, "MeshQuote": { "type": "object", "properties": { "slug": { "type": "string" }, "host": { "type": "string", "enum": [ "fly", "local" ] }, "available": { "type": "boolean" }, "price": { "type": "object", "properties": { "plan_gate": { "type": "string", "const": "paid_plan" } } }, "reason": { "type": "string", "enum": [ "unknown_avatar", "payment_not_confirmed", "mesh_being_released", "host_unconfigured" ] }, "existing": { "$ref": "#/components/schemas/MeshStatus" } }, "required": [ "slug", "host", "available", "price" ] }, "MeshEnrollment": { "type": "object", "description": "Shown once (`Cache-Control: no-store`). The bootstrap token is one-use and valid 24 h.", "properties": { "member_id": { "$ref": "#/components/schemas/Uuid" }, "service_name": { "type": "string" }, "control_plane_url": { "type": "string", "format": "uri" }, "bootstrap_token": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "member_id", "service_name", "control_plane_url", "bootstrap_token", "expires_at" ] }, "MeshJoined": { "type": "object", "properties": { "member_id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "const": "enrolled" }, "peer_id": { "type": "string" }, "service": { "type": "string" } }, "required": [ "member_id", "state", "peer_id", "service" ] }, "MeshRevoked": { "type": "object", "properties": { "member_id": { "$ref": "#/components/schemas/Uuid" }, "state": { "type": "string", "const": "revoked" }, "method": { "type": "string", "enum": [ "ban", "token_revoke", "none" ] } }, "required": [ "member_id", "state", "method" ] }, "AppointmentCalendarRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "list_calendars", "select_calendar", "sync", "staff_queue", "link_contact", "dismiss", "communication_reconcile", "communication_status", "communication_status_batch", "available_slots", "issue_reschedule_proof", "reschedule", "issue_cancel_proof", "cancel_recovery_queue", "reconcile_cancel" ] }, "organizationId": { "$ref": "#/components/schemas/Uuid" }, "receptionistId": { "$ref": "#/components/schemas/Uuid" }, "actorUserId": { "$ref": "#/components/schemas/Uuid", "description": "Service lane only; the staff member acted for.", "__uniqueRefKey": "#/components/schemas/Uuid__4" }, "calendarId": { "type": "string", "maxLength": 512, "description": "`select_calendar`." }, "eventId": { "$ref": "#/components/schemas/Uuid", "description": "`link_contact`, `dismiss`.", "__uniqueRefKey": "#/components/schemas/Uuid__5" }, "contactId": { "type": "string", "pattern": "^people/[A-Za-z0-9_-]+$", "description": "`link_contact`." } }, "required": [ "action", "organizationId", "receptionistId" ], "additionalProperties": true }, "AppointmentActionRequest": { "type": "object", "properties": { "proof": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "proof" ], "additionalProperties": false }, "DelegatedSetupRequest": { "oneOf": [ { "$ref": "#/components/schemas/DelegatedStatus" }, { "$ref": "#/components/schemas/DelegatedListConnections" }, { "$ref": "#/components/schemas/DelegatedListCalendars" }, { "$ref": "#/components/schemas/DelegatedSelectCalendar" }, { "$ref": "#/components/schemas/DelegatedReplaceCalendar" }, { "$ref": "#/components/schemas/AgentCalendarConnections" }, { "$ref": "#/components/schemas/AgentCalendarCalendars" }, { "$ref": "#/components/schemas/AgentCalendarBind" } ], "discriminator": { "propertyName": "operation", "mapping": { "status": "#/components/schemas/DelegatedStatus", "list_connections": "#/components/schemas/DelegatedListConnections", "list_calendars": "#/components/schemas/DelegatedListCalendars", "select_calendar": "#/components/schemas/DelegatedSelectCalendar", "replace_calendar": "#/components/schemas/DelegatedReplaceCalendar", "agent_calendar_connections": "#/components/schemas/AgentCalendarConnections", "agent_calendar_calendars": "#/components/schemas/AgentCalendarCalendars", "agent_calendar_bind": "#/components/schemas/AgentCalendarBind" } } }, "DelegatedStatus": { "type": "object", "properties": { "operation": { "const": "status" }, "organizationId": { "$ref": "#/components/schemas/Uuid" }, "employeeId": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "operation", "organizationId", "employeeId" ], "additionalProperties": false }, "DelegatedListConnections": { "type": "object", "properties": { "operation": { "const": "list_connections" }, "organizationId": { "$ref": "#/components/schemas/Uuid" }, "employeeId": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "operation", "organizationId", "employeeId" ], "additionalProperties": false }, "DelegatedListCalendars": { "type": "object", "properties": { "operation": { "const": "list_calendars" }, "organizationId": { "$ref": "#/components/schemas/Uuid" }, "employeeId": { "$ref": "#/components/schemas/Uuid" }, "connectionId": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "operation", "organizationId", "employeeId", "connectionId" ], "additionalProperties": false }, "DelegatedSelectCalendar": { "type": "object", "properties": { "operation": { "const": "select_calendar" }, "organizationId": { "$ref": "#/components/schemas/Uuid" }, "employeeId": { "$ref": "#/components/schemas/Uuid" }, "connectionId": { "$ref": "#/components/schemas/Uuid" }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "operation", "organizationId", "employeeId", "connectionId", "calendarId" ], "additionalProperties": false }, "DelegatedReplaceCalendar": { "type": "object", "properties": { "operation": { "const": "replace_calendar" }, "organizationId": { "$ref": "#/components/schemas/Uuid" }, "employeeId": { "$ref": "#/components/schemas/Uuid" }, "previousIdentityId": { "$ref": "#/components/schemas/Uuid" }, "connectionId": { "$ref": "#/components/schemas/Uuid" }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "operation", "organizationId", "employeeId", "previousIdentityId", "connectionId", "calendarId" ], "additionalProperties": false }, "AgentCalendarConnections": { "description": "#5340: the approving admin's live Google Calendar connections, for an agent calendar request waiting for Google consent.", "type": "object", "properties": { "operation": { "const": "agent_calendar_connections" }, "organizationId": { "$ref": "#/components/schemas/Uuid" }, "requestId": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "operation", "organizationId", "requestId" ], "additionalProperties": false }, "AgentCalendarCalendars": { "description": "#5340: the writable calendars of one of the approving admin's Google connections.", "type": "object", "properties": { "operation": { "const": "agent_calendar_calendars" }, "organizationId": { "$ref": "#/components/schemas/Uuid" }, "requestId": { "$ref": "#/components/schemas/Uuid" }, "connectionId": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "operation", "organizationId", "requestId", "connectionId" ], "additionalProperties": false }, "AgentCalendarBind": { "description": "#5340: bind the chosen Google calendar to the agent calendar and make it active. Refusals carry\ntheir own code: `google_reconnect_required` (revoked or expired consent), `google_scope_missing`,\n`google_calendar_not_writable`, `not_the_approver`, `request_not_awaiting_consent`,\n`calendar_bound_elsewhere`, `order_in_progress`.\n", "type": "object", "properties": { "operation": { "const": "agent_calendar_bind" }, "organizationId": { "$ref": "#/components/schemas/Uuid" }, "requestId": { "$ref": "#/components/schemas/Uuid" }, "connectionId": { "$ref": "#/components/schemas/Uuid" }, "calendarId": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "operation", "organizationId", "requestId", "connectionId", "calendarId" ], "additionalProperties": false }, "NoSendResult": { "type": "object", "description": "An action result. Calendar actions never send a message, so they echo `noSend`.", "properties": { "noSend": { "type": "boolean", "const": true } }, "additionalProperties": true }, "ClaimRequest": { "type": "object", "description": "An agent's claim on a .one resource (#5342). `product` picks the adapter; the rest are its options.", "properties": { "product": { "type": "string", "enum": [ "calendar" ] }, "agent_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Who is asking, as the approve page shows it (e.g. \"Claude\")." }, "display_name": { "type": "string", "maxLength": 120, "description": "The calendar's name; the agent name when absent." }, "time_zone": { "type": "string", "maxLength": 64, "description": "An IANA zone; UTC when absent." } }, "required": [ "product", "agent_name" ], "additionalProperties": false }, "ClaimStarted": { "type": "object", "description": "The RFC 8628 device authorization response in plain words.", "properties": { "claim_id": { "$ref": "#/components/schemas/Uuid" }, "product": { "type": "string" }, "status": { "type": "string", "enum": [ "authorization_pending" ] }, "approve_url": { "type": "string", "format": "uri", "description": "For the human: `https:///approve/` (dev: dev.helpfulai.app)." }, "poll_url": { "type": "string", "format": "uri" }, "poll_token": { "type": "string", "description": "The agent's secret (`acpp_…`); shown once." }, "expires_at": { "type": "string", "format": "date-time" }, "expires_in": { "type": "integer", "description": "Seconds the human has to approve (1800)." }, "interval": { "type": "integer", "description": "Seconds between polls (5)." }, "next_step": { "type": "string" } }, "required": [ "claim_id", "product", "status", "approve_url", "poll_url", "poll_token", "expires_at", "expires_in", "interval" ] }, "ClaimPoll": { "type": "object", "properties": { "claim_id": { "$ref": "#/components/schemas/Uuid" }, "product": { "type": "string" }, "status": { "type": "string", "enum": [ "authorization_pending", "approving", "ready", "access_denied", "expired_token", "failed" ] }, "interval": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "code": { "type": "string", "description": "failed: the order's refusal code." }, "resource": { "type": "object", "description": "ready: what was ordered (calendar: calendar_id, calendar_href, external_agent_id, state)." }, "credentials": { "type": "object", "description": "ready: `api_key` (an `hpx_` key, scope acp) on the FIRST ready poll only; null afterwards.", "properties": { "api_key": { "type": [ "string", "null" ] }, "key_prefix": { "type": "string" }, "scope": { "type": "string", "enum": [ "acp" ] }, "header": { "type": "string" } } }, "usage": { "type": "object", "description": "ready: the endpoints and the owner parameter to send with the key." }, "message": { "type": "string" } }, "required": [ "claim_id", "product", "status" ] }, "ClaimApproveRequest": { "type": "object", "properties": { "approve_token": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The token in the approve URL (`acpa_…`)." }, "action": { "type": "string", "enum": [ "view", "approve", "deny" ] }, "organization_id": { "$ref": "#/components/schemas/Uuid", "description": "view (for the quote) and approve: the organization the resource is for; the caller must be its company admin.", "__uniqueRefKey": "#/components/schemas/Uuid__6" } }, "required": [ "approve_token", "action" ], "additionalProperties": false }, "ClaimDecision": { "type": "object", "properties": { "claim": { "type": "object", "properties": { "product": { "type": "string" }, "site": { "type": "string" }, "noun": { "type": "string" }, "agent_name": { "type": "string" }, "phase": { "type": "string", "enum": [ "decide", "working", "approved", "denied", "expired", "failed" ] }, "expires_at": { "type": "string", "format": "date-time" }, "result_code": { "type": [ "string", "null" ] }, "resource": { "type": "object" } } }, "can_approve": { "type": "boolean" }, "reason": { "type": "string" }, "message": { "type": "string" }, "quote": { "type": "object", "properties": { "resource": { "type": "object" }, "included": { "type": "boolean", "description": "true: included in the plan, approving orders it now. false: billed, Checkout first." }, "price": { "type": [ "object", "null" ], "properties": { "amount": { "type": [ "integer", "null" ], "description": "Minor units." }, "currency": { "type": "string" }, "interval": { "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] } } } } } }, "required": [ "claim" ] }, "McpMessage": { "type": "object", "description": "One JSON-RPC 2.0 message of the Model Context Protocol (or an array of them): initialize, ping, tools/list, tools/call, notifications/*.", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "integer", "null" ] }, "method": { "type": "string" }, "params": { "type": "object" } }, "required": [ "jsonrpc", "method" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "details": { "type": "object" } }, "required": [ "error" ] }, "Uuid": { "type": "string", "format": "uuid" }, "AssistantEmailDispatch": { "type": "object", "properties": { "userAgentId": { "type": "string", "minLength": 1 }, "assistantId": { "type": [ "string", "null" ], "description": "Null for personal or draft mode." }, "userId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "threadId": { "type": [ "string", "null" ] }, "fromEmail": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "replyStyle": { "type": [ "string", "null" ] }, "draftMode": { "type": [ "boolean", "null" ], "description": "Create a Gmail draft instead of sending." } }, "required": [ "userAgentId", "userId", "messageId" ] }, "TelnyxMessagingEvent": { "type": "object", "description": "A Telnyx messaging webhook. Only `message.received` is ingested.", "properties": { "data": { "type": "object", "properties": { "event_type": { "type": "string", "examples": [ "message.received" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "payload": { "type": "object" } }, "required": [ "event_type" ] } }, "required": [ "data" ] }, "InboundRedriveRequest": { "type": "object", "description": "The reaper's redrive of a stalled claim (`x-worker-secret` lane).", "properties": { "claim_id": { "type": "string" } }, "required": [ "claim_id" ] }, "InboundReceipt": { "type": "object", "properties": { "received": { "type": "boolean" }, "claim_id": { "type": "string" }, "duplicate": { "type": "boolean" }, "status": { "type": "string" }, "skipped": { "type": "string", "examples": [ "not_inbound", "recipient_not_allowed" ] }, "error": { "type": "string", "enum": [ "claim_failed", "fetch_failed" ] }, "recovered": { "type": "boolean", "description": "Redrive lane only." }, "terminal": { "type": "boolean", "description": "Redrive lane only." }, "reason": { "type": "string", "description": "Redrive lane only." } } }, "LivekitWebhookEvent": { "type": "object", "description": "A LiveKit webhook event; SIP participant joins and leaves are metered.", "properties": { "event": { "type": "string", "examples": [ "participant_joined", "participant_left" ] }, "createdAt": { "type": "integer" }, "room": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "participant": { "type": "object", "properties": { "identity": { "type": "string" }, "kind": { "type": "integer" }, "joinedAt": { "type": "integer" }, "attributes": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "identity" ] } }, "required": [ "event" ] }, "ResendWebhookEvent": { "type": "object", "description": "A Resend webhook. Only `email.received` is claimed.", "properties": { "type": { "type": "string", "examples": [ "email.received" ] }, "data": { "type": "object" } }, "required": [ "type", "data" ] }, "InstanceQuoteRequest": { "type": "object", "properties": { "customer_assistant_id": { "$ref": "#/components/schemas/Uuid" }, "area_code": { "type": [ "string", "null" ], "pattern": "^[2-9][0-9]{2}$" }, "phone_number": { "type": [ "string", "null" ], "pattern": "^\\+1[2-9][0-9]{9}$", "description": "An exact number to re-check instead of searching." } }, "required": [ "customer_assistant_id" ] }, "PersonaQuoteRequest": { "type": "object", "properties": { "request_id": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "request_id" ] }, "InstanceQuote": { "type": "object", "properties": { "quote_id": { "$ref": "#/components/schemas/Uuid" }, "customer_assistant_id": { "$ref": "#/components/schemas/Uuid" }, "organization_id": { "$ref": "#/components/schemas/Uuid" }, "phone_number": { "type": "string" }, "preferred_area_code_matched": { "type": "boolean" }, "requested_area_code": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "area_code_unavailable": { "type": "boolean" }, "availability_message": { "type": "string" }, "pricing": { "type": "object", "properties": { "platform_monthly_usd": { "type": "string" }, "phone_monthly_usd": { "type": "string" }, "ai_voice_per_minute_usd": { "type": "string" }, "sms_per_segment_usd": { "type": "string" } } }, "requires_exact_number_approval": { "type": "boolean", "const": true } } }, "PersonaQuote": { "type": "object", "properties": { "request_id": { "$ref": "#/components/schemas/Uuid" }, "area_code": { "type": [ "string", "null" ] }, "reserved": { "type": "boolean", "description": "True when an unfinished order already holds this number." }, "quote": { "type": [ "object", "null" ], "properties": { "number": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "monthly_cents": { "type": "integer" }, "voice_microusd_per_minute": { "type": "integer" }, "sms_microusd_per_segment": { "type": "integer" } } } } }, "InstancePhoneApproveRequest": { "type": "object", "properties": { "quote_id": { "$ref": "#/components/schemas/Uuid" }, "approved_phone_number": { "type": "string", "pattern": "^\\+[1-9][0-9]{7,14}$" } }, "required": [ "quote_id", "approved_phone_number" ] }, "InstancePhoneApproval": { "type": "object", "properties": { "approved": { "type": "boolean", "const": true }, "quote_id": { "$ref": "#/components/schemas/Uuid" }, "customer_assistant_id": { "$ref": "#/components/schemas/Uuid" }, "organization_id": { "$ref": "#/components/schemas/Uuid" }, "phone_number": { "type": "string" }, "state": { "type": "string" }, "activation_queued": { "type": "boolean" }, "order_placed": { "type": "boolean", "const": false } } }, "PhoneApproveRequest": { "type": "object", "properties": { "requestId": { "$ref": "#/components/schemas/Uuid" }, "action": { "type": "string", "enum": [ "approve", "cancel" ] }, "returnPath": { "type": "string", "maxLength": 256 }, "avatarName": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "requestId", "action" ] }, "ActivateRequest": { "type": "object", "properties": { "customer_assistant_id": { "$ref": "#/components/schemas/Uuid" }, "quote_id": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "customer_assistant_id", "quote_id" ] }, "Activation": { "type": "object", "properties": { "rent_paid": { "type": "boolean" }, "state": { "type": "string" }, "order_placed": { "type": "boolean" }, "phone_number": { "type": [ "string", "null" ] } }, "required": [ "rent_paid", "state", "order_placed" ] }, "ProvisionRequest": { "type": "object", "properties": { "customer_assistant_id": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "customer_assistant_id" ] }, "Provisioning": { "type": "object", "properties": { "phone_number": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "order_placed": { "type": "boolean" }, "voice_connection_ready": { "type": "boolean" }, "voice_route_ready": { "type": "boolean" }, "sms_profile_ready": { "type": "boolean" }, "sms_compliance_ready": { "type": "boolean" }, "sms_route_ready": { "type": "boolean" }, "active": { "type": "boolean" } } }, "CancelRequest": { "type": "object", "properties": { "customer_assistant_id": { "$ref": "#/components/schemas/Uuid" } }, "required": [ "customer_assistant_id" ] }, "Cancellation": { "type": "object", "properties": { "cancelled": { "type": "boolean", "const": true }, "routing_stopped": { "type": "boolean", "const": true }, "registered_calls_ended": { "type": "boolean" }, "registered_calls_pending": { "type": "integer" }, "rent_reconciliation": { "type": "string", "enum": [ "none", "portout", "cancelled_uncharged", "refunded", "pending" ] }, "phone_number": { "type": [ "string", "null" ] }, "port_out_deadline": { "type": [ "string", "null" ], "format": "date-time" }, "release_after": { "type": [ "string", "null" ], "format": "date-time" } } } } } }