> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common data structures

> Shared envelopes and reusable objects used across the Cloud Agents API.

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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Overview" icon="rocket" href="/cloud-agents/overview">
    How Qoder Cloud Agents fits together.
  </Card>
</CardGroup>