---
title: "Data Models Reference"
url: "https://adaptocms.com/docs/data-models/"
source: adaptocms.com
---

# Data Models Reference

This page documents all response models returned by the Adapto CMS Public API. These schemas define the shape of data you will receive from API calls.

* * *

## PaginatedResponse

The standard envelope for all paginated list endpoints.

```
{
  "items": [],       // Array of resource objects
  "total": 0,        // Total number of matching items across all pages
  "page": 1,         // Current page number
  "limit": 20,       // Items per page
  "pages": 0         // Total number of pages
}
```

Field

Type

Description

`items`

array

Array of resource objects for the current page

`total`

integer

Total matching items across all pages

`page`

integer

Current page number (1-based)

`limit`

integer

Number of items per page

`pages`

integer

Total number of pages

* * *

## ArticleResponseModel

Full article object returned by article endpoints.

Field

Type

Required

Description

`id`

string

Yes

Unique identifier (UUID)

`title`

string

Yes

Article title

`content`

string

Yes

Full HTML content body

`slug`

string

Yes

URL-friendly identifier

`author`

string

Yes

Author name

`source`

ArticleSourceModel

Yes

Content source information

`categories`

string\[\]

Yes

Array of category IDs

`tags`

string\[\]

Yes

Array of tag strings

`summary`

string

Yes

Short summary or excerpt

`language`

string

Yes

ISO 639-1 language code

`status`

string

Yes

One of: `draft`, `published`, `archived`, `deleted`

`created_at`

string | null

No

Creation timestamp

`updated_at`

string | null

No

Last update timestamp

`published_at`

string | null

No

Publication timestamp

`media_objects_placements`

object\[\]

Yes

Media object placement data

`custom_fields`

object

Yes

Map of field name to CustomFieldModel

`translation_of_id`

string | null

No

ID of the source article (if this is a translation)

`file_urls`

object | null

No

Map of file\_id to CDN URL for referenced files

* * *

## ArticlePreviewResponseModel

Lightweight article object (no `content`, `custom_fields`, `file_urls`, or `media_objects_placements`).

Contains: `id`, `title`, `slug`, `author`, `source`, `categories`, `tags`, `summary`, `language`, `status`, `created_at`, `updated_at`, `published_at`, `translation_of_id`.

* * *

## ArticleSourceModel

Describes where the article content originated.

Field

Type

Required

Description

`type`

string

Yes

One of: `internal`, `external`, `user_submitted`, `ai_generated`

`name`

string

Yes

Source name (e.g. "Dashboard", "RSS Feed")

`url`

string | null

No

Source URL (for external content)

`author`

string | null

No

Original author (for external content)

`published_date`

integer | null

No

Original publication date (Unix timestamp)

`license`

string | null

No

Content license identifier

* * *

## CategoryResponseModel

Field

Type

Required

Description

`id`

string

Yes

Unique identifier (UUID)

`name`

string

Yes

Category name

`slug`

string

Yes

URL-friendly identifier

`description`

string | null

Yes

Category description

`parent_id`

string | null

Yes

Parent category ID (null for root categories)

`language`

string

Yes

ISO 639-1 language code

`created_at`

string

Yes

Creation timestamp

`updated_at`

string

Yes

Last update timestamp

`translation_of_id`

string | null

Yes

Source category ID (if translation)

`custom_fields`

object

Yes

Map of custom fields

`file_urls`

object | null

No

Map of file\_id to CDN URL

* * *

## PageResponseModel

Field

Type

Required

Description

`id`

string

Yes

Unique identifier (UUID)

`title`

string

Yes

Page title

`content`

string

Yes

Full HTML content

`slug`

string

Yes

URL-friendly identifier

`menu_label`

string | null

Yes

Short label for navigation menus

`parent_id`

string | null

Yes

Parent page ID (for hierarchical pages)

`language`

string

Yes

ISO 639-1 language code

`tags`

string\[\]

Yes

Array of tag strings

`status`

string

Yes

One of: `draft`, `published`, `archived`, `deleted`

`created_at`

string

Yes

Creation timestamp

`updated_at`

string

Yes

Last update timestamp

`published_at`

string | null

Yes

Publication timestamp

`media_objects_placements`

