---
title: Twenty OpenAPI documents
description: >-
  Read workspace-specific core and metadata OpenAPI documents through fixed
  authenticated AIP Resources
kind: capability-reference
audience: integrator
appliesTo: "1.x"
writingStandard: "aip-docs/1.0"
lastReviewedRevision: "97be86e9efedf07ecf1783b03800f683f107fb04"
connector: twenty
capabilityIds:
  - cap:twenty:openapi.core
  - cap:twenty:openapi.metadata
---

# Twenty OpenAPI documents

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.

The returned document is provider evidence from one request. It is not a new
connector catalogue, execution proxy, compatibility decision, or authorization
to call an arbitrary documented endpoint.

## Compare the resources

| Capability | Provider request | Input | Purpose |
|---|---|---|---|
| `openapi.core` | `GET /rest/open-api/core` | Empty object | Read core record API description |
| `openapi.metadata` | `GET /rest/open-api/metadata` | Empty object | Read metadata API description |

Both capabilities are low-risk AIP Resources. They require no approval, accept
an optional idempotency key, and advertise safe connector retry.

Both support synchronous execution only. Neither supports asynchronous
execution, streaming, cancellation, transactions, or compensation.

## Read the core document

Invoke `cap:twenty:openapi.core` with an empty JSON object:

```json
{}
```

The connector sends authenticated `GET /rest/open-api/core` to the fixed
origin. No Action field can change the path, origin, workspace, or token.

Use the core document to inspect record objects, fields, request and response
shapes, and provider routes visible to the configured credential. Treat every
provider extension according to the document's own semantics.

The connector's health method uses the same core path but does not decode or
retain its OpenAPI body. A successful health status proves authenticated path
reachability at that moment, not a complete document validation.

## Read the metadata document

Invoke `cap:twenty:openapi.metadata` with the same empty input:

```json
{}
```

The connector sends authenticated `GET /rest/open-api/metadata`. This resource
is independent of the core health probe.

Use the document to inspect metadata resource shapes and provider definitions.
The connector still exposes only its twelve fixed metadata resource names and
five fixed metadata operations.

A route appearing in the provider document does not make it callable through
the connector.

## Interpret the result wrapper

A completed Action has this connector-owned output shape:

```json
{
  "http_status": 200,
  "provider_request_id": "provider-request-id-or-null",
  "body": {}
}
```

`body` is the decoded provider JSON without OpenAPI normalization, bundling,
reference resolution, validation, or canonical hashing. Empty response bytes
become JSON `null`.

`provider_request_id` comes from a valid `x-request-id`, then `traceparent`, and
is absent when neither bounded header is available.

The configured response ceiling defaults to 64 MiB and accepts values through
256 MiB. A declared or accumulated response above the effective bound fails
without returning a partial document.

## Use the documents for drift review

Record these identities with every retained document:

- AIP source revision;
- connector artifact digest and version;
- pinned provider mapping revision;
- connector instance, replica, tenant, and workspace identities;
- credential revision without secret bytes;
- Action ID, timestamp, HTTP status, and provider request ID;
- complete document digest calculated outside the connector;
- redaction and access-control decisions for the retained body.

Compare the observed document with the connector's fixed operation and schema
mapping. Classify additions, removals, changed fields, changed paths, changed
authentication, and changed semantics before updating compatibility claims.

An observed difference is drift evidence. It does not determine whether the
provider or connector is correct, whether the change is backward compatible,
or whether an artifact has passed qualification.

## Keep execution separate from description

The connector does not:

- execute paths found in an OpenAPI document;
- synthesize new AIP capabilities from provider operations;
- accept caller-selected REST paths or methods;
- expose GraphQL query execution;
- create or rotate provider API tokens;
- validate provider document conformance to its own implementation;
- reconcile the document with the pinned mapping automatically.

Use fixed admitted capabilities for execution. Change the mapping through
source review, schema review, tests, admission, and artifact qualification.

## Handle failures and retry

| Condition | Connector code | Decision |
|---|---|---|
| Non-empty or unknown input field | `connector.twenty.invalid_request` | Submit exactly `{}` |
| Provider `401` or `403` | `connector.twenty.authentication` | Repair host credential or workspace binding |
| Provider `429` or `5xx` | `connector.twenty.remote_temporary` | Retry the same read according to policy |
| Other provider non-success | `connector.twenty.remote_rejected` | Inspect fixed provider compatibility and permissions |
| Transport failure | `connector.twenty.transport` | Retryable for these reads |
| Oversized or invalid JSON response | `connector.twenty.invalid_response` | Preserve evidence and investigate provider drift or limit |

Retry with the same Action intent and fixed route. A retry can observe a newer
provider document; retain timestamps and digests when comparison matters.

## Security and data boundaries

Both contracts declare confidential data, possible personal information, and
required redaction. OpenAPI documents can expose tenant-specific object names,
custom fields, identifiers, route shapes, and provider extensions.

Store retained documents under tenant-scoped access and retention controls.
Do not publish an observed workspace document merely because its format is
OpenAPI.

The connector does not remove fields from these resource bodies. Apply
workspace-specific redaction before attaching them to issues, evidence bundles,
or public compatibility reports.

## Related documentation

- [Twenty capability index](README.md)
- [Twenty workspace metadata](workspace-metadata.md)
- [Twenty connector configuration](../reference/configuration.md)
- [Connector upstream baselines](../../upstream-baselines.md)
- [Errors and retry decisions](../../../reference/errors.md)