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",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "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_`
Session thread	`sthr_`
Turn	`turn_`
File	`file_`
Vault	`vault_`
Vault credential	`vcred_`
Skill	`skill_`
Memory store	`memstore_`
Memory entry	`mem_`
Memory version	`memver_`
Work item	`work_`
Forward template	`tmpl_`
Forward identity	`idn_`
Forward identity config	`cfg_`
Forward channel	`channel_`
Forward QR session	`qr_`
Forward schedule	`sched_`
Forward schedule run	`srun_`
Forward resource	Reuses the registered resource’s own ID prefix

Next steps

Overview

How Qoder Cloud Agents fits together.

First steps

Define your agent

Configure agent environment

Delegate work to your agent

Manage agent context

Best Practices

API reference

Common data structures

Metadata object

Paginated list

Error envelope

Timestamp

ID prefixes

Next steps

Overview

​Metadata object

​Paginated list

​Error envelope

​Timestamp

​ID prefixes

​Next steps

Overview

Metadata object

Paginated list

Error envelope

Timestamp

ID prefixes

Next steps