Create a template

POST /api/v1/forward/templates Forward が Identity に対してセッションを開始する際に使用する、デフォルトのエージェント設定とセッションのデフォルト値を定義するテンプレートを作成します。

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT または SAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	安全でないリクエストに対する任意の冪等性キー。
`X-Qoder-Beta`	Browser Use を使用する場合	Browser Use を有効にするには `browser-use-2026-07-14` を指定する必要があります。

Body parameters

Parameter	Type	Required	Description
`name`	string	Yes	テンプレート名。1〜256 文字で、アカウント内で一意である必要があります。
`model`	string\|object	Yes	モデル ID、またはモデル ID と任意の調整フィールドを含むオブジェクト。
`environment_id`	string	Yes	このテンプレートから作成されたセッションで使用されるデフォルトの Environment。
`description`	string	No	テンプレートの説明。最大 2048 文字。
`system`	string	No	システムプロンプト。最大 100,000 文字。
`tools`	array	No	ツール設定のリスト。最大 128 件。
`mcp_servers`	array	No	MCP サーバー設定のリスト。最大 20 件。
`skills`	array	No	Skill のバインディングリスト。最大 20 件。
`multiagent`	object\|null	No	Multi-agent コラボレーション設定。`type` は `coordinator` である必要があります。省略または `null` で無効になります。
`vaults`	object	No	Vault ID をキーとするデフォルトの Vault 設定。
`files`	object	No	ファイル ID をキーとするデフォルトのファイルリソース。
`github_repositories`	object	No	呼び出し側が指定する binding key をキーとするデフォルトの GitHub リポジトリ。最大 20 件。
`environment_variables`	object \| string	No	デフォルトのセッション環境変数。
`metadata`	object	No	カスタムメタデータ。

Nested configuration objects

Model

model にはモデル ID の文字列、またはモデル ID と任意の調整フィールドを含むオブジェクトを指定できます。

Field	Type	Required	Description
`id`	string	Yes	モデル識別子。利用可能な値は List models エンドポイントで確認できます。
`effort`	string	No	Reasoning effort。`none`、`low`、`medium`、`high`、`xhigh`、`max` のいずれか。各モデルが対応する値は `efforts` を確認してください。
`context_window`	integer	No	希望するコンテキストウィンドウの token 数。モデルの `available_context_windows` に含まれる正の整数を指定します。

Vaults

vaults は Vault ID をキーとするマップです。各項目には任意の enabled boolean を指定でき、省略時は true と同じです。項目内に vault_id、id、resource_id を重複して指定しないでください。

{
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    }
  }
}

レスポンスでは vaults が常にオブジェクト形式で返されます。

File resources

files は File ID をキーとするマップです。各項目の内部に file_id、id、resource_id を含めないでください。Forward は Session の作成時に mount_path を注入します。

Field	Type	Required	Description
`enabled`	boolean	No	デフォルトは `true`。`false` にすると、Identity Config で継承されたファイルが無効になります。

GitHub repositories

github_repositories は binding key をキーとするマップです。binding key は [A-Za-z][A-Za-z0-9_-]{0,63} に一致する必要があり、最大 20 件まで指定できます。正規化後のリポジトリ URL と mount path は重複できません。

Field	Type	Required	Description
`url`	string	Yes	絶対 HTTPS リポジトリ URL。userinfo、query、fragment、パーセントエンコード、バックスラッシュは使用できず、末尾の `.git` は正規化時に削除されます。
`authorization_token`	string	Yes	書き込み専用のリポジトリアクセストークン。レスポンスには返されません。最大 8192 bytes で、ASCII の英字、数字、アンダースコアのみ使用できます。
`mount_path`	string	No	Session 内の正規化された絶対 mount path。`/` は指定できません。省略時は `/data/workspace/<repository-name>` です。

Tools array

各 tools[] の項目は type によって選択されます。