object\[\]

Yes

Media object placement data

`translation_of_id`

string | null

Yes

Source page ID (if translation)

`custom_fields`

object

Yes

Map of custom fields

`file_urls`

object | null

No

Map of file\_id to CDN URL

* * *

## PagePreviewResponseModel

Lightweight page object (no `content`, `custom_fields`, `file_urls`, or `media_objects_placements`).

Contains: `id`, `title`, `slug`, `menu_label`, `parent_id`, `language`, `tags`, `status`, `created_at`, `updated_at`, `published_at`, `translation_of_id`.

* * *

## CustomCollectionResponseModel

Field

Type

Required

Description

`id`

string

Yes

Unique identifier (UUID)

`name`

string

Yes

Collection name

`slug`

string

Yes

URL-friendly identifier

`description`

string

Yes

Collection description

`language`

string

Yes

ISO 639-1 language code

`fields`

FieldDefinitionModel\[\]

Yes

Array of field schema definitions

`status`

string

Yes

One of: `draft`, `published`, `archived`, `deleted`

`created_at`

string

Yes

Creation timestamp

`updated_at`

string

Yes

Last update timestamp

* * *

## FieldDefinitionModel

Defines a field within a custom collection's schema.

Field

Type

Required

Description

`name`

string

Yes

Field identifier (used as key in item data)

`label`

string

Yes

Human-readable display label

`type`

string

Yes

Field type (see below)

`required`

boolean

No

Whether the field is required (default: false)

`multiple`

boolean

No

Whether multiple values are allowed (default: false)

`description`

string | null

No

Help text or description

`default_value`

any | null

No

Default value for the field

`related_collection`

string | null

No

For `reference` type: the related collection ID

`options`

object\[\] | null

No

For `select`/`multi_select`: array of option objects

`validation`

object | null

No

Validation rules

### Available Field Types

Type

Description

`text`

Single-line text input

`textarea`

Multi-line text input

`rich_text`

HTML rich text content

`number`

Numeric value

`date`

Date value

`date_range`

Date range (start and end)

`boolean`

True/false toggle

`select`

Single selection from predefined options

`multi_select`

Multiple selections from predefined options

`reference`

Reference to item(s) in another collection

`image`

Image file reference

`file`

File reference

`url`

URL string

`email`

Email address

`color`

Color value

* * *

## CustomCollectionItemResponseModel

Field

Type

Required

Description

`id`

string

Yes

Unique identifier (UUID)

`collection_id`

string

Yes

Parent collection ID

`title`

string

Yes

Item title

`slug`

string

Yes

URL-friendly identifier

`data`

object

Yes

Item data matching the collection's field schema

`language`

string

Yes

ISO 639-1 language code

`status`

string

Yes

One of: `draft`, `published`, `archived`, `deleted`

`created_at`

string

Yes

Creation timestamp

`updated_at`

string

Yes

Last update timestamp

`published_at`

string | null

Yes

Publication timestamp

`media_objects_placements`

object\[\]

Yes

Media object placement data

`translation_of_id`

string | null

Yes

Source item ID (if translation)

`meta_data`

object | null

No

Arbitrary metadata

`file_urls`

object | null

No

Map of file\_id to CDN URL for files referenced in data

* * *

## CustomCollectionItemPreviewResponseModel

Lightweight item object (no `data`, `file_urls`, or `media_objects_placements`).

Contains: `id`, `collection_id`, `title`, `slug`, `language`, `status`, `created_at`, `updated_at`, `published_at`, `translation_of_id`, `meta_data`.

* * *

## MediaObjectPlacement

Media placements appear on Articles, Pages, and Custom Collection Items in the `media_objects_placements` array. Each placement associates a media object with a named slot on the content item.

Field

Type

Required

Description

`placement_key`

string

Yes

Named slot identifier (e.g., `"hero"`, `"thumbnail"`, `"gallery_1"`)

`media_object`

MediaObject

Yes

The media object with file details and URL

`caption`

string | null

No

Caption text for the media

`alt_text`

string | null

No

Alt text for accessibility (use for images)

`meta_data`

string | null

No

Free-form metadata (JSON string)

