> ## 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.

# 共通データ構造

> Cloud Agents API 全体で使用される共通エンベロープと再利用可能なオブジェクト。

このページでは、複数の API グループで使用されるリソース横断的な構造を定義します。リソース固有の構造は各リソースディレクトリのデータ構造ページに記載されています。

## メタデータオブジェクト

`metadata` は呼び出し元が定義する文字列属性のフラットオブジェクトです。

| ルール   | 説明                 |
| ----- | ------------------ |
| 形式    | 値が文字列の JSON オブジェクト |
| 最大キー数 | 16                 |
| 最大キー長 | 64 Unicode 文字      |
| 最大値長  | 512 Unicode 文字     |
| デフォルト | 省略時は `{}`          |

例:

```json theme={null}
{
  "team": "docs",
  "project": "cloud-agents"
}
```

## ページネーションリスト

リストエンドポイントはカーソルページネーションエンベロープを返します。

| フィールド      | 型              | 説明                                       |
| ---------- | -------------- | ---------------------------------------- |
| `data`     | array          | 現在のページのリソースオブジェクト                        |
| `has_more` | boolean        | さらにレコードがあるかどうか                           |
| `first_id` | string \| null | 最初に返されたアイテムのカーソル ID、`data` が空の場合は `null` |
| `last_id`  | string \| null | 最後に返されたアイテムのカーソル ID、`data` が空の場合は `null` |

## エラーエンベロープ

エラーレスポンスは以下のエンベロープを使用します:

```json theme={null}
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'name' is required."
  }
}
```

| フィールド           | 型      | 説明                                                                                                                          |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| `type`          | string | 固定値 `"error"`                                                                                                               |
| `error.type`    | string | エラーカテゴリ。`invalid_request_error`、`authentication_error`、`permission_error`、`not_found_error`、`conflict_error`、`api_error` など |
| `error.message` | string | 人間が読めるエラーメッセージ                                                                                                              |

## タイムスタンプ

タイムスタンプは UTC の ISO 8601 / RFC 3339 文字列です（例: `"2026-05-18T15:26:39.61669Z"`）。一部のフィールドは null 許容です。詳細は各リソーススキーマに明記されています。

## ID プレフィックス

| リソース                    | プレフィックス                    |
| ----------------------- | -------------------------- |
| Agent                   | `agent_`                   |
| Environment             | `env_`                     |
| Session                 | `sess_`                    |
| Session イベント            | `evt_`                     |
| Session スレッド            | `sthr_`                    |
| Turn                    | `turn_`                    |
| File                    | `file_`                    |
| Vault                   | `vault_`                   |
| Vault クレデンシャル           | `vcred_`                   |
| Skill                   | `skill_`                   |
| Memory Store            | `memstore_`                |
| Memory エントリ             | `mem_`                     |
| Memory バージョン            | `memver_`                  |
| ワークアイテム                 | `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        | 登録済みリソース自身の ID プレフィックスを再利用 |

## 次のステップ

<CardGroup cols={2}>
  <Card title="概要" icon="rocket" href="/ja/cloud-agents/overview">
    Qoder Cloud Agents の全体像。
  </Card>
</CardGroup>