openapi: 3.2.0 info: title: Acquia Content API version: '1.1' description: The stable JSON:API surface shared by every Source CMS site, plus the OAuth 2.0 authentication endpoints that issue the tokens it accepts. servers: - url: '{siteUrl}' description: 'Your site''s base URL, the canonical ACQUIA_SITE_URL environment variable, with no trailing slash. Source CMS serves JSON:API under /api; headless Cloud Platform sites serve it under /jsonapi. ' variables: siteUrl: default: https://your-site.example.com description: The ACQUIA_SITE_URL environment variable (no trailing slash). tags: - name: Content description: JSON:API resource endpoints for reading and writing entries. paths: /api: get: tags: - Content operationId: apiRoot summary: List available resource endpoints description: Returns the index of resource endpoints available on the site, keyed by resource type (for example `node--article`). No version segment appears in the path; every response reports `jsonapi.version` `1.1`. security: - bearerAuth: [] responses: '200': description: The API root document. content: application/vnd.api+json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /api/{entityType}/{bundle}: parameters: - $ref: '#/components/parameters/entityType' - $ref: '#/components/parameters/bundle' get: tags: - Content operationId: listEntries summary: List entries of a bundle description: A collection of entries of one bundle, for example `/api/node/article`. `data` is an array. `meta.count` is the collection total including entries the request cannot see, so `data` can be shorter than `meta.count`, or empty; check `meta.omitted` and follow `links.next`. security: - bearerAuth: [] - {} parameters: - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/sort' responses: '200': description: A JSON:API collection document. content: application/vnd.api+json: schema: $ref: '#/components/schemas/CollectionDocument' '401': $ref: '#/components/responses/Unauthorized' post: tags: - Content operationId: createEntry summary: Create an entry description: Requires the site's allowed-operations setting (`API > JSON:API`) set to "Read and write" and a token whose client has the `content:administer` scope. security: - bearerAuth: [] requestBody: required: true content: application/vnd.api+json: schema: $ref: '#/components/schemas/EntityDocument' responses: '201': description: The created entry. content: application/vnd.api+json: schema: $ref: '#/components/schemas/EntityDocument' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /api/{entityType}/{bundle}/{uuid}: parameters: - $ref: '#/components/parameters/entityType' - $ref: '#/components/parameters/bundle' - $ref: '#/components/parameters/uuid' get: tags: - Content operationId: getEntry summary: Get one entry description: One entry addressed by its UUID (the `id` in every response). `data` is a single object. security: - bearerAuth: [] - {} parameters: - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/include' responses: '200': description: A JSON:API entity document. content: application/vnd.api+json: schema: $ref: '#/components/schemas/EntityDocument' '401': $ref: '#/components/responses/Unauthorized' patch: tags: - Content operationId: updateEntry summary: Update an entry description: Requires writes enabled and the `content:administer` scope (same as POST). security: - bearerAuth: [] requestBody: required: true content: application/vnd.api+json: schema: $ref: '#/components/schemas/EntityDocument' responses: '200': description: The updated entry. content: application/vnd.api+json: schema: $ref: '#/components/schemas/EntityDocument' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' delete: tags: - Content operationId: deleteEntry summary: Delete an entry description: Requires writes enabled and the `content:administer` scope (same as POST). security: - bearerAuth: [] responses: '204': description: The entry was deleted. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /api/{entityType}/{bundle}/{uuid}/{field}: parameters: - $ref: '#/components/parameters/entityType' - $ref: '#/components/parameters/bundle' - $ref: '#/components/parameters/uuid' - name: field in: path required: true schema: type: string description: A relationship field machine name. get: tags: - Content operationId: getRelated summary: Get related entries description: The referenced entries themselves, with full attributes, that a relationship field points at. security: - bearerAuth: [] - {} responses: '200': description: A JSON:API document of the related entries. content: application/vnd.api+json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' /api/{entityType}/{bundle}/{uuid}/relationships/{field}: parameters: - $ref: '#/components/parameters/entityType' - $ref: '#/components/parameters/bundle' - $ref: '#/components/parameters/uuid' - name: field in: path required: true schema: type: string description: A relationship field machine name. get: tags: - Content operationId: getRelationship summary: Get a relationship's linkage description: The linkage only (type + id identifiers, no attributes). Use it to read or rewrite what an entry points at without fetching the targets. security: - bearerAuth: [] - {} responses: '200': description: A JSON:API relationship document. content: application/vnd.api+json: schema: type: object '401': $ref: '#/components/responses/Unauthorized' components: schemas: CollectionDocument: type: object properties: jsonapi: type: object properties: version: type: string const: '1.1' data: type: array items: $ref: '#/components/schemas/ResourceObject' meta: type: object properties: count: type: integer links: type: object included: type: array items: $ref: '#/components/schemas/ResourceObject' ErrorDocument: type: object properties: errors: type: array items: type: object properties: status: type: string title: type: string detail: type: string ResourceObject: type: object properties: type: type: string example: node--article id: type: string format: uuid attributes: type: object relationships: type: object EntityDocument: type: object properties: jsonapi: type: object properties: version: type: string const: '1.1' data: $ref: '#/components/schemas/ResourceObject' links: type: object included: type: array items: $ref: '#/components/schemas/ResourceObject' parameters: bundle: name: bundle in: path required: true schema: type: string example: article description: A bundle machine name (for example `article`). The [content model reference](/source-cms/reference/content-model/#entity-types-and-bundles) maps each entity type to its bundle term and endpoint pattern. sort: name: sort in: query required: false schema: type: string description: Comma-separated field machine names; prefix with `-` for descending, for example `-created`. entityType: name: entityType in: path required: true schema: type: string example: node description: An entity type machine name (for example `node`, `media`, `taxonomy_term`). page: name: page in: query required: false style: deepObject explode: true schema: type: object description: 'Pagination: `page[limit]` and `page[offset]`.' uuid: name: uuid in: path required: true schema: type: string format: uuid description: The entry's UUID, the `id` member of every response. filter: name: filter in: query required: false style: deepObject explode: true schema: type: object description: 'Match entries by field value. Short form `filter[field]=value` (equality) or canonical form with `[condition][path]`, `[condition][operator]`, `[condition][value]`. Operators: =, <>, >, >=, <, <=, STARTS_WITH, CONTAINS, ENDS_WITH, IN, NOT IN, BETWEEN, NOT BETWEEN, IS NULL, IS NOT NULL. Date fields compare as UNIX timestamps. Field paths use machine names. Every operator is shown with a worked example in the [query parameter reference](/source-cms/reference/query-parameters/#operators). ' include: name: include in: query required: false schema: type: string description: Comma-separated relationship paths to embed in `included`, for example `image,tags`. fields: name: fields in: query required: false style: deepObject explode: true schema: type: object description: 'Sparse fieldsets: `fields[node--article]=title,created` limits returned fields per type.' responses: Unauthorized: description: 'Missing, malformed, or expired token. Access tokens live 300 seconds. The diagnostic is in the `WWW-Authenticate` response header; the body may be HTML, not JSON. ' content: application/vnd.api+json: schema: $ref: '#/components/schemas/ErrorDocument' Forbidden: description: 'The token is valid but lacks the required scope (for example writing without `content:administer`). The JSON:API error `detail` names the missing permission. ' content: application/vnd.api+json: schema: $ref: '#/components/schemas/ErrorDocument' example: errors: - status: '403' detail: The 'administer nodes' permission is required. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: '`Authorization: Bearer ` with one space after Bearer. Tokens come from POST /oauth/token. Not required for published-content GETs when the site''s `Public access` (`API > JSON:API`) is Yes. ' oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://your-site.example.com/oauth/token scopes: content:administer: Create, update, and delete entries over JSON:API. authorizationCode: authorizationUrl: https://your-site.example.com/oauth/authorize tokenUrl: https://your-site.example.com/oauth/token scopes: content:administer: Create, update, and delete entries over JSON:API.