Common data structures

This page defines cross-resource structures used by multiple API groups. Resource-specific structures are documented in each resource directory’s data-structures page.

Metadata object

metadata is a flat object for caller-defined string attributes.

Rule	Description
Shape	JSON object whose values are strings
Maximum keys	16
Maximum key length	64 Unicode characters
Maximum value length	512 Unicode characters
Default	`{}` when omitted

Example:

{
  "team": "docs",
  "project": "cloud-agents"
}

Paginated list

List endpoints return a cursor pagination envelope.

Field	Type	Description
`data`	array	Resource objects on the current page
`has_more`	boolean	Whether more records are available
`first_id`	string \| null	Cursor ID of the first returned item, or `null` when `data` is empty
`last_id`	string \| null	Cursor ID of the last returned item, or `null` when `data` is empty

Error envelope

Error responses use this envelope:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'name' is required."
  }
}

Field	Type	Description
`type`	string	Always `"error"`
`error.type`	string	Error category, such as `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `conflict_error`, or `api_error`
`error.message`	string	Human-readable error message

Timestamp

Timestamps are ISO 8601 / RFC 3339 strings in UTC, for example "2026-05-18T15:26:39.61669Z". Some fields are nullable; each resource schema calls that out explicitly.

ID prefixes

Resource	Prefix
Agent	`agent_`
Environment	`env_`
Session	`sess_`
Session event	`evt_`
Turn	`turn_`
File	`file_`
Vault	`vault_`
Vault credential	`vcred_`
Skill	`skill_`
Memory store	`memstore_`
Memory entry	`mem_`
Memory version	`memver_`

Overview

How Qoder Cloud Agents fits together.

​Metadata object

​Paginated list

​Error envelope

​Timestamp

​ID prefixes

​Related