The content API reference

The guide is The content API, Contentful's. This page says exactly what is there.

A subscription carries a source: one somebody made through this API is hand and is theirs, and one a deployment ships declared in platformkit.config.js is file and is the projection's to replace — see Declarations and state.

Base, keys, headers

Routes

A collection is { sys: { type: 'Array' }, total, skip, limit, items, includes?, errors? }. Another space id or environment answers NotFound with details: { type: 'Space' | 'Environment', id }.

The Management API (cloud mode)

The same routes under a management key, Content-Type: application/vnd.contentful.management.v1+json. A read answers the Management shape: fields by locale ({ "en-US": … }), sys.version (the row's revision × 2, + 1 while a draft is pending), sys.publishedVersion, publishedAt, firstPublishedAt, publishedCounter, createdBy and updatedBy (User links: the key's maker, or the person in the admin). In git mode every writing method answers BadRequest (405) with the reason. On save, the content pipe omits empty arrays from the file, so those fields are absent from the returned draft and subsequent reads.

A write's fields: a plain field its value; a RichText field as a document (richtext-to-markdown.js turns it back) or as its <field>Markdown twin, the twin winning; an Asset link { sys: { type: 'Link', linkType: 'Asset', id } } a library file (422 notResolvable when there is none); an Entry link { … linkType: 'Entry', id } another entry's id. ValidationFailed (422) carries details.errors[] with name (unknown, notResolvable, invalid), path (['fields', <field>]) and details.

Webhook deliveries: POST <url> with X-Contentful-Topic: ContentManagement.<Entry|Asset>.<create|save|publish|unpublish|delete>, X-Contentful-Webhook-Name, the definition's headers, and the entry or asset in the Management shape (a DeletedEntry / DeletedAsset for a delete); topics match by <Type>.<event>, <Type>.* and *.*. From the row store's own events, so the admin's publish delivers too. content_webhooks holds last_at and last_error; Settings → API lists it. Uploads never processed, and assets made but never processed, go with the daily sweep (sweep_uploads, 50 4 * * *).

An entry

Field values by type: Symbol / Text a string; Integer / Number a number; Boolean; Date an ISO 8601 string; Object the frontmatter's value as it is; Array of Symbol a list; Link { sys: { type: 'Link', linkType: 'Entry' | 'Asset', id } }; Array of Links a list of them; RichText Contentful's document (document → heading-1…6, paragraph, unordered-list, ordered-list, list-item, blockquote, hr, table, table-row, table-header-cell, table-cell, hyperlink, embedded-asset-block, text with the marks bold, italic, code); a markdown field's <field>Markdown twin the markdown itself; a body body and bodyMarkdown. A gated entry (canAccess beyond guest) omits its body fields unless the key is allowed gated content.

A content type

{ sys: { id, type: 'ContentType', space, environment, createdAt, updatedAt, revision }, name, description, displayField, fields: [{ id, name, type, localized, required, disabled, omitted, validations, linkType?, items? }] }. Types: Symbol, Text, RichText, Integer, Number, Date, Boolean, Object, Link (linkType Entry with validations: [{ linkContentType: [<type id>] }], or Asset), Array (items a Symbol with an in validation of fixed choices, an Object, or a Link). A select's choices are validations: [{ in: [...] }]. Ids are the model's singular in camelCase: the kit's article, book, wiki, doc, page, companion, product, collection, ad, experiment, session, site, storefront; a model of the site's own by its singular under a model namespace (models/events → modelEvent), so it can never land on a stock collection's id.

An asset

{ sys: { id (a hash of the address), type: 'Asset', space, environment, createdAt, updatedAt, revision, locale }, fields: { title (the file name without its extension), description (''), file: { url, details: { size, image?: { width, height } }, fileName, contentType } } }. url is protocol-relative on the site's images door — //<domain>/api/media/<space>/<id>/<hash>/<file> — or, for a picture a record names elsewhere, that address itself.

Collection arguments

Assets take select, order (sys.createdAt, fields.title), limit, skip, query, sys.id[in], fields.title, fields.file.fileName, fields.file.contentType, mimetype_group.

Sync

?initial=true — every published entry and asset in pages of 100 (nextPageUrl), then nextSyncUrl; type (all, Entry, Asset, Deletion, DeletedEntry, DeletedAsset) and content_type narrow it. ?sync_token=<token> — the entries and assets changed since, and DeletedEntry / DeletedAsset rows (sys.deletedAt) for what is gone; a fresh nextSyncUrl. Items carry every locale. A token that is not one of ours is BadQuery.

GraphQL