Field	Type	Applies to	Description
`type`	string	All	必須。`agent_toolset_20260401`、`browser_toolset_20260714`、`mcp_toolset`、または `custom`。
`enabled_tools`	array	`agent_toolset_20260401`	便宜的な許可リスト。空でないリストを指定すると、これらの組み込みツールのみが有効になります。
`disallowed_tools`	array	`agent_toolset_20260401`	便宜的な拒否リスト。無効化されたツール設定にコンパイルされます。
`configs`	array	`agent_toolset_20260401`, `mcp_toolset`	ツールごとの有効化と権限ポリシー。
`mcp_server_name`	string	`mcp_toolset`	必須。`mcp_servers[].name` のいずれかの項目と一致する必要があります。
`name`	string	`custom`	必須のカスタムツール名。組み込みツールと競合してはいけません。
`description`	string	`custom`	必須のカスタムツールの説明。
`input_schema`	object	`custom`	必須の JSON Schema。`input_schema.type` は `object` である必要があります。

組み込みツール名は Bash、Read、Write、Edit、Glob、Grep、WebFetch、WebSearch、DeliverArtifacts です。

Browser Use（Beta）

Browser Use は現在 Beta 機能であり、機能、制限、API の詳細は変更される可能性があります。この Template から作成する Session でブラウザ機能を有効にするには、次の toolset を tools に追加します：

{
  "type": "browser_toolset_20260714"
}

リクエストには、次の Header も含める必要があります：

X-Qoder-Beta: browser-use-2026-07-14

Tool config

tools[].configs[] の項目はこの形式を使用します。

Field	Type	Required	Description
`name`	string	Yes	ツール名。`agent_toolset_20260401` の場合は組み込みツール名、`mcp_toolset` の場合は MCP ツール名。
`enabled`	boolean	No	`false` にするとツールを非表示にして拒否します。`true` にすると明示的に有効化します。
`permission_policy`	object	No	実行時の権限の挙動。

Permission policy

Field	Type	Required	Description
`type`	string	Yes	`always_allow`、`always_ask`、または `always_deny`。

MCP servers

Field	Type	Required	Description
`type`	string	No	現在は `http` のみ。省略された値は Effective Config で HTTP MCP サーバーとして扱われます。
`name`	string	Yes	Template 内で一意の MCP サーバー名。`tools[].mcp_server_name` から参照されます。
`url`	string	Yes	Streamable HTTP MCP エンドポイントの URL。

Skills

Field	Type	Required	Description
`type`	string	Yes	`custom` または `qoder`。
`skill_id`	string	Yes	Skill ID。
`version`	string	No	Skill のバージョン。省略した場合は最新バージョンが使用されます。
`enabled`	boolean	No	デフォルトは `true`。`false` にすると、コンパイルされたエージェント設定にその Skill が含まれなくなります。

Multiagent

multiagent は現在の Template を coordinator として設定し、委任先の Agent を宣言します。

フィールド	型	必須	説明
`type`	string	はい	`coordinator` を指定します。
`agents`	array	はい	委任可能な Agent の一覧。1〜20 件を指定します。

multiagent.agents[] の各項目は、次のいずれかの形式を使用できます：

形式	例	説明
Template 参照	`{"type":"agent","template_id":"tmpl_research"}`	現在の呼び出し元がアクセスできる Forward Template を参照します。
Coordinator 自身	`{"type":"self"}`	現在の coordinator を委任可能な Agent として使用します。

フィールド	型	適用対象	必須	説明
`type`	string	すべて	はい	`agent` は別の Agent、`self` は coordinator 自身を参照します。
`template_id`	string	`agent`	はい	参照する Forward Template ID。
`name`	string	`agent`	いいえ	Sub-Agent の表示名。

