The Drupal JSON:API module is a core component that exposes all Drupal entity types and bundles as a standards-compliant JSON:API interface, requiring no configuration to enable. Each entity bundle receives a unique URL path following the pattern /jsonapi/{entity_type}/{bundle}, and the module supports GET, POST, PATCH, and DELETE operations for full CRUD access.
openapi: 3.1.0
info:
title: Drupal JSON:API
description: >-
The Drupal JSON:API module is a core component that exposes all Drupal entity
types and bundles as a standards-compliant JSON:API interface, requiring no
configuration to enable. Each entity bundle receives a unique URL path following
the pattern /jsonapi/{entity_type}/{bundle}, and the module supports GET, POST,
PATCH, and DELETE operations for full CRUD access. It supports filtering, sorting,
pagination, sparse fieldsets, includes for relationship resolution, translations,
revisions, and file uploads out of the box. All resource identifiers use entity
UUIDs rather than numeric IDs. The JSON:API module is the recommended approach
for most decoupled and headless Drupal applications due to its adherence to the
open JSON:API specification (jsonapi.org) and its compatibility with the broader
JSON:API client ecosystem.
version: '1.1'
contact:
name: Drupal Community
url: https://www.drupal.org/community
termsOfService: https://www.drupal.org/about/legal
externalDocs:
description: Drupal JSON:API Module Documentation
url: https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module/api-overview
servers:
- url: https://example.com/jsonapi
description: Drupal JSON:API Base (replace with your Drupal installation base URL)
tags:
- name: Files
description: >-
JSON:API endpoints for file entities and file upload operations.
- name: Node Articles
description: >-
JSON:API endpoints for article content nodes. The bundle slug varies by
Drupal installation; article is shown as an example bundle name.
- name: Node Pages
description: >-
JSON:API endpoints for basic page content nodes. The bundle slug varies
by Drupal installation.
- name: Taxonomy Terms
description: >-
JSON:API endpoints for taxonomy term entities across all configured
vocabularies.
- name: Users
description: >-
JSON:API endpoints for Drupal user entities. Config entities are read-only
via JSON:API and require authentication.
security:
- basicAuth: []
- oAuth2:
- content
paths:
/node/article:
get:
operationId: listNodeArticles
summary: List article nodes
description: >-
Retrieves a collection of article content nodes. Supports filtering by
any field using the filter query parameter, ascending and descending
sorting via sort, cursor-based pagination via page[limit] and page[offset],
sparse fieldsets via fields[node--article], and relationship resolution
via include. Published nodes are accessible to anonymous users; unpublished
nodes require authentication and appropriate permissions.
tags:
- Node Articles
parameters:
- $ref: '#/components/parameters/JsonApiAccept'
- $ref: '#/components/parameters/FilterPath'
- $ref: '#/components/parameters/FilterValue'
- $ref: '#/components/parameters/FilterOperator'
- $ref: '#/components/parameters/SortParam'
- $ref: '#/components/parameters/PageLimit'
- $ref: '#/components/parameters/PageOffset'
- $ref: '#/components/parameters/IncludeParam'
- $ref: '#/components/parameters/FieldsParam'
responses:
'200':
description: Collection of article nodes returned successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/NodeArticleCollection'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
post:
operationId: createNodeArticle
summary: Create an article node
description: >-
Creates a new article content node. The request body must be a JSON:API
resource object with type set to node--article and the desired attributes
and relationships. Entity reference fields must be expressed as relationship
objects, not plain attributes. Requires authentication and create article
content permission.
tags:
- Node Articles
parameters:
- $ref: '#/components/parameters/JsonApiContentType'
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/NodeArticleCreateRequest'
responses:
'201':
description: Article node created successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/NodeArticleResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/node/article/{uuid}:
get:
operationId: getNodeArticle
summary: Get an article node
description: >-
Retrieves a single article content node by its UUID. Supports sparse
fieldsets via fields[node--article] and relationship resolution via
include. Note that JSON:API always uses UUID as the identifier, not the
numeric node ID.
tags:
- Node Articles
parameters:
- $ref: '#/components/parameters/EntityUuid'
- $ref: '#/components/parameters/JsonApiAccept'
- $ref: '#/components/parameters/IncludeParam'
- $ref: '#/components/parameters/FieldsParam'
responses:
'200':
description: Article node returned successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/NodeArticleResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateNodeArticle
summary: Update an article node
description: >-
Updates an existing article content node by its UUID. Only the attributes
and relationships included in the request body are modified; omitted fields
retain their current values. Requires authentication and edit permissions
for the article content type.
tags:
- Node Articles
parameters:
- $ref: '#/components/parameters/EntityUuid'
- $ref: '#/components/parameters/JsonApiContentType'
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/NodeArticleUpdateRequest'
responses:
'200':
description: Article node updated successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/NodeArticleResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteNodeArticle
summary: Delete an article node
description: >-
Permanently deletes an article content node by its UUID. Requires
authentication and delete permissions for the article content type.
This operation cannot be undone.
tags:
- Node Articles
parameters:
- $ref: '#/components/parameters/EntityUuid'
responses:
'204':
description: Article node deleted successfully. No content returned.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/node/page:
get:
operationId: listNodePages
summary: List basic page nodes
description: >-
Retrieves a collection of basic page content nodes. Supports the same
query parameters as other JSON:API collection endpoints including filter,
sort, page, include, and fields.
tags:
- Node Pages
parameters:
- $ref: '#/components/parameters/JsonApiAccept'
- $ref: '#/components/parameters/FilterPath'
- $ref: '#/components/parameters/FilterValue'
- $ref: '#/components/parameters/SortParam'
- $ref: '#/components/parameters/PageLimit'
- $ref: '#/components/parameters/PageOffset'
- $ref: '#/components/parameters/IncludeParam'
- $ref: '#/components/parameters/FieldsParam'
responses:
'200':
description: Collection of basic page nodes returned successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiCollection'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
/node/page/{uuid}:
get:
operationId: getNodePage
summary: Get a basic page node
description: >-
Retrieves a single basic page content node by its UUID. Supports sparse
fieldsets and relationship includes.
tags:
- Node Pages
parameters:
- $ref: '#/components/parameters/EntityUuid'
- $ref: '#/components/parameters/JsonApiAccept'
- $ref: '#/components/parameters/IncludeParam'
- $ref: '#/components/parameters/FieldsParam'
responses:
'200':
description: Basic page node returned successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiSingleResponse'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/user/user:
get:
operationId: listUsers
summary: List users
description: >-
Retrieves a collection of user entities. Requires authentication and
administer users permission to access. Supports filtering, sorting,
pagination, sparse fieldsets, and includes.
tags:
- Users
parameters:
- $ref: '#/components/parameters/JsonApiAccept'
- $ref: '#/components/parameters/FilterPath'
- $ref: '#/components/parameters/FilterValue'
- $ref: '#/components/parameters/SortParam'
- $ref: '#/components/parameters/PageLimit'
- $ref: '#/components/parameters/PageOffset'
- $ref: '#/components/parameters/IncludeParam'
- $ref: '#/components/parameters/FieldsParam'
responses:
'200':
description: Collection of user entities returned successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiCollection'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/user/user/{uuid}:
get:
operationId: getUser
summary: Get a user
description: >-
Retrieves a single user entity by UUID. Users can read their own profile;
administrators can read any user. Sensitive fields like email may be
restricted to authenticated users with appropriate permissions.
tags:
- Users
parameters:
- $ref: '#/components/parameters/EntityUuid'
- $ref: '#/components/parameters/JsonApiAccept'
- $ref: '#/components/parameters/IncludeParam'
- $ref: '#/components/parameters/FieldsParam'
responses:
'200':
description: User entity returned successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiSingleResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateUser
summary: Update a user
description: >-
Updates an existing user entity by UUID. Users can update their own
profiles; administrators can update any user account. Requires
authentication.
tags:
- Users
parameters:
- $ref: '#/components/parameters/EntityUuid'
- $ref: '#/components/parameters/JsonApiContentType'
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiUpdateRequest'
responses:
'200':
description: User updated successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiSingleResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/taxonomy_term/{vocabulary}:
get:
operationId: listTaxonomyTerms
summary: List taxonomy terms by vocabulary
description: >-
Retrieves a collection of taxonomy terms for a specific vocabulary bundle.
Replace {vocabulary} with the machine name of the vocabulary (e.g., tags,
categories). Supports filtering, sorting, pagination, and includes.
tags:
- Taxonomy Terms
parameters:
- $ref: '#/components/parameters/VocabularyBundle'
- $ref: '#/components/parameters/JsonApiAccept'
- $ref: '#/components/parameters/FilterPath'
- $ref: '#/components/parameters/FilterValue'
- $ref: '#/components/parameters/SortParam'
- $ref: '#/components/parameters/PageLimit'
- $ref: '#/components/parameters/PageOffset'
- $ref: '#/components/parameters/IncludeParam'
- $ref: '#/components/parameters/FieldsParam'
responses:
'200':
description: Collection of taxonomy terms returned successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiCollection'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/taxonomy_term/{vocabulary}/{uuid}:
get:
operationId: getTaxonomyTerm
summary: Get a taxonomy term
description: >-
Retrieves a single taxonomy term by vocabulary bundle and UUID. Returns
the term's name, description, weight, and any configured relationships
such as parent terms.
tags:
- Taxonomy Terms
parameters:
- $ref: '#/components/parameters/VocabularyBundle'
- $ref: '#/components/parameters/EntityUuid'
- $ref: '#/components/parameters/JsonApiAccept'
- $ref: '#/components/parameters/IncludeParam'
- $ref: '#/components/parameters/FieldsParam'
responses:
'200':
description: Taxonomy term returned successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiSingleResponse'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/file/file:
get:
operationId: listFiles
summary: List file entities
description: >-
Retrieves a collection of file entities. Returns file metadata including
filename, MIME type, size, and URI. Requires authentication with
appropriate file access permissions.
tags:
- Files
parameters:
- $ref: '#/components/parameters/JsonApiAccept'
- $ref: '#/components/parameters/FilterPath'
- $ref: '#/components/parameters/FilterValue'
- $ref: '#/components/parameters/SortParam'
- $ref: '#/components/parameters/PageLimit'
- $ref: '#/components/parameters/PageOffset'
- $ref: '#/components/parameters/FieldsParam'
responses:
'200':
description: Collection of file entities returned successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiCollection'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/file/file/{uuid}:
get:
operationId: getFile
summary: Get a file entity
description: >-
Retrieves a single file entity by UUID. Returns file metadata. The file
binary is accessible via the URI field returned in the response.
tags:
- Files
parameters:
- $ref: '#/components/parameters/EntityUuid'
- $ref: '#/components/parameters/JsonApiAccept'
- $ref: '#/components/parameters/FieldsParam'
responses:
'200':
description: File entity returned successfully.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiSingleResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteFile
summary: Delete a file entity
description: >-
Permanently deletes a file entity and its associated file from storage
by UUID. Requires file management permissions and authentication.
tags:
- Files
parameters:
- $ref: '#/components/parameters/EntityUuid'
responses:
'204':
description: File entity deleted successfully. No content returned.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic Authentication using Drupal username and password.
cookieAuth:
type: apiKey
in: cookie
name: SESS
description: >-
Cookie-based session authentication obtained via Drupal login.
oAuth2:
type: oauth2
description: OAuth 2.0 via the Simple OAuth module.
flows:
authorizationCode:
authorizationUrl: https://example.com/oauth/authorize
tokenUrl: https://example.com/oauth/token
scopes:
content: Access and manage content entities
user: Access and manage user entities
parameters:
EntityUuid:
name: uuid
in: path
required: true
description: >-
The UUID of the entity. JSON:API always uses UUID as the identifier,
not the numeric entity ID.
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
VocabularyBundle:
name: vocabulary
in: path
required: true
description: >-
The machine name of the taxonomy vocabulary bundle (e.g., tags,
categories, topics).
schema:
type: string
example: tags
JsonApiAccept:
name: Accept
in: header
required: false
description: >-
The JSON:API media type. Include this header to receive a properly
formatted JSON:API response.
schema:
type: string
default: application/vnd.api+json
JsonApiContentType:
name: Content-Type
in: header
required: true
description: Must be application/vnd.api+json for all JSON:API write requests.
schema:
type: string
default: application/vnd.api+json
FilterPath:
name: filter[name][path]
in: query
required: false
description: >-
The dotted field path to filter on, e.g. title, status, uid.name, or
field_tags.name for nested relationship fields.
schema:
type: string
example: status
FilterValue:
name: filter[name][value]
in: query
required: false
description: The value to filter against.
schema:
type: string
example: '1'
FilterOperator:
name: filter[name][operator]
in: query
required: false
description: >-
The comparison operator for the filter condition. Supported operators:
=, <>, >, >=, <, <=, STARTS_WITH, CONTAINS, ENDS_WITH, IN, NOT IN,
BETWEEN, NOT BETWEEN, IS NULL, IS NOT NULL.
schema:
type: string
enum:
- '='
- '<>'
- '>'
- '>='
- '<'
- '<='
- STARTS_WITH
- CONTAINS
- ENDS_WITH
- IN
- NOT IN
- BETWEEN
- NOT BETWEEN
- IS NULL
- IS NOT NULL
default: '='
SortParam:
name: sort
in: query
required: false
description: >-
Sort the results by the given field. Prefix with - for descending order.
For example, sort=title for ascending by title or sort=-created for
descending by creation date.
schema:
type: string
example: '-created'
PageLimit:
name: page[limit]
in: query
required: false
description: >-
The maximum number of resources to return in a single page. Used for
cursor-based pagination.
schema:
type: integer
minimum: 1
maximum: 50
default: 50
PageOffset:
name: page[offset]
in: query
required: false
description: >-
The number of resources to skip before beginning to return results.
Used in combination with page[limit] for pagination.
schema:
type: integer
minimum: 0
default: 0
IncludeParam:
name: include
in: query
required: false
description: >-
A comma-separated list of relationship paths to include in the response.
For example, include=uid resolves the author relationship, and
include=field_tags includes related taxonomy terms inline.
schema:
type: string
example: uid,field_tags
FieldsParam:
name: fields[node--article]
in: query
required: false
description: >-
Sparse fieldset parameter to limit which attributes are returned, reducing
response payload size. Replace node--article with the relevant resource
type. Value is a comma-separated list of field names.
schema:
type: string
example: title,body,created
responses:
BadRequest:
description: The request body or query parameters are invalid.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiErrorResponse'
Unauthorized:
description: Authentication is required to access this resource.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiErrorResponse'
Forbidden:
description: The authenticated user lacks permission to perform this operation.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiErrorResponse'
NotFound:
description: The requested resource does not exist or is inaccessible.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiErrorResponse'
UnprocessableEntity:
description: >-
The request body is syntactically valid but semantically unprocessable,
such as failing field validation.
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/JsonApiErrorResponse'
schemas:
JsonApiResourceObject:
type: object
description: A JSON:API resource object representing a single Drupal entity.
required:
- type
- id
properties:
type:
type: string
description: >-
The JSON:API resource type in the format {entity_type}--{bundle},
e.g. node--article, taxonomy_term--tags.
example: node--article
id:
type: string
format: uuid
description: The UUID of the resource.
attributes:
type: object
description: >-
The resource's field values excluding entity references. Keys are
field machine names.
relationships:
type: object
description: >-
The resource's entity reference fields expressed as relationship
objects with data containing type and id.
links:
$ref: '#/components/schemas/JsonApiLinks'
JsonApiLinks:
type: object
description: Navigation links included in JSON:API responses.
properties:
self:
type: object
description: Link to the current resource or collection.
properties:
href:
type: string
format: uri
description: The URL of the current resource.
related:
type: object
description: Link to a related resource.
properties:
href:
type: string
format: uri
description: The URL of the related resource.
JsonApiCollectionLinks:
type: object
description: Pagination links for collection responses.
properties:
self:
type: object
properties:
href:
type: string
format: uri
description: Link to the current page.
first:
type: object
properties:
href:
type: string
format: uri
description: Link to the first page of results.
prev:
type: object
properties:
href:
type: string
format: uri
description: Link to the previous page of results.
next:
type: object
properties:
href:
type: string
format: uri
description: Link to the next page of results.
last:
type: object
properties:
href:
type: string
format: uri
description: Link to the last page of results.
JsonApiCollection:
type: object
description: A JSON:API collection response containing multiple resource objects.
properties:
jsonapi:
type: object
description: JSON:API version metadata.
properties:
version:
type: string
description: The JSON:API specification version.
example: '1.0'
data:
type: array
description: Array of resource objects.
items:
$ref: '#/components/schemas/JsonApiResourceObject'
included:
type: array
description: Array of included related resources when using the include parameter.
items:
$ref: '#/components/schemas/JsonApiResourceObject'
links:
$ref: '#/components/schemas/JsonApiCollectionLinks'
meta:
type: object
description: >-
Non-standard meta-information about the response, such as total
result count.
properties:
count:
type: integer
description: Total number of matching resources across all pages.
JsonApiSingleResponse:
type: object
description: A JSON:API response containing a single resource object.
properties:
jsonapi:
type: object
description: JSON:API version metadata.
properties:
version:
type: string
description: The JSON:API specification version.
example: '1.0'
data:
$ref: '#/components/schemas/JsonApiResourceObject'
included:
type: array
description: Array of included related resources when using the include parameter.
items:
$ref: '#/components/schemas/JsonApiResourceObject'
links:
$ref: '#/components/schemas/JsonApiLinks'
NodeArticleAttributes:
type: object
description: Attributes for a Drupal article node resource object.
properties:
drupal_internal__nid:
type: integer
description: The internal numeric node ID (not used as the primary identifier).
drupal_internal__vid:
type: integer
description: The internal numeric revision ID.
langcode:
type: string
description: The language code for this node (e.g., en).
status:
type: boolean
description: Whether the node is published (true) or unpublished (false).
title:
type: string
description: The title of the article node.
created:
type: string
format: date-time
description: ISO 8601 timestamp of when the node was created.
changed:
type: string
format: date-time
description: ISO 8601 timestamp of when the node was last modified.
promote:
type: boolean
description: Whether the node is promoted to the front page.
sticky:
type: boolean
description: Whether the node is sticky at the top of lists.
body:
type: object
description: The main body field of the article.
properties:
value:
type: string
description: The full body text, may contain HTML markup.
summary:
type: string
description: Optional trimmed summary of the body text.
format:
type: string
description: The text format machine name applied to the body.
processed:
type: string
description: The body text after applying the text format processing.
path:
type: object
description: The URL alias configuration for this node.
properties:
alias:
type: string
description: The URL alias path, e.g. /my-article-title.
pid:
type: integer
description: The path ID.
langcode:
type: string
description: The language code for this path alias.
NodeArticleResponse:
type: object
description: A JSON:API response for a single article node.
properties:
jsonapi:
type: object
properties:
version:
type: string
example: '1.0'
data:
type: object
description: The article node resource object.
properties:
type:
type: string
example: node--article
id:
type: string
format: uuid
attributes:
$ref: '#/components/schemas/NodeArticleAttributes'
relationships:
type: object
description: Entity reference relationships for the article node.
properties:
node_type:
type: object
description: Reference to the node type configuration entity.
properties:
data:
$ref: '#/components/schemas/JsonApiRelationshipData'
uid:
type: object
description: Reference to the authoring user entity.
properties:
data:
$ref: '#/components/schemas/JsonApiRelationshipData'
field_tags:
type: object
description: References to taxonomy term entities for tagging.
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/drupal/refs/heads/main/openapi/drupal-jsonapi-openapi.yml