Skip to main content
Conventions

Generic Data Structures

Defines the shared response envelopes and base objects reused across the Cloud Agents API.

Metadata object

metadata is a flat object for caller-defined string attributes.
RuleDescription
ShapeJSON object whose values are strings
Maximum keys16
Maximum key length64 Unicode characters
Maximum value length512 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."
  }
}
FieldTypeDescription
typestringAlways "error"
error.typestringError category, such as invalid_request_error, authentication_error, permission_error, not_found_error, conflict_error, or api_error
error.messagestringHuman-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

ResourcePrefix
Agentagent_
Environmentenv_
Sessionsess_
Session eventevt_
Session threadsthr_
Turnturn_
Filefile_
Vaultvault_
Vault credentialvcred_
Skillskill_
Memory storememstore_
Memory entrymem_
Memory versionmemver_
Guides
Tutorials
API Reference