Placement keys are arbitrary strings defined by your application. Common conventions include `"hero"`, `"thumbnail"`, `"og_image"`, `"avatar"`, `"gallery_1"`, `"gallery_2"`, etc.

### Example

```
{
  "placement_key": "hero",
  "media_object": {
    "id": "mo-001",
    "title": "Product hero image",
    "description": "Main product shot on white background",
    "file_id": "file-abc-123",
    "url": "https://media.adaptocms.com/tenants/.../hero.jpg",
    "type": "image",
    "created_at": "2026-01-15T10:00:00",
    "updated_at": "2026-01-15T10:00:00"
  },
  "caption": "The new Adapto dashboard",
  "alt_text": "Screenshot of the Adapto CMS dashboard",
  "meta_data": null
}
```

* * *

## MediaObject

Represents a media asset (image, video, audio, document, or external embed) stored in Adapto's media system.

Field

Type

Required

Description

`id`

string

Yes

Unique identifier (UUID)

`title`

string | null

No

Media title

`description`

string | null

No

Media description

`file_id`

string

Yes

ID of the underlying file in storage

`url`

string

Yes

Direct CDN URL to the file (served from `media.adaptocms.com`)

`type`

string

Yes

Media type — see MediaType values below

`created_at`

string | null

No

Creation timestamp (ISO 8601)

`updated_at`

string | null

No

Last update timestamp (ISO 8601)

* * *

## MediaType Values

The `type` field on a MediaObject identifies the kind of media. This determines how your frontend should render it.

Value

Description

Rendering Approach

`image`

Image files (JPEG, PNG, GIF, WebP, AVIF, SVG, HEIC)

`<img>` tag

`video`

Uploaded video files (MP4, WebM, MOV, AVI, etc.)

`<video>` tag with `src`

`audio`

Audio files (MP3, WAV, AAC, FLAC, OGG)

`<audio>` tag

`document`

Documents (PDF, DOC, DOCX, CSV, XLS, XLSX)

Download link or `<iframe>` for PDF

`youtube`

YouTube video (URL stored in `url` field)

YouTube `<iframe>` embed

`vimeo`

Vimeo video

Vimeo `<iframe>` embed

`tiktok`

TikTok video

TikTok embed script

`instagram_reel`

Instagram Reel

Instagram embed

`instagram_post`

Instagram Post

Instagram embed

`other`

Any other file type

Download link

* * *

## MicroCopyResponseModel

Field

Type

Required

Description

`id`

string

Yes

Unique identifier (UUID)

`key`

string

Yes

Unique key identifier (e.g. `nav.home`)

`value`

string

Yes

The text value

`language`

string

Yes

ISO 639-1 language code

`translation_of`

string | null

Yes

Source micro copy ID (if translation)

`tags`

string

Yes

Comma-separated tags

`created_at`

string

Yes

Creation timestamp

`updated_at`

string

Yes

Last update timestamp

`custom_fields`

object

Yes

Map of custom fields

`file_urls`

object | null

No

Map of file\_id to CDN URL

* * *

## CustomFieldModel

Represents a custom field value on articles, categories, pages, or micro copy entries.

Field

Type

Required

Description

`type`

string

Yes

Field type (same types as FieldDefinitionModel)

`multiple`

boolean

No

Whether multiple values are present (default: false)

`related_collection`

string | null

No

Related collection ID (for reference type)

`media_objects_placements`

object\[\]

No

Media placements (for rich\_text type)

`value`

any

No

The actual field value

* * *

## SearchResultModel

Field

Type

Required

Description

`entity_type`

string

Yes

Type: `article`, `page`, or `collection_item`

`id`

string

Yes

Entity unique identifier

`title`

string

Yes

Entity title

`slug`

string

Yes

URL-friendly slug

`parent_id`

string | null

No

Parent page ID or collection ID

`parent_name`

string | null

No

Parent page title or collection name

* * *

## HTTPValidationError

Returned when request validation fails (HTTP 422).

```
{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}
```

Field

Type

Description

`detail`

ValidationError\[\]

Array of validation errors

### ValidationError

Field

Type

Description

`loc`

(string | integer)\[\]

Location of the error (e.g. `["query", "limit"]`)

`msg`

string

Human-readable error message

`type`

string

Error type identifier