ContentZen Document API

Flexible API for managing, publishing, and querying your content. Integrate ContentZen with any frontend, mobile app, or service.

Getting Started

To use the ContentZen API, make HTTP requests to your project endpoint. All requests and responses use JSON. You can use fetch, axios, or any HTTP client.

GET https://api.contentzen.io/v1/posts

API Keys & Authentication

All API requests require authentication via an API key. You can generate and manage your API keys in the ContentZen dashboard under Settings → API Keys.

Include your API key in the Authorization header:

Authorization: Bearer <your-api-key>

Core Methods

getDocument

Returns a single document by its ID. Optionally filter by language, state, select fields, or expand relations.

getDocument({ id, lang?, state?, select?, expand? })

Param	Type	Required	Description
id	string	Yes	Document ID
lang	string	No	Language code (e.g., "en")
state	string	No	"draft" or "published"
select	array	No	Fields to return
expand	array/object	No	Relations/components to populate

Example Request:

GET /api/posts/xyz789?lang=en&state=published&select=title,content

Example Response:

{
  "id": "xyz789",
  "title": "Welcome to ContentZen!",
  "content": "...",
  "state": "published",
  "lang": "en",
  "createdAt": "2024-06-01T12:00:00Z"
}

getFirstDocument

Returns the first document matching the provided filters.

getFirstDocument({ lang?, state?, filter?, select?, expand? })

Param	Type	Required	Description
lang	string	No	Language code
state	string	No	"draft" or "published"
filter	object	No	Field filters
select	array	No	Fields to return
expand	array/object	No	Relations/components to populate

Example Request:

GET /api/posts/first?lang=fr&filter[author]=alex

Example Response:

{
  "id": "abc123",
  "title": "Bonjour!",
  "state": "draft"
}

getDocuments

Returns multiple documents with filters, sorting, and pagination.

getDocuments({ lang?, state?, filter?, select?, expand?, orderBy?, limit?, offset? })

Param	Type	Required	Description
lang	string	No	Language code
state	string	No	"draft" or "published"
filter	object	No	Field filters
select	array	No	Fields to return
expand	array/object	No	Relations/components to populate
orderBy	string/array	No	Sort order
limit	number	No	Max results
offset	number	No	Pagination offset

Example Request:

GET /api/posts?lang=fr&state=draft&filter[author]=alex&orderBy=createdAt:desc&limit=10&offset=0

Example Response:

{
  "data": [
    { "id": "abc123", "title": "Bonjour!", "state": "draft" }
  ],
  "meta": { "total": 1, "limit": 10, "offset": 0 }
}

createDocument

Creates a new document (optionally published) in a specific language.

createDocument({ lang?, payload, select?, state?, expand? })

Param	Type	Required	Description
lang	string	No	Language code
payload	object	Yes	Document data
select	array	No	Fields to return
state	string	No	"draft" or "published"
expand	array/object	No	Relations/components to populate

Example Request:

POST /api/posts
{
  "lang": "en",
  "payload": {
    "title": "New Post",
    "content": "..."
  }
}

Example Response:

{
  "id": "newid123",
  "title": "New Post",
  "state": "draft",
  "lang": "en"
}

updateDocument

Updates a document by ID. Can publish immediately.

updateDocument({ id, lang?, payload, select?, state?, expand? })

Param	Type	Required	Description
id	string	Yes	Document ID
lang	string	No	Language code
payload	object	Yes	Document data
select	array	No	Fields to return
state	string	No	"draft" or "published"
expand	array/object	No	Relations/components to populate

Example Request:

PUT /api/posts/xyz789
{
  "payload": {
    "title": "Updated Title"
  },
  "state": "published"
}

Example Response:

{
  "id": "xyz789",
  "title": "Updated Title",
  "state": "published"
}

removeDocument

Deletes a document or a specific language version.

removeDocument({ id, lang?, select?, expand? })

Param	Type	Required	Description
id	string	Yes	Document ID
lang	string	No	Language code
select	array	No	Fields to return
expand	array/object	No	Relations/components to populate

Example Request:

DELETE /api/posts/xyz789?lang=en

Example Response:

{ "success": true }

publishDocument

Publishes a document (all or specific locales).

publishDocument({ id, lang?, select?, expand? })

Param	Type	Required	Description
id	string	Yes	Document ID
lang	string	No	Language code ("*" for all)
select	array	No	Fields to return
expand	array/object	No	Relations/components to populate

Example Request:

POST /api/posts/xyz789/publish?lang=*

Example Response:

{ "id": "xyz789", "state": "published" }

unpublishDocument

Unpublishes a document (all or specific locales).

unpublishDocument({ id, lang?, select?, expand? })

Param	Type	Required	Description
id	string	Yes	Document ID
lang	string	No	Language code ("*" for all)
select	array	No	Fields to return
expand	array/object	No	Relations/components to populate

Example Request:

POST /api/posts/xyz789/unpublish?lang=*

Example Response:

{ "id": "xyz789", "state": "draft" }

discardDraft

Discards a draft and restores the last published version.

discardDraft({ id, lang?, select?, expand? })

Param	Type	Required	Description
id	string	Yes	Document ID
lang	string	No	Language code ("*" for all)
select	array	No	Fields to return
expand	array/object	No	Relations/components to populate

Example Request:

POST /api/posts/xyz789/discard-draft?lang=*

Example Response:

{ "id": "xyz789", "state": "published" }

countDocuments

Returns the number of documents by language and state.

countDocuments({ lang?, state?, filter? })

Param	Type	Required	Description
lang	string	No	Language code
state	string	No	"draft" or "published"
filter	object	No	Field filters

Example Request:

GET /api/posts/count?lang=en&state=published

Example Response:

{ "count": 42 }

Parameters

lang — Language code (e.g., "en", "fr"). Use "*" for all languages.
state — 'draft' or 'published'. Default: draft.
filter — Object with field filters (e.g., { title: 'Hello' }).
select — Array of fields to return (e.g., ["title", "createdAt"]).
expand — Relations/components to populate ("*" for all, or object for nested).
orderBy — Sort order (e.g., "createdAt:desc" or array).
limit, offset — Pagination for getDocuments.
payload — Data for create/update (object).

Examples

getDocument

GET /api/posts/xyz789?lang=en&state=published&select=title,content

{
  "id": "xyz789",
  "title": "Welcome to ContentZen!",
  "content": "...",
  "state": "published",
  "lang": "en",
  "createdAt": "2024-06-01T12:00:00Z"
}

getDocuments

GET /api/posts?lang=fr&state=draft&filter[author]=alex&orderBy=createdAt:desc&limit=10&offset=0

{
  "data": [
    { "id": "abc123", "title": "Bonjour!", "state": "draft" }
  ],
  "meta": { "total": 1, "limit": 10, "offset": 0 }
}

createDocument

POST /api/posts
{
  "lang": "en",
  "payload": {
    "title": "New Post",
    "content": "..."
  }
}

{
  "id": "newid123",
  "title": "New Post",
  "state": "draft",
  "lang": "en"
}

updateDocument

PUT /api/posts/xyz789
{
  "payload": {
    "title": "Updated Title"
  },
  "state": "published"
}

{
  "id": "xyz789",
  "title": "Updated Title",
  "state": "published"
}

removeDocument

DELETE /api/posts/xyz789?lang=en

{ "success": true }

publishDocument

POST /api/posts/xyz789/publish?lang=*

{ "id": "xyz789", "state": "published" }

countDocuments

GET /api/posts/count?lang=en&state=published

{ "count": 42 }