{
  "schemaVersion": "1.0",
  "title": "Native HTTP API",
  "description": "This reference lists the native HTTP surface implemented by the product-neutral getaip-server gateway. Use it to select a route, identify its application authentication boundary, construct query parameters, and interpret the current respons",
  "canonical": "https://getaip.org/docs/reference/http-api",
  "route": "/docs/reference/http-api",
  "source": "docs/reference/http-api.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "API Reference",
  "documentType": "Reference",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/reference/http-api.md",
    "txt": "/docs/download/reference/http-api.txt",
    "json": "/docs/download/reference/http-api.json",
    "pdf": "/docs/download/reference/http-api.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Native HTTP API\ndescription: Look up product-neutral getaip-server routes, authentication, queries, and responses\nkind: reference\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# Native HTTP API\n\nThis reference lists the native HTTP surface implemented by the\nproduct-neutral `getaip-server` gateway. Use it to select a route, identify its\napplication authentication boundary, construct query parameters, and interpret\nthe current response form.\n\nThe route inventory applies to source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635`. It describes an implementation\nbinding, not additional AIP 1.0 wire requirements. Normative message fields\nremain owned by the protocol schemas.\n\n## Route and authentication classes\n\nThe router has four native security classes:\n\n| Class | Routes | Authentication in `getaip-server` |\n|---|---|---|\n| Service and public discovery | `/`, `/health`, `/ready`, `/metrics`, `/aip/v1/health`, `/aip/v1/manifest` | No application middleware; protect operational data at the deployment edge |\n| Generic native envelope | `POST /aip/v1/messages` | Configured bearer identity when presented; otherwise native envelope signature policy; loopback insecure development only when explicitly enabled |\n| Ergonomic native API | Actions, events, sessions, approvals, transactions, deliveries, receipts, audit, resources, capabilities, and WebSocket | Native bearer middleware, or the explicit loopback development identity |\n| Connector ingress | `POST /aip/v1/connector-events` and `POST /aip/v1/connector-callbacks` | Signed connector route, sender, tenant, lease, and replay validation inside the ingress handler |\n\nThe first class is unprotected only inside the application router. A reverse\nproxy or network policy should restrict readiness and metrics according to the\ndeployment boundary. Public manifest exposure is a deployment decision.\n\nThe connector-ingress routes are not client action routes. Their detailed\ncontract belongs to the connector-fleet API.\n\n## Authentication and trusted context\n\nThe direct `getaip-server` native HTTP edge supports one configured static bearer\ncredential. A successful comparison establishes the configured principal,\nscopes, and optional tenant as server-owned context. The gateway replaces\npayload sender claims with that authenticated principal.\n\nAll ergonomic routes pass through the native-auth middleware. With bearer\nauthentication configured, a missing or invalid credential returns HTTP `401`\nwith error code `auth.native_http_unauthorized`. An explicit loopback\ndevelopment mode can substitute the daemon identity; it is not a production\nauthentication mode.\n\n`POST /aip/v1/messages` is different. With a valid bearer credential, it uses\nthe trusted HTTP-edge identity and enforces replay policy. Without a bearer\nidentity, it sends the envelope through native signature verification, trusted\nsigner binding, and replay policy. The default gateway policy requires a\ntrusted signed envelope on that path.\n\nA `tenant_id`, principal filter, or sender field supplied by the client does\nnot grant authority. Runtime query authorization still checks the established\nprincipal, scopes, object owner, and tenant. See [Identity and\ntrust](../concepts/identity-and-trust.md) for that authorization model.\n\n## Representations and response forms\n\nThe native envelope media type is `application/aip+json`. The current Axum\nhandlers use JSON extraction and JSON responses; ordinary JSON responses carry\n`application/json`. Follow-mode event responses carry\n`text/event-stream`.\n\nTimestamps in native records use RFC 3339. Identifiers are opaque. Clients\nshould validate their documented prefix and length rules but must not derive\ntime, tenant, or topology from their contents.\n\nResponse form depends on the route:\n\n| Route class | Success | Error |\n|---|---|---|\n| `POST /aip/v1/messages` and `POST /aip/v1/actions` | Complete AIP response `Envelope` | Complete `Envelope` with an `error` body |\n| Ergonomic native queries and operations | Native body object such as `ActionStatus` or `ApprovalList` | Complete `Envelope` with `ProtocolError` |\n| Tenant capability catalog | `CapabilityPage` | Direct `{\"error\": {\"code\": ..., \"message\": ...}}` object |\n| Health, readiness, metrics, and manifest | Route-specific JSON or Prometheus text | Route-specific response |\n| SSE follow | Named SSE events with JSON data and cursor IDs | One terminal SSE error event |\n\n## Service and manifest routes\n\n| Method | Path | Response |\n|---|---|---|\n| `GET` | `/` | Process liveness payload |\n| `GET` | `/health` | Process liveness payload |\n| `GET` | `/ready` | Core readiness; HTTP `200` or `503` |\n| `GET` | `/metrics` | Prometheus text exposition |\n| `GET` | `/aip/v1/health` | Versioned alias of process liveness |\n| `GET` | `/aip/v1/manifest` | Complete or filtered participant `Manifest` |\n| `POST` | `/aip/v1/messages` | Response envelope for any supported native message body |\n\n`GET /aip/v1/manifest` accepts:\n\n| Parameter | Form |\n|---|---|\n| `capability_id` | Comma-separated capability IDs |\n| `resource_kind` | Comma-separated resource kinds |\n| `profile` | Comma-separated profile IDs |\n| `risk` | Comma-separated risk values |\n| `side_effect` | Comma-separated side-effect values |\n| `requires_approval` | Boolean |\n| `supports_streaming` | Boolean |\n| `supports_transactions` | Boolean |\n\nAn empty filter returns the complete local manifest. This route does not\ninclude the tenant connector-fleet catalog.\n\n## Action routes\n\n| Method | Path | Purpose |\n|---|---|---|\n| `POST` | `/aip/v1/actions` | Submit an envelope through the action-oriented alias |\n| `GET` | `/aip/v1/actions` | List visible durable action views |\n| `GET` | `/aip/v1/actions/{action_id}` | Read one `ActionStatus` |\n| `GET` | `/aip/v1/actions/{action_id}/result` | Read the terminal `ActionResult` |\n| `GET` | `/aip/v1/actions/{action_id}/events` | Read or follow action events |\n| `GET` | `/aip/v1/actions/{action_id}/chunks` | Read or follow stream chunks |\n| `POST` | `/aip/v1/actions/{action_id}/cancel` | Request cancellation |\n\nBoth submission paths call the same envelope handler at this revision.\n`POST /aip/v1/actions` is the action-oriented, bearer-authenticated alias, but\nthe handler does not reject another supported body type solely because of that\npath. Use `/aip/v1/messages` for non-action message families.\n\n### List actions\n\n`GET /aip/v1/actions` accepts:\n\n| Parameter | Meaning |\n|---|---|\n| `state` | Stable lifecycle state |\n| `capability_id` | Exact capability ID |\n| `session_id` | Exact session ID |\n| `principal_id` | Requesting principal recorded for the queued action |\n| `tenant_id` | Exact tenant boundary |\n| `approval_id` | Linked approval |\n| `transaction_id` | Linked transaction |\n| `cursor` | Page cursor returned by this route |\n| `limit` | Requested page size |\n| `include_results` | Include available final results |\n| `include_receipts` | Include available receipt chains |\n\nThe response is `ActionList` with `actions`, `total_size`, and an optional\nnext `cursor`.\n\n### Read status or result\n\nThe status route accepts `tenant_id`, `include_result`,\n`include_receipts`, `include_chunks`, and `wait_ms`. The result route\naccepts `tenant_id`, `wait_ms`, `include_receipt`, and\n`include_terminal_events`.\n\n`wait_ms` is serialized into the current request object, but the reviewed\nruntime does not wait. Status returns the current view immediately. Result\nreturns the current terminal result or an `action.result_not_ready` error.\nClients that need waiting should follow events or poll with their own bounded\ndeadline.\n\n### Read events or chunks\n\nThe action-events route accepts:\n\n| Parameter | Meaning |\n|---|---|\n| `tenant_id` | Expected tenant boundary |\n| `cursor` | Opaque event cursor |\n| `limit` | Requested page size |\n| `kind` | One event kind |\n| `kinds` | Comma-separated event kinds |\n| `include_chunks` | Include durable stream chunks |\n| `follow` | Return an SSE follow stream |\n\nWhen `cursor` is absent, `Last-Event-ID` supplies the cursor. The chunks\nroute uses `tenant_id`, `cursor`, `limit`, and `follow`, and always\nselects `aip.stream.chunk` with chunks included.\n\nCancellation accepts an optional JSON object:\n\n```json\n{\n  \"reason\": \"The caller no longer needs the result\"\n}\n```\n\nA successful cancellation response does not prove that an external provider\neffect was reversed.\n\n## Global event route\n\n| Method | Path | Purpose |\n|---|---|---|\n| `GET` | `/aip/v1/events` | Read or follow events visible to the authenticated identity |\n\nUsed parameters are `cursor`, `limit`, `kind`, comma-separated `kinds`,\nand `follow`. A query cursor takes precedence over `Last-Event-ID`.\nAuthorization limits the returned principals and tenants; the global route\ndoes not use a caller-supplied tenant filter.\n\n## Session routes\n\n| Method | Path | Purpose |\n|---|---|---|\n| `GET` | `/aip/v1/sessions` | List visible sessions |\n| `GET` | `/aip/v1/sessions/{session_id}` | Read one session |\n| `POST` | `/aip/v1/sessions/{session_id}/close` | Close a session |\n| `POST` | `/aip/v1/sessions/{session_id}/resume` | Resume a session |\n| `POST` | `/aip/v1/sessions/{session_id}:close` | Suffix-form close alias |\n| `POST` | `/aip/v1/sessions/{session_id}:resume` | Suffix-form resume alias |\n\nThe list route accepts `principal_id`, `status`, `cursor`, and `limit`.\nClose accepts an optional `reason`. Resume accepts `resume_token` and\n`last_event_cursor`. A successful resume rotates the token; replace the\nsupplied token with the returned one. [Actions and\nsessions](../concepts/actions-and-sessions.md) owns the lifecycle rules.\n\n## Approval routes\n\n| Method | Path | Purpose |\n|---|---|---|\n| `GET` | `/aip/v1/approvals` | List visible approval records |\n| `GET` | `/aip/v1/approvals/{approval_id}` | Read one approval record |\n\nList filters are `status`, `approver`, `requester`, `tenant_id`,\n`cursor`, and `limit`. `include_action_status` and\n`include_receipts` add their corresponding views.\n\nThe one-record route accepts `tenant_id`, `include_action_status`,\n`include_receipts`, and `include_evidence_payload`. Evidence payload\nexpansion uses export authorization and requires the `approval:sensitive`\nscope in addition to approval access.\n\nSubmit `ApprovalRequest` and `ApprovalDecision` bodies through\n`POST /aip/v1/messages`. There is no dedicated approval mutation route.\n\n## Transaction and callback-delivery routes\n\n| Method | Path | Purpose |\n|---|---|---|\n| `GET` | `/aip/v1/transactions/{transaction_id}` | Read by transaction ID |\n| `GET` | `/aip/v1/transactions/by-plan/{plan_id}` | Read by plan ID |\n| `GET` | `/aip/v1/transactions/by-action/{action_id}` | Read by action ID |\n| `GET` | `/aip/v1/callback-deliveries` | List durable callback deliveries |\n| `GET` | `/aip/v1/callback-deliveries/{delivery_id}` | Read one delivery |\n\nAll transaction routes accept `tenant_id`, `include_result`, and\n`include_receipts`.\n\nThe callback list accepts `action_id`, `status`, `profile`, `target`,\n`tenant_id`, `cursor`, `limit`, and `include_receipts`. The one-record\nroute accepts `tenant_id` and `include_receipts`.\n\nThese routes are read-only. This revision has no public callback replay route\nand no dedicated remote-delegation outbox route.\n\n## Receipt and audit routes\n\n| Method | Path | Purpose |\n|---|---|---|\n| `GET` | `/aip/v1/receipts/{chain_id}` | Read one receipt chain |\n| `GET` | `/aip/v1/receipts/by-receipt/{receipt_id}` | Find the chain containing a receipt |\n| `GET` | `/aip/v1/audit/events` | Query visible audit events |\n\nAudit filters are `action_id`, `session_id`, `principal_id`,\n`tenant_id`, `transaction_id`, RFC 3339 `from` and `to`, `cursor`,\nand `limit`. `include_receipts=true` and `export=true` both use an\nexport-class authorization check. Export also forces receipt inclusion.\n\nOrdinary audit reads may be narrowed to the authenticated principal when the\nidentity lacks a cross-principal read or export scope.\n\n## Resource routes\n\n| Method | Path | Purpose |\n|---|---|---|\n| `GET` | `/aip/v1/resources` | List visible resources |\n| `GET` | `/aip/v1/resources/{resource_id}` | Read one resource |\n\nList filters are `capability_id`, `kind`, `tenant_id`, `cursor`, and\n`limit`. A one-resource read accepts `tenant_id`, `version`, and a\ncomma-separated `accept` preference.\n\n## Tenant capability catalog\n\n| Method | Path | Purpose |\n|---|---|---|\n| `GET` | `/aip/v1/capabilities` | Search connector capabilities visible to the configured tenant |\n\nFilters are `capability_id`, case-insensitive `text`, `profile`,\n`cursor`, and `limit`. The response contains `catalog_revision`,\n`capabilities`, `next_cursor`, and `total`.\n\nThe route requires both native bearer authentication and a tenant configured\nfor that bearer identity. It returns:\n\n| Status | Code | Condition |\n|---:|---|---|\n| `404` | `connector_catalog.disabled` | No fleet catalog provider is configured |\n| `403` | `connector_catalog.tenant_required` | The bearer identity has no configured tenant |\n| `400` | `connector_catalog.invalid_query` | A typed filter is invalid |\n| `409` | `connector_catalog.stale_cursor` | The catalog revision changed during pagination |\n| `503` | `connector_catalog.unavailable` | The registry query failed |\n\nThe default requested size is 100. The reviewed registry clamps the requested\nrow limit between 1 and 200 and caps one page at 4 MiB of canonical capability\ndefinitions. A valid query can still return zero matches. A stale cursor must\nrestart from the first page.\n\n## Pagination, expansions, and cursors\n\nDurable action, session, approval, callback, resource, audit, and event lists\ndefault to 100 rows. The runtime clamps their requested row count between 1 and\n1,000 rather than rejecting an out-of-range value. Event pages are also bounded\nto 4 MiB.\n\nCursors are route-specific continuation tokens. Echo only a cursor returned by\nthe same operation and identity context. Do not parse or manufacture it.\nCapability catalog cursors additionally bind a catalog revision.\n\nExpansion flags default to false. Request results, receipts, chunks, approval\nevidence, or audit export only when the caller has a real need and the required\ndisclosure authority.\n\n## SSE and WebSocket\n\n`follow=true` on action events, action chunks, or global events returns SSE.\nThe current follow loop polls the durable view every 500 ms and sends a\nkeep-alive every 15 seconds. Action-scoped follow ends when the response marks\nthe action terminal; global follow continues until disconnect or error.\n\n| Method | Path | Purpose |\n|---|---|---|\n| `GET` | `/aip/v1/ws` | Upgrade to the authenticated native WebSocket transport |\n\nThe route performs a native-authenticated WebSocket upgrade. A text\nframe can contain:\n\n- one encoded AIP `Envelope`, which receives one response envelope; or\n- a JSON control object with `\"type\": \"subscribe\"` for action-scoped or global\n  event reads.\n\nA subscription accepts `subscription_id`, `action_id`, `session_id`,\n`tenant_id`, `cursor`, `limit`, `kind`, `kinds`,\n`include_chunks`, and `follow`. The reviewed server permits at most 16\nconcurrent subscriptions per connection and buffers eight outbound frames.\nThose are implementation limits, not AIP wire requirements.\n\nThe [transport bindings](transport-bindings.md) reference owns reconnect,\nbackpressure, and delivery semantics.\n\n## Separate fleet, host, and profile surfaces\n\nThese related routes do not belong to the ergonomic client API:\n\n| Process | Routes | Canonical owner |\n|---|---|---|\n| `getaip-server` connector ingress | `POST /aip/v1/connector-events`, `POST /aip/v1/connector-callbacks` | [Connector fleet API](connector-fleet-api.md) |\n| Lifecycle control plane | `GET /health`, `GET /ready`, `GET /metrics`, `POST /aip/v1/connector-control` | Connector fleet API |\n| Standalone connector host | `GET /health`, `GET /ready`, `GET /metrics`, `GET /aip/v1/manifest`, `POST /aip/v1/messages` | Connector fleet API and connector-local operations |\n\nMCP and A2A have their own HTTP routes, media types, sessions, and error\nmappings. Use [AIP through MCP](../guides/use-aip-through-mcp.md) or [AIP\nthrough A2A](../guides/use-aip-through-a2a.md). Product-specific or\nmigration-only module mounts are not part of the product-neutral native route\ninventory.\n\n## Errors\n\nInvalid path identifiers and typed filters return HTTP `400`. Missing bearer\nauthentication returns `401`. Runtime errors map their `ProtocolError`\ncategory and code to an HTTP status, and ergonomic routes return that error in a\ncomplete envelope. Clients must use the typed error and retry fields rather\nthan the status code alone.\n\n## Related documentation\n\n- [Use native AIP](../guides/use-native-aip.md)\n- [JSON schemas](../spec/schemas.md)\n- [Errors and retry decisions](errors.md)\n",
    "text": "Native HTTP API\n\nThis reference lists the native HTTP surface implemented by the\nproduct-neutral getaip-server gateway. Use it to select a route, identify its\napplication authentication boundary, construct query parameters, and interpret\nthe current response form.\n\nThe route inventory applies to source revision\nd7cce13d1d555644d04a4d73c66c95b113737635. It describes an implementation\nbinding, not additional AIP 1.0 wire requirements. Normative message fields\nremain owned by the protocol schemas.\n\nRoute and authentication classes\n\nThe router has four native security classes:\n\n| Class | Routes | Authentication in getaip-server |\n\n| Service and public discovery | /, /health, /ready, /metrics, /aip/v1/health, /aip/v1/manifest | No application middleware; protect operational data at the deployment edge |\n| Generic native envelope | POST /aip/v1/messages | Configured bearer identity when presented; otherwise native envelope signature policy; loopback insecure development only when explicitly enabled |\n| Ergonomic native API | Actions, events, sessions, approvals, transactions, deliveries, receipts, audit, resources, capabilities, and WebSocket | Native bearer middleware, or the explicit loopback development identity |\n| Connector ingress | POST /aip/v1/connector-events and POST /aip/v1/connector-callbacks | Signed connector route, sender, tenant, lease, and replay validation inside the ingress handler |\n\nThe first class is unprotected only inside the application router. A reverse\nproxy or network policy should restrict readiness and metrics according to the\ndeployment boundary. Public manifest exposure is a deployment decision.\n\nThe connector-ingress routes are not client action routes. Their detailed\ncontract belongs to the connector-fleet API.\n\nAuthentication and trusted context\n\nThe direct getaip-server native HTTP edge supports one configured static bearer\ncredential. A successful comparison establishes the configured principal,\nscopes, and optional tenant as server-owned context. The gateway replaces\npayload sender claims with that authenticated principal.\n\nAll ergonomic routes pass through the native-auth middleware. With bearer\nauthentication configured, a missing or invalid credential returns HTTP 401\nwith error code auth.nativehttpunauthorized. An explicit loopback\ndevelopment mode can substitute the daemon identity; it is not a production\nauthentication mode.\n\nPOST /aip/v1/messages is different. With a valid bearer credential, it uses\nthe trusted HTTP-edge identity and enforces replay policy. Without a bearer\nidentity, it sends the envelope through native signature verification, trusted\nsigner binding, and replay policy. The default gateway policy requires a\ntrusted signed envelope on that path.\n\nA tenantid, principal filter, or sender field supplied by the client does\nnot grant authority. Runtime query authorization still checks the established\nprincipal, scopes, object owner, and tenant. See Identity and\ntrust (../concepts/identity-and-trust.md) for that authorization model.\n\nRepresentations and response forms\n\nThe native envelope media type is application/aip+json. The current Axum\nhandlers use JSON extraction and JSON responses; ordinary JSON responses carry\napplication/json. Follow-mode event responses carry\ntext/event-stream.\n\nTimestamps in native records use RFC 3339. Identifiers are opaque. Clients\nshould validate their documented prefix and length rules but must not derive\ntime, tenant, or topology from their contents.\n\nResponse form depends on the route:\n\n| Route class | Success | Error |\n\n| POST /aip/v1/messages and POST /aip/v1/actions | Complete AIP response Envelope | Complete Envelope with an error body |\n| Ergonomic native queries and operations | Native body object such as ActionStatus or ApprovalList | Complete Envelope with ProtocolError |\n| Tenant capability catalog | CapabilityPage | Direct {\"error\": {\"code\": ..., \"message\": ...}} object |\n| Health, readiness, metrics, and manifest | Route-specific JSON or Prometheus text | Route-specific response |\n| SSE follow | Named SSE events with JSON data and cursor IDs | One terminal SSE error event |\n\nService and manifest routes\n\n| Method | Path | Response |\n\n| GET | / | Process liveness payload |\n| GET | /health | Process liveness payload |\n| GET | /ready | Core readiness; HTTP 200 or 503 |\n| GET | /metrics | Prometheus text exposition |\n| GET | /aip/v1/health | Versioned alias of process liveness |\n| GET | /aip/v1/manifest | Complete or filtered participant Manifest |\n| POST | /aip/v1/messages | Response envelope for any supported native message body |\n\nGET /aip/v1/manifest accepts:\n\n| Parameter | Form |\n\n| capabilityid | Comma-separated capability IDs |\n| resourcekind | Comma-separated resource kinds |\n| profile | Comma-separated profile IDs |\n| risk | Comma-separated risk values |\n| sideeffect | Comma-separated side-effect values |\n| requiresapproval | Boolean |\n| supportsstreaming | Boolean |\n| supportstransactions | Boolean |\n\nAn empty filter returns the complete local manifest. This route does not\ninclude the tenant connector-fleet catalog.\n\nAction routes\n\n| Method | Path | Purpose |\n\n| POST | /aip/v1/actions | Submit an envelope through the action-oriented alias |\n| GET | /aip/v1/actions | List visible durable action views |\n| GET | /aip/v1/actions/{actionid} | Read one ActionStatus |\n| GET | /aip/v1/actions/{actionid}/result | Read the terminal ActionResult |\n| GET | /aip/v1/actions/{actionid}/events | Read or follow action events |\n| GET | /aip/v1/actions/{actionid}/chunks | Read or follow stream chunks |\n| POST | /aip/v1/actions/{actionid}/cancel | Request cancellation |\n\nBoth submission paths call the same envelope handler at this revision.\nPOST /aip/v1/actions is the action-oriented, bearer-authenticated alias, but\nthe handler does not reject another supported body type solely because of that\npath. Use /aip/v1/messages for non-action message families.\n\nList actions\n\nGET /aip/v1/actions accepts:\n\n| Parameter | Meaning |\n\n| state | Stable lifecycle state |\n| capabilityid | Exact capability ID |\n| sessionid | Exact session ID |\n| principalid | Requesting principal recorded for the queued action |\n| tenantid | Exact tenant boundary |\n| approvalid | Linked approval |\n| transactionid | Linked transaction |\n| cursor | Page cursor returned by this route |\n| limit | Requested page size |\n| includeresults | Include available final results |\n| includereceipts | Include available receipt chains |\n\nThe response is ActionList with actions, totalsize, and an optional\nnext cursor.\n\nRead status or result\n\nThe status route accepts tenantid, includeresult,\nincludereceipts, includechunks, and waitms. The result route\naccepts tenantid, waitms, includereceipt, and\nincludeterminalevents.\n\nwaitms is serialized into the current request object, but the reviewed\nruntime does not wait. Status returns the current view immediately. Result\nreturns the current terminal result or an action.resultnotready error.\nClients that need waiting should follow events or poll with their own bounded\ndeadline.\n\nRead events or chunks\n\nThe action-events route accepts:\n\n| Parameter | Meaning |\n\n| tenantid | Expected tenant boundary |\n| cursor | Opaque event cursor |\n| limit | Requested page size |\n| kind | One event kind |\n| kinds | Comma-separated event kinds |\n| includechunks | Include durable stream chunks |\n| follow | Return an SSE follow stream |\n\nWhen cursor is absent, Last-Event-ID supplies the cursor. The chunks\nroute uses tenantid, cursor, limit, and follow, and always\nselects aip.stream.chunk with chunks included.\n\nCancellation accepts an optional JSON object:\n\n{\n  \"reason\": \"The caller no longer needs the result\"\n}\n\nA successful cancellation response does not prove that an external provider\neffect was reversed.\n\nGlobal event route\n\n| Method | Path | Purpose |\n\n| GET | /aip/v1/events | Read or follow events visible to the authenticated identity |\n\nUsed parameters are cursor, limit, kind, comma-separated kinds,\nand follow. A query cursor takes precedence over Last-Event-ID.\nAuthorization limits the returned principals and tenants; the global route\ndoes not use a caller-supplied tenant filter.\n\nSession routes\n\n| Method | Path | Purpose |\n\n| GET | /aip/v1/sessions | List visible sessions |\n| GET | /aip/v1/sessions/{sessionid} | Read one session |\n| POST | /aip/v1/sessions/{sessionid}/close | Close a session |\n| POST | /aip/v1/sessions/{sessionid}/resume | Resume a session |\n| POST | /aip/v1/sessions/{sessionid}:close | Suffix-form close alias |\n| POST | /aip/v1/sessions/{sessionid}:resume | Suffix-form resume alias |\n\nThe list route accepts principalid, status, cursor, and limit.\nClose accepts an optional reason. Resume accepts resumetoken and\nlasteventcursor. A successful resume rotates the token; replace the\nsupplied token with the returned one. Actions and\nsessions (../concepts/actions-and-sessions.md) owns the lifecycle rules.\n\nApproval routes\n\n| Method | Path | Purpose |\n\n| GET | /aip/v1/approvals | List visible approval records |\n| GET | /aip/v1/approvals/{approvalid} | Read one approval record |\n\nList filters are status, approver, requester, tenantid,\ncursor, and limit. includeactionstatus and\nincludereceipts add their corresponding views.\n\nThe one-record route accepts tenantid, includeactionstatus,\nincludereceipts, and includeevidencepayload. Evidence payload\nexpansion uses export authorization and requires the approval:sensitive\nscope in addition to approval access.\n\nSubmit ApprovalRequest and ApprovalDecision bodies through\nPOST /aip/v1/messages. There is no dedicated approval mutation route.\n\nTransaction and callback-delivery routes\n\n| Method | Path | Purpose |\n\n| GET | /aip/v1/transactions/{transactionid} | Read by transaction ID |\n| GET | /aip/v1/transactions/by-plan/{planid} | Read by plan ID |\n| GET | /aip/v1/transactions/by-action/{actionid} | Read by action ID |\n| GET | /aip/v1/callback-deliveries | List durable callback deliveries |\n| GET | /aip/v1/callback-deliveries/{deliveryid} | Read one delivery |\n\nAll transaction routes accept tenantid, includeresult, and\nincludereceipts.\n\nThe callback list accepts actionid, status, profile, target,\ntenantid, cursor, limit, and includereceipts. The one-record\nroute accepts tenantid and includereceipts.\n\nThese routes are read-only. This revision has no public callback replay route\nand no dedicated remote-delegation outbox route.\n\nReceipt and audit routes\n\n| Method | Path | Purpose |\n\n| GET | /aip/v1/receipts/{chainid} | Read one receipt chain |\n| GET | /aip/v1/receipts/by-receipt/{receiptid} | Find the chain containing a receipt |\n| GET | /aip/v1/audit/events | Query visible audit events |\n\nAudit filters are actionid, sessionid, principalid,\ntenantid, transactionid, RFC 3339 from and to, cursor,\nand limit. includereceipts=true and export=true both use an\nexport-class authorization check. Export also forces receipt inclusion.\n\nOrdinary audit reads may be narrowed to the authenticated principal when the\nidentity lacks a cross-principal read or export scope.\n\nResource routes\n\n| Method | Path | Purpose |\n\n| GET | /aip/v1/resources | List visible resources |\n| GET | /aip/v1/resources/{resourceid} | Read one resource |\n\nList filters are capabilityid, kind, tenantid, cursor, and\nlimit. A one-resource read accepts tenantid, version, and a\ncomma-separated accept preference.\n\nTenant capability catalog\n\n| Method | Path | Purpose |\n\n| GET | /aip/v1/capabilities | Search connector capabilities visible to the configured tenant |\n\nFilters are capabilityid, case-insensitive text, profile,\ncursor, and limit. The response contains catalogrevision,\ncapabilities, nextcursor, and total.\n\nThe route requires both native bearer authentication and a tenant configured\nfor that bearer identity. It returns:\n\n| Status | Code | Condition |\n\n| 404 | connectorcatalog.disabled | No fleet catalog provider is configured |\n| 403 | connectorcatalog.tenantrequired | The bearer identity has no configured tenant |\n| 400 | connectorcatalog.invalidquery | A typed filter is invalid |\n| 409 | connectorcatalog.stalecursor | The catalog revision changed during pagination |\n| 503 | connectorcatalog.unavailable | The registry query failed |\n\nThe default requested size is 100. The reviewed registry clamps the requested\nrow limit between 1 and 200 and caps one page at 4 MiB of canonical capability\ndefinitions. A valid query can still return zero matches. A stale cursor must\nrestart from the first page.\n\nPagination, expansions, and cursors\n\nDurable action, session, approval, callback, resource, audit, and event lists\ndefault to 100 rows. The runtime clamps their requested row count between 1 and\n1,000 rather than rejecting an out-of-range value. Event pages are also bounded\nto 4 MiB.\n\nCursors are route-specific continuation tokens. Echo only a cursor returned by\nthe same operation and identity context. Do not parse or manufacture it.\nCapability catalog cursors additionally bind a catalog revision.\n\nExpansion flags default to false. Request results, receipts, chunks, approval\nevidence, or audit export only when the caller has a real need and the required\ndisclosure authority.\n\nSSE and WebSocket\n\nfollow=true on action events, action chunks, or global events returns SSE.\nThe current follow loop polls the durable view every 500 ms and sends a\nkeep-alive every 15 seconds. Action-scoped follow ends when the response marks\nthe action terminal; global follow continues until disconnect or error.\n\n| Method | Path | Purpose |\n\n| GET | /aip/v1/ws | Upgrade to the authenticated native WebSocket transport |\n\nThe route performs a native-authenticated WebSocket upgrade. A text\nframe can contain:\n• one encoded AIP Envelope, which receives one response envelope; or\n• a JSON control object with \"type\": \"subscribe\" for action-scoped or global\n  event reads.\n\nA subscription accepts subscriptionid, actionid, sessionid,\ntenantid, cursor, limit, kind, kinds,\nincludechunks, and follow. The reviewed server permits at most 16\nconcurrent subscriptions per connection and buffers eight outbound frames.\nThose are implementation limits, not AIP wire requirements.\n\nThe transport bindings (transport-bindings.md) reference owns reconnect,\nbackpressure, and delivery semantics.\n\nSeparate fleet, host, and profile surfaces\n\nThese related routes do not belong to the ergonomic client API:\n\n| Process | Routes | Canonical owner |\n\n| getaip-server connector ingress | POST /aip/v1/connector-events, POST /aip/v1/connector-callbacks | Connector fleet API (connector-fleet-api.md) |\n| Lifecycle control plane | GET /health, GET /ready, GET /metrics, POST /aip/v1/connector-control | Connector fleet API |\n| Standalone connector host | GET /health, GET /ready, GET /metrics, GET /aip/v1/manifest, POST /aip/v1/messages | Connector fleet API and connector-local operations |\n\nMCP and A2A have their own HTTP routes, media types, sessions, and error\nmappings. Use AIP through MCP (../guides/use-aip-through-mcp.md) or AIP\nthrough A2A (../guides/use-aip-through-a2a.md). Product-specific or\nmigration-only module mounts are not part of the product-neutral native route\ninventory.\n\nErrors\n\nInvalid path identifiers and typed filters return HTTP 400. Missing bearer\nauthentication returns 401. Runtime errors map their ProtocolError\ncategory and code to an HTTP status, and ergonomic routes return that error in a\ncomplete envelope. Clients must use the typed error and retry fields rather\nthan the status code alone.\n\nRelated documentation\n• Use native AIP (../guides/use-native-aip.md)\n• JSON schemas (../spec/schemas.md)\n• Errors and retry decisions (errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "8c4eab689a3764a9d676a128693791e6afa6634fa9d3b1f9f159393d66825aa2"
  }
}