参照する Template は存在し、現在の呼び出し元からアクセスできる必要があります。multiagent を使用する場合、tools に agent_toolset_20260401 が必要です。Template の作成時には Forward がこのツールセットを自動的に追加します。

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/templates' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support assistant",
  "description": "Handles customer support requests",
  "model": {
    "id": "ultimate",
    "effort": "high",
    "context_window": 400000
  },
  "system": "You are a helpful support assistant.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "mcp_servers": [],
  "skills": [],
  "multiagent": {
    "type": "coordinator",
    "agents": [
      {
        "type": "agent",
        "template_id": "tmpl_research",
        "name": "Research Agent"
      },
      {
        "type": "self"
      }
    ]
  },
  "environment_id": "env_xxx",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    }
  },
  "files": {},
  "github_repositories": {
    "source": {
      "url": "https://github.com/acme/support-agent.git",
      "authorization_token": "github_pat_xxx",
      "mount_path": "/data/workspace/support-agent"
    }
  },
  "environment_variables": {
    "BASE_MODE": "support"
  },
  "metadata": {}
}'

Example response

HTTP 201 Created

{
  "type": "template",
  "id": "tmpl_support",
  "name": "Support assistant",
  "description": "Handles customer support requests",
  "status": "active",
  "model": {
    "id": "ultimate",
    "effort": "high",
    "context_window": 400000
  },
  "system": "You are a helpful support assistant.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "mcp_servers": [],
  "skills": [],
  "multiagent": {
    "type": "coordinator",
    "agents": [
      {
        "type": "agent",
        "template_id": "tmpl_research",
        "name": "Research Agent"
      },
      {
        "type": "self"
      }
    ]
  },
  "environment_id": "env_xxx",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    }
  },
  "files": {},
  "github_repositories": {
    "source": {
      "url": "https://github.com/acme/support-agent",
      "mount_path": "/data/workspace/support-agent"
    }
  },
  "environment_variables": {
    "BASE_MODE": "support"
  },
  "metadata": {},
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:00:00Z"
}

Response fields

Field	Type	Description
`type`	string	常に `template`。
`id`	string	Template ID。
`status`	string	`active` または `archived`。
`multiagent`	object\|null	Multi-agent 設定。未設定の場合は `null`。
`environment_id`	string	セッションで使用されるデフォルトの Environment ID。
`vault_ids`	array	デフォルトの Vault ID。
`files`	object	ファイル ID をキーとするデフォルトのファイルリソース設定。
`created_at`	string	作成タイムスタンプ。
`updated_at`	string	更新タイムスタンプ。

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	リクエストボディが不正、またはサポートされていないフィールド値。
400	`invalid_request_error`	`browser_toolset_20260714` を使用しているが、正しい `X-Qoder-Beta` Header がない。
400	`invalid_request_error`	`multiagent` の構造が不正、`agents` が 1〜20 件の範囲外、または参照先 Template にアクセスできない。
401	`authentication_error`	PAT または SAT が無効または期限切れ。
404	`not_found_error`	参照された environment、skill、vault、または file が存在しない。
409	`conflict_error`	テンプレート名が既に存在する。
401	`authentication_error`	`authentication_required`

Notes

id は Forward によって生成されます。作成リクエストで Template ID を送信しないでください。
files はファイル ID をキーとするマップです。各ファイル項目の内部に file_id、id、resource_id を含めないでください。
Forward はセッション作成時にファイルのマウントパスを注入します。

Create a template

Headers

Body parameters

Nested configuration objects

Model

Vaults

File resources

GitHub repositories

Tools array

Browser Use（Beta）

Tool config

Permission policy

MCP servers

Skills

Multiagent

Example request

Example response

Response fields

Errors

Notes

テンプレートの一覧取得

セッションの作成

​Headers

​Body parameters

​Nested configuration objects

​Model

​Vaults

​File resources

​GitHub repositories

​Tools array

​Browser Use（Beta）

​Tool config

​Permission policy

​MCP servers

​Skills

​Multiagent

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

テンプレートの一覧取得

セッションの作成

Headers

Body parameters

Nested configuration objects

Model

Vaults

File resources

GitHub repositories

Tools array

Browser Use（Beta）

Tool config

Permission policy

MCP servers

Skills

Multiagent

Example request

Example response

Response fields

Errors

Notes

Related