Call your workspace from code
A REST API for your own deployment, reached with a named API key. The reference on this page is generated from the same OpenAPI document the server serves.
Authentication with named keysCopy link to this section
Create a key under Settings › API keys in the workspace. Give it a name, choose its scopes and, if you like, an expiry. The key starts with obk_ and is shown once. Send it on every request:
curl -H "Authorization: Bearer $api_key" \
https://<your-deployment>/api/meA key acts as the person who created it, never more: their current role and access are checked on every request. No key can create or revoke keys. A key with the admin scope reaches every route its administrator owner could, including ones not listed below.
ScopesCopy link to this section
Each key carries only the scopes chosen when it was made. A scope marked for administrators does nothing on a key whose owner is no longer an administrator.
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 キーの画面そのものは対象外です。 |
Rate limitsCopy link to this section
The server counts failed key attempts (a missing, malformed, unknown, revoked or expired key) over a fixed window. Past the limit it answers 429 with a Retry-After header until the window ends.
| Failed key attempts from one address, per window | 20 |
|---|---|
| Failed key attempts from all addresses together, per window | 500 |
| Window length, in minutes | 10 |
| Unrevoked keys one person may hold | 25 |
| Longest expiry a key can be given, in days | 3650 |
Conventions for scriptsCopy link to this section
- A successful read carries an
ETag. Send it back inIf-None-Matchto get304with no body when nothing changed, or inIf-Matchon aPUT,PATCHorDELETEso the change is refused with412if it changed since you read it. ?fields=id,namekeeps only the named fields of what the answer carries: each item of its list, or the one object it wraps.?timezone=Asia/Tokyo, or aSynthia-Timezoneheader, addscreatedAtLocalbesidecreatedAt(and the same for every other time), written in that zone with its offset. The UTC time is always there too.- A key with
write:tokenscan be exchanged atPOST /api/tokensfor a token that works for 1 to 60 minutes with some or all of its scopes, to hand to code you trust less than the key. The token stops when the key is revoked or turned off, and cannot make another token. - A list that answers whole takes
?limit=(1 to 200) and then answersnextCursorbeside the list: send it back as?cursor=for the next page; it isnullon the last.?filter=status=activekeeps the items that match, with=!=>>=<<=and~for contains; dates compare as moments (createdAt>=2026-10-01), dots reach into an object (owner.id=…), and repeated filters must all hold. Lists that page in the database (runs, conversations, the audit trail, people, operations) keep their ownlimitandcursor. - An administrator can give a key a monthly request quota. Its answers then carry
Synthia-Quota-Limit,Synthia-Quota-RemainingandSynthia-Quota-Reset; its owner is told at 80%, and requests past it are answered429until the month turns (UTC).
Behind your own API gatewayCopy link to this section
You can put the API behind a gateway or proxy of your own. Keep these intact and scripts behave exactly as they do without it:
- Pass these request headers through unchanged:
Authorization,Idempotency-Key,If-Match,If-None-Match,Synthia-Version,Synthia-Signature,Synthia-Timezone,Accept,Accept-Language,Content-TypeandUser-Agent. - Pass these answer headers back:
X-Request-Id,ETag,RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset,Retry-After,Synthia-Version, theSynthia-Quota-headers, andDeprecationandSunset. - Do not buffer or cut long answers.
/api/eventsis a WebSocket, so forward the upgrade; a Bot's replies in a group stream as server-sent events while it answers; and a run waited on withwaitcan take up to 120 seconds, so let the gateway wait at least that long. - Keep bodies byte for byte. A signature covers the exact body and a file is uploaded as its own bytes, so do not re-encode JSON or change the body on the way.
- The workspace counts each key's requests a minute itself. Give the gateway a limit at least as generous, or answer 429 with Retry-After the same way. A key limited to named addresses sees the gateway's outgoing address, so name that one.
Batches, live events and callbacksCopy link to this section
POST /api/batchsends up to 100 requests in one call. Each is checked and answered as if sent alone, with the same key, so one that is refused does not stop the rest unless you setstopOnError. Withasync: truethe call answers202with an operation to read at/api/operations/<id>.- Open
/api/eventsas a WebSocket with your key to hear messages, run status and approvals as they happen. A key hears only the kinds its scopes allow. - Add
toolto?events=to hear each tool a Bot calls during one of your runs as it happens, with its name and whether it was refused, for a chat screen of your own. A connection that does not ask for it never receives it. - To send files with a message, upload each into the conversation first:
POST /api/channels/<conversation id>/attachments?name=report.pdfwith the file's bytes as the body and its type asContent-Type. Name the ids it answers inattachmentswith the next message, within a few hours; the Bot reads them as it reads files a person attaches. - Start a run with
callbackUrland that HTTPS address is told when the run finishes or waits for a person. The call carries the run's id and status, never the reply. - Every event is described in
/api/asyncapi.json. The operations also come as Insomnia and Bruno collections at/api/openapi/insomnia.jsonand/api/openapi/bruno.json.
A chat on your own siteCopy link to this section
An administrator sets up an embedded chat under Settings › API keys › Embedded chats: the Bot it opens, the sites allowed to show it, and its colour, font, corner radius, title and first message. A page loads /embed.js from your workspace and either adds data-embed and data-token to that script tag for a chat button in a corner, or places a <synthia-chat embed="…" token="…"> element where the chat should appear.
The token names the person signed in to your site, so they chat as themselves without signing in again. Your server makes it: the JSON {"sub":"<email>","exp":<unix seconds>} in base64url, a dot, and the HMAC-SHA256 of that text with the embed's secret, in base64url. It may live at most ten minutes. The person must be a member of the workspace; their messages run with the Bot's usual approvals, and the conversation is theirs in the app too.
A browser shows the chat only inside the sites you listed. The secret is shown once; a new one ends every open chat at once, and switching the embed off stops it everywhere.
RecipesCopy link to this section
Short ways to put the pieces above together.
- Routine results into a data warehouse. Register a webhook for
routine.run_finishedwith amanage:webhookskey. The delivery names the routine; read its runs at/api/routines/<id>/runswith aread:routineskey and load the rows you keep. A JSON template on the endpoint reshapes the delivery for a warehouse's own ingest address, still signed. - Approving from an internal tool. Subscribe to
approval.requested, show what is waiting in your tool from/api/approvals, and send the person's choice to/api/approvals/<id>/decisionwith awrite:approvalskey; the audit trail records it with the key's name. For somebody without a key,POST /api/linksmakes a link that carries out that one decision, for up to a week. - Structured answers for a pipeline.
POST /api/conversationswithoutput.schemaandwaitanswers with JSON checked against your schema, or a failed run that says why. From a CI job,synthia asksends the message and prints the reply. - A help chat on the intranet. Set up an embedded chat for the Bot that answers internal questions, list the intranet's address as its site, and have the intranet's server sign each person's token, as described above.
API referenceCopy link to this section
Every operation a key below admin can reach, and the scope it needs. Signed in, Settings › API reference shows each operation's parameters, copyable curl, TypeScript and Python snippets, and a console to try it. Your deployment serves the machine-readable document at /api/openapi.json. The full reference shows every request and response schema.
ProfileプロフィールCopy link to this section
| 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 |
BotsBotCopy link to this section
| 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会話Copy link to this section
| 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実行Copy link to this section
| 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ルーティンCopy link to this section
| 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トリガーCopy link to this section
| 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担当業務Copy link to this section
| 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承認Copy link to this section
| 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メモリーCopy link to this section
| 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 |
MCPMCPCopy link to this section
| 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監査Copy link to this section
| GET | /api/audit/stream | Pull the audit trail as NDJSON, oldest first, from a cursorカーソルから古い順に NDJSON で監査証跡を取得 | read:audit |
TasksタスクCopy link to this section
| 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スキルCopy link to this section
| 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ファイルCopy link to this section
| 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署名付きリンクCopy link to this section
| POST | /api/links | Make a short-lived link that carries out one request as this keyこのキーとして 1 件のリクエストを行う、短時間有効なリンクを作る | write:links |
Short-lived tokens短時間有効なトークンCopy link to this section
| POST | /api/tokens | Exchange this key for a token that works for a few minutesこのキーを数分間使えるトークンに交換 | write:tokens |
Boundaries境界Copy link to this section
| 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バッチCopy link to this section
| 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 |
A client in any languageCopy link to this section
The document at /api/openapi.json is OpenAPI 3.1, so any OpenAPI client generator can build a typed client from it. Download it from your own deployment, signed in or with your key as a bearer token (it is not public), run your language's generator on the file, and give the client your key as a bearer token.
Regenerate when the /api/openapi/changelog.json list names a change. The TypeScript SDK is generated from this same document.
From the terminalCopy link to this section
The synthia command line works with your deployment from a terminal or a CI job, with the same named keys as the API. It is one file and needs Node.js 18 or later. Install it from your own deployment, then save the deployment and a key:
curl -fsSL https://<your-deployment>/developers/cli/install.sh | sh
synthia login --url https://<your-deployment>
synthia doctorsynthia ask and synthia chat send a message to a Bot or a group conversation and print the replies as they arrive. bots, routines and skills pull / skills push manage what the key's scopes allow, and audit export writes the audit trail as JSON lines. Every command takes --json; keep several deployments with --profile.
In CI, set synthia_key and synthia_url in the job's environment instead of logging in. synthia doctor checks the address, the key, the API version and the clock, and exits with an error when one of them is wrong.
synthia agent new <folder> writes a starter external agent with no dependencies, ready for your model; synthia agent check runs the protocol checks the workspace relies on against it.
synthia loadtest <bot> sizes a deployment before people rely on it: it starts many conversations with one Bot at once (--conversations, --concurrency, --messages) and reports reply times at the median, 90th and 99th percentile, the time spent queued, tokens and failures, exiting with an error past --max-failures percent. Every message is a real, metered turn.
From an MCP clientCopy link to this section
Desktop assistants and code editors connect over MCP with a key that has the use:mcp scope as a bearer token. /api/mcp serves the whole workspace; /api/mcp/bots/<bot id> serves one Bot and nothing of any other; /api/mcp/audit answers questions about the audit trail; /api/mcp/routines lists, runs and pauses routines; /api/mcp/approvals lists the approvals waiting for you and decides them with the approval card's choices.
The tools offered are the ones the key's other scopes allow. With read:files, a Bot's workspace files are resources; with manage:skills, skills are prompts. Settings > API keys lists each address with settings to copy.
An administrator can list the MCP clients that may connect, by the name each gives when it connects, under Admin › API keys. Any other client is refused, and the refusal is recorded in the audit trail.
Apps that act for peopleCopy link to this section
Register an app under Settings › API keys › Your apps instead of handing it a long-lived key. A server app holds a client secret and gets hour-long tokens from /api/oauth/token with grant_type=client_credentials; they act as you, with the scopes you chose.
An app other people sign in to sends them to /settings/authorize-app with client_id, redirect_uri, scope, state and a PKCE code_challenge (S256). Once they allow it, exchange the code at the same token address with the code_verifier; refresh tokens change on every use. Until an administrator puts the app on the allow-list, only you can authorise it.
MCP clients find all of this on their own: /api/mcp answers a request without a token with where to sign in, /.well-known/oauth-authorization-server describes the sign-in, and a client registers itself at /api/oauth/register. People see every app they authorised under Apps you authorised and can take its access away at once.
GuidesCopy link to this section
Last updated