Content API

Version applicability

This page documents the Content API in kis.ai release 2.0.0. The service’s runtime HTTP paths carry no version segment, so a /1.1.7/ documentation URL does not imply a /v1/ segment on the API itself.

Before you call

Tenancy headers, bearer authentication, the error envelope and the health probes are the same across every kis.ai service. See API conventions. This page documents what is specific to this block.

Authentication and tenancy

Every route requires a bearer token:

Authorization: Bearer <token>

The four CEPT headers resolve the tenant, and every content type, store and asset is scoped to it.

X-Customer: acme
X-Product: site
X-Env: prod
X-Tenant: acme

A request that cannot resolve a tenant is refused rather than served against a default. The :contentstore and :contentapp path segments select within the tenant and are not a substitute for it.

The health and readiness probes are the only unauthenticated surface.

Route summary

Method	Path	Purpose
GET	/api/:plural	Strapi: a page of entries
GET	/api/:plural/:documentId	Strapi: one document
POST	/api/:plural	Strapi: create
PUT	/api/:plural/:documentId	Strapi: update
DELETE	/api/:plural/:documentId	Strapi: delete
GET	/spaces/:space/environments/:env/entries	Contentful: a page of entries
GET	/spaces/:space/environments/:env/entries/:id	Contentful: one entry
GET	/spaces/:space/environments/:env/content_types	Contentful: the type catalogue
GET	/spaces/:space/entries	Contentful, environment-scoped base URL
GET	/spaces/:space/entries/:id	as above
GET	/spaces/:space/content_types	as above
GET	/contentapp/list	Apps visible to the tenant
POST	/app/:contentapp/preview-token	Mint a preview grant
GET	/contentstore/list	Stores available to the tenant
POST	/store/:contentstore/asset	Upload
GET	/store/:contentstore/asset	Read by id or path
GET	/store/:contentstore/asset/id/:id	Read by id
GET	/store/:contentstore/asset/path/*path	Read by path
PUT	/store/:contentstore/asset	Replace the bytes, or add a version
PATCH	/store/:contentstore/asset	Rename or move
DELETE	/store/:contentstore/asset	Delete
POST	/store/:contentstore/folder	Create a folder
GET	/store/:contentstore/list	List a folder
PUT	/store/:contentstore/folder	Rename or move a folder
DELETE	/store/:contentstore/folder	Delete a folder

Strapi delivery

Full dialect reference: Strapi delivery.

GET /api/:plural

Parameter	Default	Notes
locale	every locale
status	published	draft requires entitlement or a preview token
filters[field][$op]		See the operator table
sort	(documentId, locale)	field:asc, field:desc
fields	every field	Comma-separated
populate	none	Relation names or dotted paths, to depth 10
pagination[page]	1
pagination[pageSize]	25	Clamped to 100
pagination[start] / pagination[limit]		The offset form
pagination[withCount]	true
preview		A preview token

200 with { "data": [...], "meta": { "pagination": {...} } }.

GET /api/:plural/:documentId

Takes locale, status, fields, populate and preview.

200 with { "data": {...}, "meta": {} }. 404 when the document has no row in the requested locale.

POST /api/:plural

Body {"data": {...}, "publish": false}, up to 8 MiB. Takes locale.

201 with the row that landed. A new entry is a draft unless publish is true.

PUT /api/:plural/:documentId

Body {"data": {...}, "publish": true}. Takes locale.

200 with the row that landed. Omitting publish leaves the publish state alone.

DELETE /api/:plural/:documentId

Takes locale. 204 No Content.

Statuses

Status	error.name	When
400	ValidationError	Malformed query or body, unknown field, unsupported operator
403	ForbiddenError	The entity’s rules refused this caller
404	NotFoundError	No such type, ambiguous plural, or no such document in that locale
400	ApplicationError	The request could not be served

Contentful delivery

Full dialect reference: Contentful delivery.

GET /spaces/:space/environments/:env/entries

Parameter	Default	Notes
content_type	required	Type name or plural
locale	the row’s own	* pivots every locale into one entry
fields.x, fields.x[op], sys.id		ne, in, nin, lt, lte, gt, gte, exists, match
order	(documentId, locale)	- prefixes a descending term
select	every field	Comma-separated
limit	100	Clamped to 1000
skip	0
include	1	Link depth, up to 10
preview		A preview token

X-Contentful-Preview: true selects the draft view for a caller entitled to it.

200 with { "sys": {"type":"Array"}, "total", "skip", "limit", "items", "includes" }.

GET /spaces/:space/environments/:env/entries/:id

No content_type needed: the id is a document identity, so the type is found across the space. Takes locale and preview.

200 with one { "sys": {...}, "fields": {...} } entry.

GET /spaces/:space/environments/:env/content_types

200 with the space’s content types, their fields, each field’s CDA type, and whether it is required and localized.

Statuses

Status	sys.id	When
400	BadRequest	Missing content_type, or a malformed query string
400	InvalidQuery	Unknown field, or include above the ceiling
403	AccessDenied	The entity’s rules refused this caller
404	NotFound	Unknown space, unknown type, or no such entry

Content apps

GET /contentapp/list

200 with the content apps configured for this tenant.

Preview tokens

POST /app/:contentapp/preview-token

{ "type": "posts", "space": "blog", "documentId": "01J9Y…", "locale": "en", "ttlSeconds": 900 }

Only type is required. ttlSeconds defaults to 1800 and is clamped to 86400.

{ "token": "kp1.…", "expiresAt": "…", "type": "blog.post", "space": "blog",
  "documentId": "01J9Y…", "locale": "en" }

Status	When
200	Minted
400	No type, or the body is not valid JSON
403	The caller may not preview this type
404	No such type, or an ambiguous plural
501	The app has no preview signing secret configured

Present the token as ?preview=<token> or X-Preview-Token. See Preview.

Assets

Full guide: Assets.

GET /contentstore/list

200 with the content stores available to this tenant.

POST /store/:contentstore/asset

multipart/form-data, with the file in the file part.

Parameter	Notes
path	Folder path to file the asset under
parentfolderid	Folder by id, instead of path
createfolders	Create missing folders along path
filename	Override the uploaded name
overwrite	Replace, or add a version when versioning is on
locale	Required when the store has locales enabled
description	Stored on the sidecar
cacheexpiry	Per-asset cache policy
transform	Apply a transform on the way in

200 with the asset record.

GET /store/:contentstore/asset, /asset/id/:id, /asset/path/*path

Parameter	Notes
id / path	Addressing, when not in the path
version	Pin a version
locale	Required when the store has locales enabled
transform	A native transform expression
w, h, fit, fm, f, format	Image parameters
metadata=true	Return the metadata as JSON instead of the bytes
download	Ask for a download disposition

Responds 200 or 206, 304 on a matching validator, 416 for an unsatisfiable byte range, or 302 to a presigned URL for an object store.

PUT /store/:contentstore/asset

multipart/form-data. Takes id or path, plus locale, version and transform.

PATCH /store/:contentstore/asset

Takes path, newpath and locale. Renames or moves an asset.

DELETE /store/:contentstore/asset

Takes id or path, plus locale.

Folders

POST /store/:contentstore/folder

Takes name, path, parentid and createfolders.

GET /store/:contentstore/list

Takes folderid or path, plus type, depth and meta.

Unpaginated

A listing returns the folder’s whole contents. Keep folders to a size you would be willing to return in one response.

PUT /store/:contentstore/folder

Takes parentfolderid, currentname, newname, currentpath, newpath and createfolders.

DELETE /store/:contentstore/folder

Takes id or path, plus forcedelete.

See also

• Quickstart: these routes in order, end to end
• Operations: configuring stores, apps and webhooks