Generated from the content types. Query fields: <type>(id!, preview, locale), <type>Collection(skip, limit, preview, locale, where: <Type>Filter, order: [<Type>Order]), asset(id!), assetCollection(where: AssetFilter, order: [AssetOrder]), entryCollection(where: EntryFilter). A type has sys { id spaceId environmentId publishedAt firstPublishedAt publishedVersion locale }, contentfulMetadata { tags concepts }, linkedFrom { entryCollection <type>Collection… }, and its fields — String, Int, Float, Boolean, DateTime, JSON, a linked type, Asset, <Type><Field>Collection for a list of links, <Type><Field> { json links { entries { block inline hyperlink } assets { block hyperlink } } } for Rich Text. Filters: <f>, <f>_not, <f>_in, <f>_not_in, <f>_exists, <f>_contains, <f>_not_contains, <f>_gt/_gte/_lt/_lte, <list>_contains_all/_some/_none, <link>: { … } (a nested filter), sys: SysFilter, AND, OR. Orders: <f>_ASC/_DESC for every sortable field, sys_id_*, sys_publishedAt_*, sys_firstPublishedAt_*, sys_publishedVersion_*. Asset.url(transform: { width, height, quality, cornerRadius, resizeStrategy, resizeFocus, backgroundColor, format }) writes the Images API's parameters. preview: true needs a preview key (ACCESS_DENIED, 403); a query over 11 000 in Contentful's complexity is TOO_COMPLEX_QUERY; a malformed one INVALID_QUERY — each under errors[].extensions.contentful.code.

Images

w, h (1–4000), fit (pad, fill, scale, crop, thumb; none: fit within), f (center, top, right, left, bottom, top_right, top_left, bottom_right, bottom_left; face, faces → center), fm (jpg, png, webp, gif; avif → webp), q (1–100), r (a radius, or max), bg (rgb:rrggbb). Cache-Control: public, max-age=31536000, immutable, ETag; out of range BadQuery (400); an unknown asset NotFound.

Errors

{ sys: { type: 'Error', id }, message, details?, requestId }: NotFound (404: a space, environment, entry, asset, content type or route), BadQuery (400: an argument out of range, a field filter with no content_type, an unknown locale, a bad sync token), InvalidQuery (400: an unknown content type, details.errors[0].name = unknownContentType; an unsupported operator), AccessTokenInvalid (401: no key where Delivery is private, a revoked key), AccessDenied (403: a write, or a Management read, under a key that is not a management key), VersionMismatch (409: a stale X-Contentful-Version, an entry already at an id, an asset in use), ValidationFailed (422: a field, a link or a value refused, details.errors naming each), RateLimitExceeded (429: X-Contentful-RateLimit-Reset says when), BadRequest (405: a write).

The OpenAPI document

openapi: 3.1.0; info.title <site name> API, version 1; servers the site's public address first (the host rewrites /spaces, /content/v1, /images and /v1 to the functions), then the content function's own; tags Content Delivery, Content Management, Content Sync, Content GraphQL, Content Images, Analytics Events, Analytics Capture, and, with the forms module on, Forms, Responses, Webhooks, Insights, with the sessions module on Event Types, Slots, Bookings, Schedules, Scheduling Webhooks, with the store module on Storefront, with the support module on Client, Conversations, Contacts, Support Webhooks, gathered by x-tagGroups into Content API, Forms API, Scheduling API, Store API, Support API and Analytics API (each tag's description says what it is a drop-in for — the sidebar carries names only); paths every route above under its tag — the space, entries and one entry, assets and one asset, content types and one, locales, sync; GraphQL POST and GET; the image route; /api/events (the site's own batch), /api/events/e/, /api/events/batch/, /api/events/flags/, /api/events/array/{token}/config.js — each with its parameters (content_type an enum of the type ids), its responses and Contentful's errors; components.securitySchemes.key the bearer key; components.schemas Link, Sys, RichTextDocument, Asset, ContentType, ContentTypeField, Locale, Error, Entry (one of every type), EntryCollection, AssetCollection, SyncCollection, AnalyticsEvent, AnalyticsBatch, PostHogEvent, PostHogBatch, FlagsResponse, and one schema per content type under its id in PascalCase (Article, Book, a site model's namespaced singular such as ModelEvent) with fields typed from the content type. _shared/api/openapi.js is the generator; the page is ApiReferencePage.vue at /api (ROUTES.api, behind the api module).

Keys

api_keys in the database: name, kind (delivery | preview | management | forms | scheduling | storefront | support), gated, prefix, hash (sha256 of the key; the key itself is never stored), created_by, created_at, last_used_at, revoked_at — administrators read and write under RLS; the functions look a key up by its hash with the service role. A key is pk_<kind>_<32 base62 characters>. api.public (default true) and api.space (default the site's slug) in platformkit.config.js; the module switch is api.