Kontent.ai API reference

New to Corsair? See API access, authentication, and error handling.

Items

get

items.get One content item by codename, with its elements and, on request, its linked items Risk: read

await corsair.kontentai.api.items.get({ codename: 'about_us', depth: 2 });

Input

Name	Type	Required	Description
`codename`	`string`	Yes	The item, type or taxonomy codename, such as `about_us`.
`depth`	`number`	No	How deep to resolve linked items: `0` returns no `modular_content`, `1` and `2` go deeper. Kontent clamps anything outside 0 to 2 without saying so.
`language`	`string`	No	Read the item in this language codename. An untranslated item falls back to another language; check `system.language` on the answer.
`elements`	`string[]`	No	Return only these element codenames. Sent as one comma-separated `elements` value.
`preview`	`boolean`	No	Read the latest version, including unpublished content, from the Preview API. Needs a Delivery API key with preview access stored on the account.

preview: true reads the latest version, unpublished included, from the Preview API; it needs a stored delivery_api_key with preview access. Output

Name	Type	Required	Description
`item`	`object`	Yes	—
`modular_content`	`Record<string, any> \| null`	No	—

item full type

{
  system: {
    id: string,
    name?: string | null,
    codename?: string | null,
    language?: string | null,
    type?: string | null,
    collection?: string | null,
    sitemap_locations?: string[] | null,
    last_modified?: string | null,
    workflow?: string | null,
    workflow_step?: string | null
  },
  elements?: Record<string, {
    type: string,
    name?: string | null,
    value?: any
  }> | null
}

list

items.list Published content items by type, language, collection or filter, with depth deciding how far linked items resolve; next_skip gives the next page Risk: read

await corsair.kontentai.api.items.list({ limit: 10, depth: 1, type: 'article', language: 'en-US', order: 'elements.post_date[desc]', in_filter: 'elements.title[nempty]' });

Input

Name	Type	Required	Description
`skip`	`number`	No	Items to skip. Defaults to 0.
`limit`	`number`	No	Items per page, at most 2000. Without it Kontent returns everything from `skip` on in one answer.
`order`	`string`	No	A sort, such as `system.last_modified` or `elements.price[asc]`. Suffix the field with `[desc]` to reverse it; a `-` prefix is refused with a 400.
`preview`	`boolean`	No	Read the latest version, including unpublished content, from the Preview API. Needs a Delivery API key with preview access stored on the account.
`depth`	`number`	No	How deep to resolve linked items: `0` returns no `modular_content`, `1` and `2` go deeper. Kontent clamps anything outside 0 to 2 without saying so.
`type`	`string`	No	Only items of this content type codename, sent as `system.type`.
`language`	`string`	No	Read content in this language codename, such as `es-ES`. Items not translated into it fall back to another language; add `system.language=es-ES` to `in_filter` to drop them.
`collection`	`string`	No	Only this collection codename, sent as `system.collection`.
`in_filter`	`string`	No	Kontent filters, such as `elements.price[gt]=10` or `system.type[in]=article,coffee&elements.title[nempty]`. Each `&`-separated filter is sent as its own query parameter, and an item must match all of them.
`elements`	`string[]`	No	Return only these element codenames. Sent as one comma-separated `elements` value.

depth is 0 to 2; Kontent silently clamps anything outside it, so the plugin rejects it instead. next_skip is the next page, and null on the last one. Output

Name	Type	Required	Description
`items`	`object[]`	Yes	—
`modular_content`	`Record<string, any> \| null`	No	—
`pagination`	`object \| null`	No	—
`next_skip`	`number \| null`	Yes	The `skip` for the next page; null on the last page.

items full type

{
  system: {
    id: string,
    name?: string | null,
    codename?: string | null,
    language?: string | null,
    type?: string | null,
    collection?: string | null,
    sitemap_locations?: string[] | null,
    last_modified?: string | null,
    workflow?: string | null,
    workflow_step?: string | null
  },
  elements?: Record<string, {
    type: string,
    name?: string | null,
    value?: any
  }> | null
}[]

pagination full type

{
  skip?: number | null,
  limit?: number | null,
  count?: number | null,
  next_page?: string | null
} | null

Languages

list

languages.list The environment’s languages, each with the codename to read content in Risk: read

await corsair.kontentai.api.languages.list({ limit: 10 });

Input

