コードからワークスペースを呼び出す
自分のデプロイメント向けの REST API に、名前付きの API キーでアクセスできます。このページのリファレンスは、サーバーが提供するものと同じ OpenAPI ドキュメントから生成しています。
名前付きキーによる認証このセクションへのリンクをコピー
ワークスペースの 設定 › API キー でキーを作成します。名前を付け、スコープを選び、必要なら有効期限を設定します。キーは obk_ で始まり、表示されるのは一度だけです。すべてのリクエストで送信してください。
curl -H "Authorization: Bearer $api_key" \
https://<your-deployment>/api/meキーは作成した本人として動作し、それ以上の権限は持ちません。現在のロールとアクセス権はリクエストのたびに確認されます。どのキーでもキーの作成や失効はできません。admin スコープを持つキーは、管理者である所有者が使えるすべてのルートに届きます。以下に載っていないルートも含みます。
スコープこのセクションへのリンクをコピー
キーが持つのは、作成時に選んだスコープだけです。管理者向けのスコープは、所有者が管理者でなくなったキーでは何もしません。
read:profile | Read your profileプロフィールの読み取り Who the key belongs to and their role.キーの持ち主とそのロールです。 |
|---|---|
read:bots | Read BotsBot の読み取り The Bots the owner can see, and each one's profile.所有者が見られる Bot と、それぞれのプロフィールです。 |
read:channels | Read conversations会話の読み取り The owner's conversations, and the messages in their group conversations.所有者の会話と、所有者が参加しているグループ会話のメッセージです。 |
write:messages | Send messagesメッセージの送信 Post a message into a group conversation the owner belongs to, as the owner.所有者が参加しているグループ会話に、所有者としてメッセージを投稿します。 |
read:routines | Read routinesルーティンの読み取り The owner's routines and their run history.所有者のルーティンと、その実行履歴です。 |
write:routines | Run routinesルーティンの実行 Start one of the owner's routines now. This does real work, exactly as a scheduled run would.所有者のルーティンをいますぐ 1 つ開始します。予定どおりの実行とまったく同じく、実際の作業を行います。 |
manage:routines | Create and change routinesルーティンの作成と変更 Create the owner's routines, change their instruction and schedule, switch them on or off, delete them, and add or remove the triggers that start them.所有者のルーティンを作成し、指示とスケジュールの変更、オン・オフの切り替え、削除、ルーティンを開始するトリガーの追加・削除を行います。 |
read:approvals | Read approvals承認の読み取り The approval requests and Bot questions waiting for the owner, and what the Bot saw when it asked.所有者を待っている承認リクエストと Bot からの質問、そして Bot が質問したときに見ていた内容です。 |
write:approvals | Answer approvals and questions承認と質問への回答 Approve or refuse the owner's waiting requests and answer Bots' questions, as the owner. Each decision is recorded with the key's name.所有者として、待っているリクエストを承認または拒否し、Bot の質問に回答します。判断はそれぞれキーの名前とともに記録されます。 |
read:responsibilities | Read responsibilities担当業務の読み取り The owner's lasting goals, their runs and progress, and their triggers.所有者の継続的な目標、その実行と進捗、トリガーです。 |
manage:responsibilities | Manage responsibilities担当業務の管理 Create, change, pause, resume, complete and run the owner's responsibilities, and manage their triggers, including new signing secrets.所有者の担当業務を作成・変更・一時停止・再開・完了・実行し、新しい署名シークレットを含むトリガーを管理します。 |
read:memory | Read memoryメモリーの読み取り The memories the owner's Bots keep about them.所有者の Bot が所有者について覚えているメモリーです。 |
write:memory | Change memoryメモリーの変更 Add, edit, switch off and forget the memories the owner's Bots keep about them.所有者の Bot が所有者について覚えているメモリーを追加・編集・オフにし、忘れさせます。 |
read:tasks | Read tasksタスクの読み取り The owner's own task list, one task's history, and the list as a spreadsheet.所有者自身のタスク一覧、1 つのタスクの履歴、スプレッドシート形式の一覧です。 |
write:tasks | Change tasksタスクの変更 Add, change, tick off and delete the owner's own tasks, as the owner.所有者として、所有者自身のタスクを追加・変更・完了・削除します。 |
read:usage | Read usage and cost使用量とコストの読み取り Token use and estimated cost by Bot, model and day. The owner must be allowed to view usage.Bot・モデル・日ごとのトークン使用量と推定コストです。所有者に使用量の閲覧が許可されている必要があります。 |
manage:bots | Create and change BotsBot の作成と変更 Create Bots, change their profile and instructions, read their saved versions and delete them, exactly as the Bot dialog does. Only Bots the owner may change.Bot ダイアログと同じように、Bot を作成し、プロフィールと指示を変更し、保存されたバージョンを読み、削除します。対象は所有者が変更できる Bot だけです。 |
manage:skills | Manage skillsスキルの管理 List, write and delete the owner's skills, and give skills to or take them from Bots the owner may change.所有者のスキルを一覧・作成・削除し、所有者が変更できる Bot にスキルを付与したり外したりします。 |
read:files | Read Bots' filesBot のファイルの読み取り List, read, search and download the files in the workspace of a Bot the owner may use. Each read is decided and recorded as it is in the app.所有者が使える Bot のワークスペースにあるファイルを一覧・読み取り・検索・ダウンロードします。読み取りはアプリと同じく、その都度判断され記録されます。 |
write:files | Change Bots' filesBot のファイルの変更 Upload, write, move and delete files and make folders in the workspace of a Bot the owner may use, under the same rules and records as the app.所有者が使える Bot のワークスペースで、アプリと同じルールと記録のもと、ファイルのアップロード・書き込み・移動・削除とフォルダーの作成を行います。 |
use:mcp | Connect as an MCP serverMCP サーバーとして接続 Desktop assistants and code editors reach this workspace's tools over MCP. Each tool still needs its own scope: asking a Bot needs Send messages, running a routine needs Run routines.デスクトップアシスタントやコードエディターが、MCP でこのワークスペースのツールを使えます。ツールごとのスコープも引き続き必要です。Bot に質問するには「メッセージの送信」、ルーティンを実行するには「ルーティンの実行」が必要です。 |
read:analytics | Read analyticsアナリティクスの読み取り admin The Insights figures for business-intelligence tools: the overview, every report, the model comparison, the notable changes and the conversations behind a Bot's figures.BI ツール向けのインサイトの数値です。概要、すべてのレポート、モデルの比較、注目すべき変化、Bot の数値の元になった会話を含みます。 |
read:audit | Read the audit trail監査ログの読み取り admin Search and export the deployment's audit trail.デプロイの監査ログを検索し、書き出します。 |
read:people | Read peopleメンバーの読み取り admin Everybody on the deployment, their role and access.デプロイの全員と、そのロールとアクセス権です。 |
manage:people | Manage peopleメンバーの管理 admin Invitations, roles, suspensions and groups. Never makes an administrator.招待、ロール、利用停止、グループです。管理者を作ることはありません。 |
manage:webhooks | Manage webhooksWebhook の管理 admin Add, change, pause, resume, test and remove the addresses the audit trail is sent to, give them new signing secrets, read their delivery log and health, and replay events.監査ログの送信先アドレスを追加・変更・一時停止・再開・テスト・削除し、新しい署名シークレットを発行し、配信ログと状態を読み、イベントを再送します。 |
manage:legal_holds | Manage legal holds訴訟ホールドの管理 admin List legal holds, place people on hold and ask for a hold to be released. A release still waits for an administrator to approve it in the app.訴訟ホールドを一覧し、メンバーをホールドの対象にし、ホールドの解除を申請します。解除は、引き続き別の管理者がアプリで承認するまで保留されます。 |
write:links | Make signed links署名付きリンクの作成 Make short-lived links that carry out one request this key could make itself (a download, or approving or refusing a request) for somebody or something that does not hold the key. Each use is checked against the key again.このキー自身が行えるリクエストを 1 つだけ実行する短時間有効なリンク(ダウンロード、またはリクエストの承認・拒否)を、キーを持たない人やシステムのために作成します。使われるたびに、改めてキーと照合されます。 |
write:tokens | Make short-lived tokens短時間有効なトークンの作成 Exchange this key for a token that works for up to an hour with the key's scopes or fewer, to hand to code trusted less than the key. A token stops when the key is revoked or turned off, and cannot make another token.このキーを、キーと同じかそれより少ないスコープで最長 1 時間使えるトークンに交換し、キーほど信頼できないコードに渡せます。トークンはキーが失効またはオフになると使えなくなり、別のトークンを作ることはできません。 |
manage:secrets | Write vault secrets保管庫のシークレットの書き込み admin Add, replace and remove the named secrets Bots use, and read which Bot used each one. Values can be written but never read back.Bot が使う名前付きシークレットを追加・置き換え・削除し、どの Bot がどれを使ったかを読みます。値は書き込めますが、読み戻すことはできません。 |
manage:boundaries | Manage boundary rules境界ルールの管理 admin Read the boundary, check rules, test a draft against recent actions and propose a new version. A proposal waits for another administrator to approve it in the app.境界を読み、ルールを確認し、下書きを最近の操作に当てはめてテストし、新しいバージョンを提案します。提案は、別の管理者がアプリで承認するまで保留されます。 |
read:package | Check configuration packages構成パッケージの確認 admin Read the package the deployment runs, and check one before it is deployed.デプロイが実行しているパッケージを読み、デプロイ前にパッケージを確認します。 |
admin | Full administrator access管理者のフルアクセス admin Everything the owner can do through the API, including changes. Never the API key screens themselves.所有者が API で行えるすべての操作で、変更も含みます。API キーの画面そのものは対象外です。 |
レート制限このセクションへのリンクをコピー
サーバーは、失敗したキーの試行(キーなし、形式不正、不明、失効済み、期限切れ)を一定の時間枠で数えます。上限を超えると、時間枠が終わるまで Retry-After ヘッダー付きの 429 を返します。
| 1 つのアドレスからの失敗したキー試行(時間枠あたり) | 20 |
|---|---|
| 全アドレス合計の失敗したキー試行(時間枠あたり) | 500 |
| 時間枠の長さ(分) | 10 |
| 1 人が保持できる未失効のキー | 25 |
| 設定できる最長の有効期限(日) | 3650 |
スクリプト向けの決まりごとこのセクションへのリンクをコピー
- 読み取りに成功した応答には
ETagが付きます。If-None-Matchに入れて送ると、変わっていなければ本文なしの304が返ります。PUT・PATCH・DELETEのIf-Matchに入れて送ると、読み取った後に変わっていた場合は412で変更が拒否されます。 ?fields=id,nameを付けると、応答に含まれるもの(リストの各項目、または包まれている 1 つのオブジェクト)のうち、指定したフィールドだけが返ります。?timezone=Asia/TokyoかSynthia-Timezoneヘッダーを付けると、createdAtの横に、そのタイムゾーンでオフセット付きで書いたcreatedAtLocalが加わります(ほかの時刻も同じです)。UTC の時刻も必ず残ります。write:tokensのあるキーは、POST /api/tokensで、そのスコープの一部またはすべてを持ち 1〜60 分有効なトークンと引き換えられます。キーほど信頼できないコードに渡すためのものです。キーが失効または無効になるとトークンも止まり、トークンから別のトークンは作れません。- 丸ごと返す一覧には
?limit=(1〜200)を付けられ、付けると一覧の隣にnextCursorが返ります。次のページは?cursor=にそれを送って取得し、最後のページではnullです。?filter=status=activeは条件に合う項目だけを残します。演算子は=!=>>=<<=と、含むを表す~です。日付は時刻として比べ(createdAt>=2026-10-01)、ドットでオブジェクトの中を指し(owner.id=…)、filter を重ねるとすべてを満たすものだけが残ります。データベースでページ分けする一覧(実行、会話、監査ログ、メンバー、オペレーション)は、それぞれのlimitとcursorを使います。 - 管理者はキーに月間リクエスト上限を設定できます。そのキーの応答には
Synthia-Quota-Limit・Synthia-Quota-Remaining・Synthia-Quota-Resetが付き、80% に達すると所有者に通知され、上限を超えたリクエストには月が変わる(UTC)まで429が返ります。
独自の API ゲートウェイの背後に置くこのセクションへのリンクをコピー
API は、ご自身のゲートウェイやプロキシの背後に置けます。次の点を保てば、スクリプトはゲートウェイがないときとまったく同じように動きます。
- 次のリクエストヘッダーはそのまま渡してください:
Authorization、Idempotency-Key、If-Match、If-None-Match、Synthia-Version、Synthia-Signature、Synthia-Timezone、Accept、Accept-Language、Content-Type、User-Agent。 - 次の応答ヘッダーはそのまま返してください:
X-Request-Id、ETag、RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset、Retry-After、Synthia-Version、Synthia-Quota-で始まるヘッダー、DeprecationとSunset。 - 長い応答をためたり途中で切ったりしないでください。
/api/eventsは WebSocket なので、アップグレードを転送してください。グループでの Bot の返信は、答えている間サーバー送信イベントとして流れます。waitで待つ実行は最大 120 秒かかるため、ゲートウェイの待ち時間は少なくともそれ以上にしてください。 - 本文は 1 バイトも変えずに渡してください。署名は本文そのものに対して計算され、ファイルもバイト列のままアップロードされるため、JSON を書き直したり途中で本文を変えたりしないでください。
- ワークスペースは、キーごとの1分あたりのリクエスト数を自ら数えています。ゲートウェイの上限はそれ以上にするか、同じように 429 と Retry-After で答えてください。アドレスを限定したキーには、ゲートウェイの送信元アドレスが見えるため、そのアドレスを登録してください。
バッチ、ライブイベント、コールバックこのセクションへのリンクをコピー
POST /api/batchで最大 100 件のリクエストを 1 回で送れます。それぞれ同じキーで単独で送ったときと同じように確認・応答されるため、stopOnErrorを指定しない限り、拒否されたものがあっても残りは続きます。async: trueを付けると202とオペレーションが返り、/api/operations/<id>で読み取れます。- キーを付けて
/api/eventsを WebSocket として開くと、メッセージ、実行の状態、承認をその場で受け取れます。キーのスコープで許された種類だけが届きます。 ?events=にtoolを加えると、実行中に Bot が呼び出した各ツールを、その名前と拒否されたかどうかとともにその場で受け取れます。独自のチャット画面を作るためのものです。指定しない接続には届きません。- メッセージにファイルを添えるには、先にそれぞれを会話へアップロードします:
POST /api/channels/<conversation id>/attachments?name=report.pdfに、ファイルのバイト列を本文、種類をContent-Typeとして送ります。返ってきた id を、数時間以内に次のメッセージのattachmentsに指定してください。Bot は人が添付したファイルと同じように読みます。 callbackUrlを付けて実行を始めると、実行が終わったときや人の対応を待つときに、その HTTPS アドレスへ通知されます。通知に含まれるのは実行の ID と状態だけで、返信は含まれません。- すべてのイベントは
/api/asyncapi.jsonに記述されています。操作は Insomnia と Bruno のコレクションとしても/api/openapi/insomnia.jsonと/api/openapi/bruno.jsonで入手できます。
自社サイトにチャットを置くこのセクションへのリンクをコピー
管理者は 設定 › API キー › 埋め込みチャット で埋め込みチャットを設定します。開く Bot、表示を許可するサイト、色、フォント、角の丸み、タイトル、最初のメッセージを指定できます。ページではワークスペースの /embed.js を読み込み、そのスクリプトタグに data-embed と data-token を付けて隅にチャットボタンを置くか、チャットを表示したい場所に <synthia-chat embed="…" token="…"> 要素を置きます。
トークンはサイトにサインインしている人を示すので、その人はもう一度サインインせずに本人としてチャットできます。トークンはサイトのサーバーで作ります。JSON {"sub":"<email>","exp":<unix seconds>} を base64url にしたものに、ドットと、その文字列を埋め込みのシークレットで計算した HMAC-SHA256(base64url)を続けます。有効期間は最大 10 分です。その人はワークスペースのメンバーである必要があります。メッセージは Bot のいつもの承認のもとで実行され、会話はアプリでもその人のものとして残ります。
ブラウザーがチャットを表示するのは、指定したサイトの中だけです。シークレットが表示されるのは一度だけです。新しいシークレットにすると開いているチャットはすべてすぐに終了し、埋め込みをオフにするとどこでも止まります。
レシピこのセクションへのリンクをコピー
ここまでの機能を組み合わせる短い手順です。
- ルーティンの結果をデータウェアハウスへ。
manage:webhooksのキーでroutine.run_finishedの Webhook を登録します。配信にはルーティンが示されるので、read:routinesのキーで/api/routines/<id>/runsからその実行を読み、残したい行を取り込みます。エンドポイントに JSON テンプレートを設定すると、署名はそのままで、ウェアハウス自身の取り込みアドレス向けに配信を組み替えられます。 - 社内ツールから承認する。
approval.requestedを購読し、/api/approvalsから待っている内容を社内ツールに表示し、その人の選択をwrite:approvalsのキーで/api/approvals/<id>/decisionに送ります。監査証跡にはキーの名前とともに記録されます。キーを持たない人には、POST /api/linksでその 1 件の判断を実行するリンクを作れます(最長 1 週間)。 - パイプライン向けの構造化された回答。
output.schemaとwaitを付けてPOST /api/conversationsを送ると、スキーマと照合した JSON が返ります。合わなければ、理由を示す失敗した実行が返ります。CI ジョブからはsynthia askでメッセージを送り、返信を表示できます。 - 社内ポータルのヘルプチャット。社内の質問に答える Bot の埋め込みチャットを設定し、社内ポータルのアドレスを表示を許可するサイトに入れ、上で説明したように社内ポータルのサーバーで各ユーザーのトークンに署名します。
API リファレンスこのセクションへのリンクをコピー
admin 未満のキーで利用できるすべての操作と、必要なスコープです。サインインすると、設定 › API リファレンス で各操作のパラメーター、コピーできる curl・TypeScript・Python のスニペット、試せるコンソールを確認できます。機械可読のドキュメントは、デプロイメントの /api/openapi.json で提供されます。すべてのリクエストとレスポンスのスキーマは完全なリファレンスにあります。
Profileプロフィールこのセクションへのリンクをコピー
| GET | /api/me | The person the key belongs toキーの持ち主 | read:profile |
| GET | /api/integration | API version, build, available features and this key's own settingsAPI のバージョン、ビルド、利用できる機能とこのキー自身の設定 | read:profile |
BotsBotこのセクションへのリンクをコピー
| GET | /api/agents | The Bots the owner can see所有者が見られる Bot | read:bots |
| POST | /api/agents | Create a BotBot を作成 | manage:bots |
| GET | /api/agents/model-options | The models this deployment offers, for a Bot or one runこのデプロイが Bot や 1 回の実行に提供するモデル | read:bots |
| GET | /api/agents/{agentId} | One Bot's profile1 つの Bot のプロフィール | read:bots |
| PATCH | /api/agents/{agentId} | Change a Bot's profileBot のプロフィールを変更 | manage:bots |
| DELETE | /api/agents/{agentId} | Delete a BotBot を削除 | manage:bots |
| GET | /api/agents/{agentId}/history | A Bot's saved versions, newest firstBot の保存された版(新しい順) | manage:bots |
| GET | /api/agents/{agentId}/tests | A Bot's tests and recent runsBot のテストと最近の実行 | manage:bots |
| POST | /api/agents/{agentId}/tests | Save a testテストを保存 | manage:bots |
| DELETE | /api/agents/{agentId}/tests/{testId} | Delete a testテストを削除 | manage:bots |
| POST | /api/agents/{agentId}/tests/run | Run a Bot's tests nowBot のテストを今すぐ実行 | manage:bots |
Conversations会話このセクションへのリンクをコピー
| GET | /api/channels | The owner's conversations, newest first所有者の会話(新しい順) | read:channels |
| GET | /api/channels/{channelId} | One conversation1 つの会話 | read:channels |
| GET | /api/groups/{channelId} | A group conversation and its messagesグループ会話とそのメッセージ | read:channels |
| POST | /api/groups/{channelId} | Send a message into a group conversation, as the owner所有者としてグループ会話にメッセージを送信 | write:messages |
| GET | /api/groups/{channelId}/stream | Watch the Bots' replies arrive, as Server-Sent EventsBot の返信をサーバー送信イベント(SSE)で受け取る | read:channels |
| POST | /api/conversations | Start a conversation with a Bot and send its first messageBot との会話を始めて最初のメッセージを送信 | write:messages |
| POST | /api/conversations/{conversationId}/messages | Send a message in a direct conversation1 対 1 の会話でメッセージを送信 | write:messages |
| POST | /api/channels/{channelId}/attachments | Upload a file into a conversation, to send with a message会話にファイルをアップロード(メッセージに添えるため) | write:messages |
Runs実行このセクションへのリンクをコピー
| GET | /api/runs | The runs the owner started through the API, newest first所有者が API で始めた実行(新しい順) | read:channels |
| GET | /api/runs/{runId} | A run's status, timings, token use and any approval it waits on実行の状態、所要時間、トークン使用量、待っている承認 | read:channels |
| GET | /api/runs/{runId}/wait | Wait for a run to finish実行が終わるのを待つ | read:channels |
| POST | /api/runs/{runId}/cancel | Stop a run, the same as pressing Stop実行を止める(停止ボタンと同じ) | write:messages |
Routinesルーティンこのセクションへのリンクをコピー
| GET | /api/routines | The owner's routines所有者のルーティン | read:routines |
| POST | /api/routines | Create a routineルーティンを作成 | manage:routines |
| GET | /api/routines/{id}/runs | One routine's runs1 つのルーティンの実行 | read:routines |
| POST | /api/routines/{id}/run | Run a routine nowルーティンを今すぐ実行 | write:routines |
| PUT | /api/routines/{id}/instruction | Change what a routine doesルーティンの内容を変更 | manage:routines |
| GET | /api/routines/{id}/schedule | A routine's schedule and its next runルーティンのスケジュールと次の実行 | read:routines |
| PUT | /api/routines/{id}/schedule | Change when a routine runsルーティンの実行時刻を変更 | manage:routines |
| POST | /api/routines/schedule-preview | Check a schedule and see its next runs, without saving anythingスケジュールを確認して次の実行を見る(何も保存しません) | manage:routines |
| PUT | /api/routines/{id}/enabled | Switch a routine on or offルーティンをオンまたはオフにする | manage:routines |
| DELETE | /api/routines/{id} | Delete a routineルーティンを削除 | manage:routines |
Triggersトリガーこのセクションへのリンクをコピー
| GET | /api/routines/{id}/triggers | The event triggers that start a routineルーティンを始めるイベントトリガー | read:routines |
| POST | /api/routines/{id}/triggers | Add a trigger that starts a routineルーティンを始めるトリガーを追加 | manage:routines |
| DELETE | /api/routines/{id}/triggers/{triggerId} | Remove a routine's triggerルーティンのトリガーを削除 | manage:routines |
| GET | /api/responsibilities/{id}/triggers | The event triggers that start a responsibility担当業務を始めるイベントトリガー | read:responsibilities |
| POST | /api/responsibilities/{id}/triggers | Add a trigger that starts a responsibility担当業務を始めるトリガーを追加 | manage:responsibilities |
| PATCH | /api/responsibilities/triggers/{triggerId} | Change a trigger's settingsトリガーの設定を変更 | manage:responsibilities |
| DELETE | /api/responsibilities/triggers/{triggerId} | Remove a triggerトリガーを削除 | manage:responsibilities |
| PUT | /api/responsibilities/triggers/{triggerId}/enabled | Pause or resume a triggerトリガーを一時停止または再開 | manage:responsibilities |
| POST | /api/responsibilities/triggers/{triggerId}/secret | Give a trigger a new signing secretトリガーに新しい署名用シークレットを発行 | manage:responsibilities |
Responsibilities担当業務このセクションへのリンクをコピー
| GET | /api/responsibilities | The owner's responsibilities所有者の担当業務 | read:responsibilities |
| POST | /api/responsibilities | Create a responsibility担当業務を作成 | manage:responsibilities |
| GET | /api/responsibilities/{id} | One responsibility1 つの担当業務 | read:responsibilities |
| PATCH | /api/responsibilities/{id} | Change a responsibility担当業務を変更 | manage:responsibilities |
| GET | /api/responsibilities/{id}/runs | One responsibility's runs1 つの担当業務の実行 | read:responsibilities |
| POST | /api/responsibilities/{id}/pause | Pause a responsibility担当業務を一時停止 | manage:responsibilities |
| POST | /api/responsibilities/{id}/resume | Resume a paused responsibility一時停止した担当業務を再開 | manage:responsibilities |
| POST | /api/responsibilities/{id}/complete | Mark a responsibility complete担当業務を完了にする | manage:responsibilities |
| POST | /api/responsibilities/{id}/run | Run a responsibility now担当業務を今すぐ実行 | manage:responsibilities |
Approvals承認このセクションへのリンクをコピー
| GET | /api/approvals | Approval requests and Bot questions waiting for the owner所有者を待っている承認依頼と Bot の質問 | read:approvals |
| GET | /api/approvals/{id}/context | What the Bot saw and said when it asked依頼したときに Bot が見ていたものと言ったこと | read:approvals |
| POST | /api/approvals/{id}/decision | Approve or refuse one request, as the owner所有者として 1 件の依頼を承認または拒否 | write:approvals |
| POST | /api/approvals/decisions | Approve or refuse several requests for the same action at once同じ操作の複数の依頼をまとめて承認または拒否 | write:approvals |
| POST | /api/approvals/questions/{id}/respond | Answer a Bot's question, so its work can carry onBot の質問に答えて作業を続けさせる | write:approvals |
Memoryメモリーこのセクションへのリンクをコピー
| GET | /api/memory | The memories the owner's Bots keep about them所有者について Bot が覚えているメモリー | read:memory |
| POST | /api/memory | Add a memoryメモリーを追加 | write:memory |
| PATCH | /api/memory/{id} | Edit, switch off or confirm a memoryメモリーを編集、無効化、または確認 | write:memory |
| DELETE | /api/memory/{id} | Forget a memoryメモリーを忘れさせる | write:memory |
MCPMCPこのセクションへのリンクをコピー
| POST | /api/mcp | This workspace as an MCP server (JSON-RPC over HTTP)MCP サーバーとしてのこのワークスペース(HTTP 上の JSON-RPC) | use:mcp |
| POST | /api/mcp/bots/{botId} | One Bot as an MCP serverMCP サーバーとしての 1 つの Bot | use:mcp |
| POST | /api/mcp/audit | The audit trail as an MCP serverMCP サーバーとしての監査証跡 | use:mcp |
| POST | /api/mcp/routines | Routines as an MCP serverMCP サーバーとしてのルーティン | use:mcp |
| POST | /api/mcp/approvals | Approvals as an MCP serverMCP サーバーとしての承認 | use:mcp |
Audit監査このセクションへのリンクをコピー
| GET | /api/audit/stream | Pull the audit trail as NDJSON, oldest first, from a cursorカーソルから古い順に NDJSON で監査証跡を取得 | read:audit |
Tasksタスクこのセクションへのリンクをコピー
| GET | /api/me/tasks | The owner's tasks, open ones first所有者のタスク(未完了が先) | read:tasks |
| POST | /api/me/tasks | Add a task to the owner's list所有者のリストにタスクを追加 | write:tasks |
| GET | /api/me/tasks/export.csv | Every task the owner keeps, as CSV所有者が持つすべてのタスクを CSV で | read:tasks |
| GET | /api/me/tasks/{taskId}/history | Who made a task, what changed and when it was ticked offタスクを作った人、変わった内容、完了した時刻 | read:tasks |
| PATCH | /api/me/tasks/{taskId} | Change a task, or tick it off with done: trueタスクを変更、または done: true で完了にする | write:tasks |
| DELETE | /api/me/tasks/{taskId} | Delete a taskタスクを削除 | write:tasks |
Skillsスキルこのセクションへのリンクをコピー
| GET | /api/plugins/skills | The deployment's skills and the owner's ownデプロイのスキルと所有者自身のスキル | manage:skills |
| POST | /api/plugins/skills | Write a skill, or a new version of oneスキル、またはその新しい版を書く | manage:skills |
| DELETE | /api/plugins/skills/{slug} | Delete a skillスキルを削除 | manage:skills |
| GET | /api/plugins/for/{agentId} | What one Bot has been given: skills, tools and other Bots1 つの Bot に与えられたもの:スキル、ツール、ほかの Bot | manage:skills |
| POST | /api/plugins/grants | Give a skill to a BotBot にスキルを与える | manage:skills |
| DELETE | /api/plugins/grants | Take a skill from a BotBot からスキルを外す | manage:skills |
Filesファイルこのセクションへのリンクをコピー
| POST | /api/computers/{botId}/files/list | List a folder in a Bot's workspaceBot のワークスペースのフォルダーを一覧にする | read:files |
| POST | /api/computers/{botId}/files/read | Read a text fileテキストファイルを読む | read:files |
| POST | /api/computers/{botId}/files/search | Find files by name pattern or by text inside them名前のパターンや中身のテキストでファイルを探す | read:files |
| GET | /api/computers/{botId}/files/download | Download a file as it isファイルをそのままダウンロード | read:files |
| POST | /api/computers/{botId}/files/upload | Upload a file, its bytes as the bodyファイルをアップロード(本文にバイト列) | write:files |
| POST | /api/computers/{botId}/files/write | Write a text file, or add to the end of oneテキストファイルを書く、または末尾に追加する | write:files |
| POST | /api/computers/{botId}/files/mkdir | Make a folderフォルダーを作る | write:files |
| POST | /api/computers/{botId}/files/move | Move or rename a file or folderファイルやフォルダーを移動または名前変更 | write:files |
| POST | /api/computers/{botId}/files/delete | Delete a file or folderファイルやフォルダーを削除 | write:files |
Signed links署名付きリンクこのセクションへのリンクをコピー
| POST | /api/links | Make a short-lived link that carries out one request as this keyこのキーとして 1 件のリクエストを行う、短時間有効なリンクを作る | write:links |
Short-lived tokens短時間有効なトークンこのセクションへのリンクをコピー
| POST | /api/tokens | Exchange this key for a token that works for a few minutesこのキーを数分間使えるトークンに交換 | write:tokens |
Boundaries境界このセクションへのリンクをコピー
| GET | /api/computers/policy | The boundary in force, and rules that can never match有効な境界と、決して一致しないルール | manage:boundaries |
| PUT | /api/computers/policy | Propose a new boundary, for another administrator to approve新しい境界を提案し、別の管理者の承認を待つ | manage:boundaries |
| POST | /api/computers/policy-validate | Check one rule, and where it stops being valid1 つのルールと、それが有効でなくなる箇所を確認 | manage:boundaries |
| POST | /api/computers/policy-dry-run | What a draft boundary would have decided for recent actions下書きの境界が最近の操作に対してどう判断したか | manage:boundaries |
| GET | /api/computers/policy-changes | Proposed boundary changes and what became of them提案された境界の変更とその結果 | manage:boundaries |
Batchバッチこのセクションへのリンクをコピー
| POST | /api/batch | Send up to 100 requests in one call, each answered on its own1 回の呼び出しで最大 100 件のリクエストを送り、それぞれに応答 | read:profile |
| GET | /api/operations | The background operations this person started, newest firstこの人が始めたバックグラウンドの操作(新しい順) | read:profile |
| GET | /api/operations/{id} | One background operation: how far it is, and each result so far1 つのバックグラウンド操作:進み具合とここまでの各結果 | read:profile |
どの言語でもクライアントをこのセクションへのリンクをコピー
/api/openapi.json のドキュメントは OpenAPI 3.1 なので、OpenAPI のクライアント生成ツールで型付きクライアントを作れます。ご自身のデプロイから、サインインした状態か、キーを Bearer トークンとして付けてダウンロードし(公開はしていません)、使う言語の生成ツールにかけ、キーを Bearer トークンとしてクライアントに渡してください。
/api/openapi/changelog.json の一覧に変更が載ったら生成し直してください。TypeScript SDK もこの同じドキュメントから生成されています。
ターミナルからこのセクションへのリンクをコピー
synthia コマンドラインを使うと、API と同じ名前付きキーで、ターミナルや CI ジョブからデプロイを操作できます。1 つのファイルで動き、Node.js 18 以降が必要です。ご自身のデプロイからインストールし、デプロイとキーを保存してください。
curl -fsSL https://<your-deployment>/developers/cli/install.sh | sh
synthia login --url https://<your-deployment>
synthia doctorsynthia ask と synthia chat は Bot やグループ会話にメッセージを送り、返信を届いたそばから表示します。bots、routines、skills pull / skills push はキーのスコープで許される範囲で管理を行い、audit export は監査ログを JSON Lines で書き出します。どのコマンドも --json に対応し、--profile で複数のデプロイを使い分けられます。
CI では、ログインする代わりにジョブの環境変数に synthia_key と synthia_url を設定してください。synthia doctor はアドレス、キー、API のバージョン、時計を確認し、どれかに問題があるとエラーで終了します。
synthia agent new <フォルダー> は依存関係のない外部エージェントのひな形を書き出します。モデルをつなぐだけで使えます。synthia agent check で、ワークスペースが前提とするプロトコルのチェックをそのエージェントに対して実行できます。
synthia loadtest <bot> は、人が使い始める前にデプロイの規模を見積もります。1 つの Bot との会話を同時に多数始め(--conversations、--concurrency、--messages)、返信時間の中央値・90 パーセンタイル・99 パーセンタイル、キューで待った時間、トークン、失敗を報告し、失敗が --max-failures パーセントを超えるとエラーで終了します。どのメッセージも、使用量に計上される実際のターンです。
MCPクライアントからこのセクションへのリンクをコピー
デスクトップアシスタントやコードエディターは、use:mcp スコープを持つキーをBearerトークンにしてMCPで接続します。/api/mcp はワークスペース全体、/api/mcp/bots/<Bot ID> は1つのBotだけ(ほかのBotには一切アクセスしません)、/api/mcp/audit は監査ログへの質問、/api/mcp/routines はルーティンの一覧・実行・一時停止、/api/mcp/approvals はあなたを待っている承認の一覧と、承認カードと同じ選択肢での判断を扱います。
使えるツールは、キーのほかのスコープで許可されたものだけです。read:files があればBotのワークスペースのファイルがリソースに、manage:skills があればスキルがプロンプトになります。設定 > APIキーに、各アドレスとコピーできる設定があります。
管理者は、接続時に名乗る名前で、接続できる MCP クライアントを 管理 › APIキー に登録できます。それ以外のクライアントは拒否され、拒否は監査ログに記録されます。
人の代わりに動くアプリこのセクションへのリンクをコピー
アプリに長期間有効なキーを渡す代わりに、設定 › API キー › あなたのアプリ でアプリを登録してください。サーバーアプリはクライアントシークレットを持ち、grant_type=client_credentials で /api/oauth/token から 1 時間有効なトークンを受け取ります。トークンは選んだスコープの範囲で、あなたとして動きます。
ほかの人がサインインするアプリは、client_id、redirect_uri、scope、state と PKCE の code_challenge(S256)を付けて /settings/authorize-app に案内します。許可されたら、同じトークンのアドレスで code_verifier と一緒にコードを交換してください。リフレッシュトークンは使うたびに変わります。管理者が許可リストに追加するまで、承認できるのはあなただけです。
MCP クライアントはこれを自動で見つけます。/api/mcp はトークンのないリクエストにサインイン先を返し、/.well-known/oauth-authorization-server がサインインの方法を示し、クライアントは /api/oauth/register で自身を登録します。承認したアプリは 承認したアプリ に一覧され、アクセスはいつでもすぐに取り消せます。
ガイドこのセクションへのリンクをコピー
最終更新日