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