Name	Type	Required	Description
`skip`	`number`	No	Items to skip. Defaults to 0.
`limit`	`number`	No	Items per page, at most 2000. Without it Kontent returns everything from `skip` on in one answer.
`order`	`string`	No	A sort, such as `system.last_modified` or `elements.price[asc]`. Suffix the field with `[desc]` to reverse it; a `-` prefix is refused with a 400.
`preview`	`boolean`	No	Read the latest version, including unpublished content, from the Preview API. Needs a Delivery API key with preview access stored on the account.

Output

Name	Type	Required	Description
`languages`	`object[]`	Yes	—
`pagination`	`object \| null`	No	—
`next_skip`	`number \| null`	Yes	—

languages full type

{
  system: {
    id: string,
    name?: string | null,
    codename?: string | null
  }
}[]

pagination full type

{
  skip?: number | null,
  limit?: number | null,
  count?: number | null,
  next_page?: string | null
} | null

Taxonomies

list

taxonomies.list The taxonomy groups with their nested terms, which an item’s taxonomy element points at Risk: read

await corsair.kontentai.api.taxonomies.list({ limit: 10 });

Input

Name	Type	Required	Description
`skip`	`number`	No	Items to skip. Defaults to 0.
`limit`	`number`	No	Items per page, at most 2000. Without it Kontent returns everything from `skip` on in one answer.
`order`	`string`	No	A sort, such as `system.last_modified` or `elements.price[asc]`. Suffix the field with `[desc]` to reverse it; a `-` prefix is refused with a 400.
`preview`	`boolean`	No	Read the latest version, including unpublished content, from the Preview API. Needs a Delivery API key with preview access stored on the account.

Terms nest, so a term carries its own children. Output

Name	Type	Required	Description
`taxonomies`	`object[]`	Yes	—
`pagination`	`object \| null`	No	—
`next_skip`	`number \| null`	Yes	—

taxonomies full type

{
  system: {
    id: string,
    name?: string | null,
    codename?: string | null,
    last_modified?: string | null
  },
  terms?: {
    name?: string | null,
    codename?: string | null,
    terms?: (recursive)[] | null
  }[] | null
}[]

pagination full type

{
  skip?: number | null,
  limit?: number | null,
  count?: number | null,
  next_page?: string | null
} | null

Types

get

types.get One content type by codename, with its element definitions Risk: read

await corsair.kontentai.api.types.get({ codename: 'about_us' });

Input

Name	Type	Required	Description
`codename`	`string`	Yes	The item, type or taxonomy codename, such as `about_us`.
`preview`	`boolean`	No	Read the latest version, including unpublished content, from the Preview API. Needs a Delivery API key with preview access stored on the account.

Output

Name	Type	Required	Description
`type`	`object`	Yes	—

type full type

{
  system: {
    id: string,
    name?: string | null,
    codename?: string | null,
    last_modified?: string | null
  },
  elements?: Record<string, {
    type: string,
    name?: string | null,
    taxonomy_group?: string | null,
    options?: {
      name?: string | null,
      codename?: string | null
    }[] | null
  }> | null
}

list

types.list The content types, each with the element definitions an item of that type carries Risk: read

await corsair.kontentai.api.types.list({ limit: 10 });

Input

Name	Type	Required	Description
`skip`	`number`	No	Items to skip. Defaults to 0.
`limit`	`number`	No	Items per page, at most 2000. Without it Kontent returns everything from `skip` on in one answer.
`order`	`string`	No	A sort, such as `system.last_modified` or `elements.price[asc]`. Suffix the field with `[desc]` to reverse it; a `-` prefix is refused with a 400.
`preview`	`boolean`	No	Read the latest version, including unpublished content, from the Preview API. Needs a Delivery API key with preview access stored on the account.

Each type carries the element definitions an item of that type returns. Output

Name	Type	Required	Description
`types`	`object[]`	Yes	—
`pagination`	`object \| null`	No	—
`next_skip`	`number \| null`	Yes	—

types full type

{
  system: {
    id: string,
    name?: string | null,
    codename?: string | null,
    last_modified?: string | null
  },
  elements?: Record<string, {
    type: string,
    name?: string | null,
    taxonomy_group?: string | null,
    options?: {
      name?: string | null,
      codename?: string | null
    }[] | null
  }> | null
}[]

pagination full type

{
  skip?: number | null,
  limit?: number | null,
  count?: number | null,
  next_page?: string | null
} | null

Overview

Plugins

Kontent.ai API reference

Items

get

list

Languages

list

Taxonomies

list

Types

get

list