{
  "schemaVersion": "1.0",
  "title": "Twenty OpenAPI documents",
  "description": "Use these two Resource capabilities to read the configured workspace's current core or metadata OpenAPI document. The connector fixes both provider routes and adds its host-owned workspace credential.",
  "canonical": "https://getaip.org/docs/connectors/twenty/capabilities/openapi-documents",
  "route": "/docs/connectors/twenty/capabilities/openapi-documents",
  "source": "docs/connectors/twenty/capabilities/openapi-documents.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/twenty/capabilities/openapi-documents.md",
    "txt": "/docs/download/connectors/twenty/capabilities/openapi-documents.txt",
    "json": "/docs/download/connectors/twenty/capabilities/openapi-documents.json",
    "pdf": "/docs/download/connectors/twenty/capabilities/openapi-documents.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Twenty OpenAPI documents\ndescription: >-\n  Read workspace-specific core and metadata OpenAPI documents through fixed\n  authenticated AIP Resources\nkind: capability-reference\naudience: integrator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: twenty\ncapabilityIds:\n  - cap:twenty:openapi.core\n  - cap:twenty:openapi.metadata\n---\n\n# Twenty OpenAPI documents\n\nUse these two Resource capabilities to read the configured workspace's current\ncore or metadata OpenAPI document. The connector fixes both provider routes and\nadds its host-owned workspace credential.\n\nThe returned document is provider evidence from one request. It is not a new\nconnector catalogue, execution proxy, compatibility decision, or authorization\nto call an arbitrary documented endpoint.\n\n## Compare the resources\n\n| Capability | Provider request | Input | Purpose |\n|---|---|---|---|\n| `openapi.core` | `GET /rest/open-api/core` | Empty object | Read core record API description |\n| `openapi.metadata` | `GET /rest/open-api/metadata` | Empty object | Read metadata API description |\n\nBoth capabilities are low-risk AIP Resources. They require no approval, accept\nan optional idempotency key, and advertise safe connector retry.\n\nBoth support synchronous execution only. Neither supports asynchronous\nexecution, streaming, cancellation, transactions, or compensation.\n\n## Read the core document\n\nInvoke `cap:twenty:openapi.core` with an empty JSON object:\n\n```json\n{}\n```\n\nThe connector sends authenticated `GET /rest/open-api/core` to the fixed\norigin. No Action field can change the path, origin, workspace, or token.\n\nUse the core document to inspect record objects, fields, request and response\nshapes, and provider routes visible to the configured credential. Treat every\nprovider extension according to the document's own semantics.\n\nThe connector's health method uses the same core path but does not decode or\nretain its OpenAPI body. A successful health status proves authenticated path\nreachability at that moment, not a complete document validation.\n\n## Read the metadata document\n\nInvoke `cap:twenty:openapi.metadata` with the same empty input:\n\n```json\n{}\n```\n\nThe connector sends authenticated `GET /rest/open-api/metadata`. This resource\nis independent of the core health probe.\n\nUse the document to inspect metadata resource shapes and provider definitions.\nThe connector still exposes only its twelve fixed metadata resource names and\nfive fixed metadata operations.\n\nA route appearing in the provider document does not make it callable through\nthe connector.\n\n## Interpret the result wrapper\n\nA completed Action has this connector-owned output shape:\n\n```json\n{\n  \"http_status\": 200,\n  \"provider_request_id\": \"provider-request-id-or-null\",\n  \"body\": {}\n}\n```\n\n`body` is the decoded provider JSON without OpenAPI normalization, bundling,\nreference resolution, validation, or canonical hashing. Empty response bytes\nbecome JSON `null`.\n\n`provider_request_id` comes from a valid `x-request-id`, then `traceparent`, and\nis absent when neither bounded header is available.\n\nThe configured response ceiling defaults to 64 MiB and accepts values through\n256 MiB. A declared or accumulated response above the effective bound fails\nwithout returning a partial document.\n\n## Use the documents for drift review\n\nRecord these identities with every retained document:\n\n- AIP source revision;\n- connector artifact digest and version;\n- pinned provider mapping revision;\n- connector instance, replica, tenant, and workspace identities;\n- credential revision without secret bytes;\n- Action ID, timestamp, HTTP status, and provider request ID;\n- complete document digest calculated outside the connector;\n- redaction and access-control decisions for the retained body.\n\nCompare the observed document with the connector's fixed operation and schema\nmapping. Classify additions, removals, changed fields, changed paths, changed\nauthentication, and changed semantics before updating compatibility claims.\n\nAn observed difference is drift evidence. It does not determine whether the\nprovider or connector is correct, whether the change is backward compatible,\nor whether an artifact has passed qualification.\n\n## Keep execution separate from description\n\nThe connector does not:\n\n- execute paths found in an OpenAPI document;\n- synthesize new AIP capabilities from provider operations;\n- accept caller-selected REST paths or methods;\n- expose GraphQL query execution;\n- create or rotate provider API tokens;\n- validate provider document conformance to its own implementation;\n- reconcile the document with the pinned mapping automatically.\n\nUse fixed admitted capabilities for execution. Change the mapping through\nsource review, schema review, tests, admission, and artifact qualification.\n\n## Handle failures and retry\n\n| Condition | Connector code | Decision |\n|---|---|---|\n| Non-empty or unknown input field | `connector.twenty.invalid_request` | Submit exactly `{}` |\n| Provider `401` or `403` | `connector.twenty.authentication` | Repair host credential or workspace binding |\n| Provider `429` or `5xx` | `connector.twenty.remote_temporary` | Retry the same read according to policy |\n| Other provider non-success | `connector.twenty.remote_rejected` | Inspect fixed provider compatibility and permissions |\n| Transport failure | `connector.twenty.transport` | Retryable for these reads |\n| Oversized or invalid JSON response | `connector.twenty.invalid_response` | Preserve evidence and investigate provider drift or limit |\n\nRetry with the same Action intent and fixed route. A retry can observe a newer\nprovider document; retain timestamps and digests when comparison matters.\n\n## Security and data boundaries\n\nBoth contracts declare confidential data, possible personal information, and\nrequired redaction. OpenAPI documents can expose tenant-specific object names,\ncustom fields, identifiers, route shapes, and provider extensions.\n\nStore retained documents under tenant-scoped access and retention controls.\nDo not publish an observed workspace document merely because its format is\nOpenAPI.\n\nThe connector does not remove fields from these resource bodies. Apply\nworkspace-specific redaction before attaching them to issues, evidence bundles,\nor public compatibility reports.\n\n## Related documentation\n\n- [Twenty capability index](README.md)\n- [Twenty workspace metadata](workspace-metadata.md)\n- [Twenty connector configuration](../reference/configuration.md)\n- [Connector upstream baselines](../../upstream-baselines.md)\n- [Errors and retry decisions](../../../reference/errors.md)\n",
    "text": "Twenty OpenAPI documents\n\nUse these two Resource capabilities to read the configured workspace's current\ncore or metadata OpenAPI document. The connector fixes both provider routes and\nadds its host-owned workspace credential.\n\nThe returned document is provider evidence from one request. It is not a new\nconnector catalogue, execution proxy, compatibility decision, or authorization\nto call an arbitrary documented endpoint.\n\nCompare the resources\n\n| Capability | Provider request | Input | Purpose |\n\n| openapi.core | GET /rest/open-api/core | Empty object | Read core record API description |\n| openapi.metadata | GET /rest/open-api/metadata | Empty object | Read metadata API description |\n\nBoth capabilities are low-risk AIP Resources. They require no approval, accept\nan optional idempotency key, and advertise safe connector retry.\n\nBoth support synchronous execution only. Neither supports asynchronous\nexecution, streaming, cancellation, transactions, or compensation.\n\nRead the core document\n\nInvoke cap:twenty:openapi.core with an empty JSON object:\n\n{}\n\nThe connector sends authenticated GET /rest/open-api/core to the fixed\norigin. No Action field can change the path, origin, workspace, or token.\n\nUse the core document to inspect record objects, fields, request and response\nshapes, and provider routes visible to the configured credential. Treat every\nprovider extension according to the document's own semantics.\n\nThe connector's health method uses the same core path but does not decode or\nretain its OpenAPI body. A successful health status proves authenticated path\nreachability at that moment, not a complete document validation.\n\nRead the metadata document\n\nInvoke cap:twenty:openapi.metadata with the same empty input:\n\n{}\n\nThe connector sends authenticated GET /rest/open-api/metadata. This resource\nis independent of the core health probe.\n\nUse the document to inspect metadata resource shapes and provider definitions.\nThe connector still exposes only its twelve fixed metadata resource names and\nfive fixed metadata operations.\n\nA route appearing in the provider document does not make it callable through\nthe connector.\n\nInterpret the result wrapper\n\nA completed Action has this connector-owned output shape:\n\n{\n  \"httpstatus\": 200,\n  \"providerrequestid\": \"provider-request-id-or-null\",\n  \"body\": {}\n}\n\nbody is the decoded provider JSON without OpenAPI normalization, bundling,\nreference resolution, validation, or canonical hashing. Empty response bytes\nbecome JSON null.\n\nproviderrequestid comes from a valid x-request-id, then traceparent, and\nis absent when neither bounded header is available.\n\nThe configured response ceiling defaults to 64 MiB and accepts values through\n256 MiB. A declared or accumulated response above the effective bound fails\nwithout returning a partial document.\n\nUse the documents for drift review\n\nRecord these identities with every retained document:\n• AIP source revision;\n• connector artifact digest and version;\n• pinned provider mapping revision;\n• connector instance, replica, tenant, and workspace identities;\n• credential revision without secret bytes;\n• Action ID, timestamp, HTTP status, and provider request ID;\n• complete document digest calculated outside the connector;\n• redaction and access-control decisions for the retained body.\n\nCompare the observed document with the connector's fixed operation and schema\nmapping. Classify additions, removals, changed fields, changed paths, changed\nauthentication, and changed semantics before updating compatibility claims.\n\nAn observed difference is drift evidence. It does not determine whether the\nprovider or connector is correct, whether the change is backward compatible,\nor whether an artifact has passed qualification.\n\nKeep execution separate from description\n\nThe connector does not:\n• execute paths found in an OpenAPI document;\n• synthesize new AIP capabilities from provider operations;\n• accept caller-selected REST paths or methods;\n• expose GraphQL query execution;\n• create or rotate provider API tokens;\n• validate provider document conformance to its own implementation;\n• reconcile the document with the pinned mapping automatically.\n\nUse fixed admitted capabilities for execution. Change the mapping through\nsource review, schema review, tests, admission, and artifact qualification.\n\nHandle failures and retry\n\n| Condition | Connector code | Decision |\n\n| Non-empty or unknown input field | connector.twenty.invalidrequest | Submit exactly {} |\n| Provider 401 or 403 | connector.twenty.authentication | Repair host credential or workspace binding |\n| Provider 429 or 5xx | connector.twenty.remotetemporary | Retry the same read according to policy |\n| Other provider non-success | connector.twenty.remoterejected | Inspect fixed provider compatibility and permissions |\n| Transport failure | connector.twenty.transport | Retryable for these reads |\n| Oversized or invalid JSON response | connector.twenty.invalidresponse | Preserve evidence and investigate provider drift or limit |\n\nRetry with the same Action intent and fixed route. A retry can observe a newer\nprovider document; retain timestamps and digests when comparison matters.\n\nSecurity and data boundaries\n\nBoth contracts declare confidential data, possible personal information, and\nrequired redaction. OpenAPI documents can expose tenant-specific object names,\ncustom fields, identifiers, route shapes, and provider extensions.\n\nStore retained documents under tenant-scoped access and retention controls.\nDo not publish an observed workspace document merely because its format is\nOpenAPI.\n\nThe connector does not remove fields from these resource bodies. Apply\nworkspace-specific redaction before attaching them to issues, evidence bundles,\nor public compatibility reports.\n\nRelated documentation\n• Twenty capability index (README.md)\n• Twenty workspace metadata (workspace-metadata.md)\n• Twenty connector configuration (../reference/configuration.md)\n• Connector upstream baselines (../../upstream-baselines.md)\n• Errors and retry decisions (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "6bf34f350f63951681a3e54a7e0f1498d7736480f300b5b1c21f5a13e3a8da2c"
  }
}