Developers

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/me

A 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:profileRead your profileプロフィールの読み取り
Who the key belongs to and their role.キーの持ち主とそのロールです。
read:botsRead BotsBot の読み取り
The Bots the owner can see, and each one's profile.所有者が見られる Bot と、それぞれのプロフィールです。
read:channelsRead conversations会話の読み取り
The owner's conversations, and the messages in their group conversations.所有者の会話と、所有者が参加しているグループ会話のメッセージです。
write:messagesSend messagesメッセージの送信
Post a message into a group conversation the owner belongs to, as the owner.所有者が参加しているグループ会話に、所有者としてメッセージを投稿します。
read:routinesRead routinesルーティンの読み取り
The owner's routines and their run history.所有者のルーティンと、その実行履歴です。
write:routinesRun routinesルーティンの実行
Start one of the owner's routines now. This does real work, exactly as a scheduled run would.所有者のルーティンをいますぐ 1 つ開始します。予定どおりの実行とまったく同じく、実際の作業を行います。
manage:routinesCreate 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:approvalsRead approvals承認の読み取り
The approval requests and Bot questions waiting for the owner, and what the Bot saw when it asked.所有者を待っている承認リクエストと Bot からの質問、そして Bot が質問したときに見ていた内容です。
write:approvalsAnswer 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:responsibilitiesRead responsibilities担当業務の読み取り
The owner's lasting goals, their runs and progress, and their triggers.所有者の継続的な目標、その実行と進捗、トリガーです。
manage:responsibilitiesManage responsibilities担当業務の管理
Create, change, pause, resume, complete and run the owner's responsibilities, and manage their triggers, including new signing secrets.所有者の担当業務を作成・変更・一時停止・再開・完了・実行し、新しい署名シークレットを含むトリガーを管理します。
read:memoryRead memoryメモリーの読み取り
The memories the owner's Bots keep about them.所有者の Bot が所有者について覚えているメモリーです。
write:memoryChange memoryメモリーの変更
Add, edit, switch off and forget the memories the owner's Bots keep about them.所有者の Bot が所有者について覚えているメモリーを追加・編集・オフにし、忘れさせます。
read:tasksRead tasksタスクの読み取り
The owner's own task list, one task's history, and the list as a spreadsheet.所有者自身のタスク一覧、1 つのタスクの履歴、スプレッドシート形式の一覧です。
write:tasksChange tasksタスクの変更
Add, change, tick off and delete the owner's own tasks, as the owner.所有者として、所有者自身のタスクを追加・変更・完了・削除します。
read:usageRead usage and cost使用量とコストの読み取り
Token use and estimated cost by Bot, model and day. The owner must be allowed to view usage.Bot・モデル・日ごとのトークン使用量と推定コストです。所有者に使用量の閲覧が許可されている必要があります。
manage:botsCreate 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:skillsManage skillsスキルの管理
List, write and delete the owner's skills, and give skills to or take them from Bots the owner may change.所有者のスキルを一覧・作成・削除し、所有者が変更できる Bot にスキルを付与したり外したりします。
read:filesRead 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:filesChange 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:mcpConnect 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:analyticsRead 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:auditRead the audit trail監査ログの読み取り admin
Search and export the deployment's audit trail.デプロイの監査ログを検索し、書き出します。
read:peopleRead peopleメンバーの読み取り admin
Everybody on the deployment, their role and access.デプロイの全員と、そのロールとアクセス権です。
manage:peopleManage peopleメンバーの管理 admin
Invitations, roles, suspensions and groups. Never makes an administrator.招待、ロール、利用停止、グループです。管理者を作ることはありません。
manage:webhooksManage 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_holdsManage 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:linksMake 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:tokensMake 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:secretsWrite 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:boundariesManage 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:packageCheck configuration packages構成パッケージの確認 admin
Read the package the deployment runs, and check one before it is deployed.デプロイが実行しているパッケージを読み、デプロイ前にパッケージを確認します。
adminFull 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 window20
Failed key attempts from all addresses together, per window500
Window length, in minutes10
Unrevoked keys one person may hold25
Longest expiry a key can be given, in days3650

Conventions for scriptsCopy link to this section

  • A successful read carries an ETag. Send it back in If-None-Match to get 304 with no body when nothing changed, or in If-Match on a PUT, PATCH or DELETE so the change is refused with 412 if it changed since you read it.
  • ?fields=id,name keeps only the named fields of what the answer carries: each item of its list, or the one object it wraps.
  • ?timezone=Asia/Tokyo, or a Synthia-Timezone header, adds createdAtLocal beside createdAt (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:tokens can be exchanged at POST /api/tokens for 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 answers nextCursor beside the list: send it back as ?cursor= for the next page; it is null on the last. ?filter=status=active keeps 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 own limit and cursor.
  • An administrator can give a key a monthly request quota. Its answers then carry Synthia-Quota-Limit, Synthia-Quota-Remaining and Synthia-Quota-Reset; its owner is told at 80%, and requests past it are answered 429 until 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-Type and User-Agent.
  • Pass these answer headers back: X-Request-Id, ETag, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After, Synthia-Version, the Synthia-Quota- headers, and Deprecation and Sunset.
  • Do not buffer or cut long answers. /api/events is 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 with wait can 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/batch sends 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 set stopOnError. With async: true the call answers 202 with an operation to read at /api/operations/<id>.
  • Open /api/events as 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 tool to ?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.pdf with the file's bytes as the body and its type as Content-Type. Name the ids it answers in attachments with the next message, within a few hours; the Bot reads them as it reads files a person attaches.
  • Start a run with callbackUrl and 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.json and /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_finished with a manage:webhooks key. The delivery names the routine; read its runs at /api/routines/<id>/runs with a read:routines key 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>/decision with a write:approvals key; the audit trail records it with the key's name. For somebody without a key, POST /api/links makes a link that carries out that one decision, for up to a week.
  • Structured answers for a pipeline. POST /api/conversations with output.schema and wait answers with JSON checked against your schema, or a failed run that says why. From a CI job, synthia ask sends 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/meThe person the key belongs toキーの持ち主read:profile
GET/api/integrationAPI version, build, available features and this key's own settingsAPI のバージョン、ビルド、利用できる機能とこのキー自身の設定read:profile

BotsBotCopy link to this section

GET/api/agentsThe Bots the owner can see所有者が見られる Botread:bots
POST/api/agentsCreate a BotBot を作成manage:bots
GET/api/agents/model-optionsThe 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}/historyA Bot's saved versions, newest firstBot の保存された版(新しい順)manage:bots
GET/api/agents/{agentId}/testsA Bot's tests and recent runsBot のテストと最近の実行manage:bots
POST/api/agents/{agentId}/testsSave a testテストを保存manage:bots
DELETE/api/agents/{agentId}/tests/{testId}Delete a testテストを削除manage:bots
POST/api/agents/{agentId}/tests/runRun a Bot's tests nowBot のテストを今すぐ実行manage:bots

Conversations会話Copy link to this section

GET/api/channelsThe 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}/streamWatch the Bots' replies arrive, as Server-Sent EventsBot の返信をサーバー送信イベント(SSE)で受け取るread:channels
POST/api/conversationsStart a conversation with a Bot and send its first messageBot との会話を始めて最初のメッセージを送信write:messages
POST/api/conversations/{conversationId}/messagesSend a message in a direct conversation1 対 1 の会話でメッセージを送信write:messages
POST/api/channels/{channelId}/attachmentsUpload a file into a conversation, to send with a message会話にファイルをアップロード(メッセージに添えるため)write:messages

Runs実行Copy link to this section

GET/api/runsThe 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}/waitWait for a run to finish実行が終わるのを待つread:channels
POST/api/runs/{runId}/cancelStop a run, the same as pressing Stop実行を止める(停止ボタンと同じ)write:messages

RoutinesルーティンCopy link to this section

GET/api/routinesThe owner's routines所有者のルーティンread:routines
POST/api/routinesCreate a routineルーティンを作成manage:routines
GET/api/routines/{id}/runsOne routine's runs1 つのルーティンの実行read:routines
POST/api/routines/{id}/runRun a routine nowルーティンを今すぐ実行write:routines
PUT/api/routines/{id}/instructionChange what a routine doesルーティンの内容を変更manage:routines
GET/api/routines/{id}/scheduleA routine's schedule and its next runルーティンのスケジュールと次の実行read:routines
PUT/api/routines/{id}/scheduleChange when a routine runsルーティンの実行時刻を変更manage:routines
POST/api/routines/schedule-previewCheck a schedule and see its next runs, without saving anythingスケジュールを確認して次の実行を見る(何も保存しません)manage:routines
PUT/api/routines/{id}/enabledSwitch 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}/triggersThe event triggers that start a routineルーティンを始めるイベントトリガーread:routines
POST/api/routines/{id}/triggersAdd 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}/triggersThe event triggers that start a responsibility担当業務を始めるイベントトリガーread:responsibilities
POST/api/responsibilities/{id}/triggersAdd 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}/enabledPause or resume a triggerトリガーを一時停止または再開manage:responsibilities
POST/api/responsibilities/triggers/{triggerId}/secretGive a trigger a new signing secretトリガーに新しい署名用シークレットを発行manage:responsibilities

Responsibilities担当業務Copy link to this section

GET/api/responsibilitiesThe owner's responsibilities所有者の担当業務read:responsibilities
POST/api/responsibilitiesCreate 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}/runsOne responsibility's runs1 つの担当業務の実行read:responsibilities
POST/api/responsibilities/{id}/pausePause a responsibility担当業務を一時停止manage:responsibilities
POST/api/responsibilities/{id}/resumeResume a paused responsibility一時停止した担当業務を再開manage:responsibilities
POST/api/responsibilities/{id}/completeMark a responsibility complete担当業務を完了にするmanage:responsibilities
POST/api/responsibilities/{id}/runRun a responsibility now担当業務を今すぐ実行manage:responsibilities

Approvals承認Copy link to this section

GET/api/approvalsApproval requests and Bot questions waiting for the owner所有者を待っている承認依頼と Bot の質問read:approvals
GET/api/approvals/{id}/contextWhat the Bot saw and said when it asked依頼したときに Bot が見ていたものと言ったことread:approvals
POST/api/approvals/{id}/decisionApprove or refuse one request, as the owner所有者として 1 件の依頼を承認または拒否write:approvals
POST/api/approvals/decisionsApprove or refuse several requests for the same action at once同じ操作の複数の依頼をまとめて承認または拒否write:approvals
POST/api/approvals/questions/{id}/respondAnswer a Bot's question, so its work can carry onBot の質問に答えて作業を続けさせるwrite:approvals

MemoryメモリーCopy link to this section

GET/api/memoryThe memories the owner's Bots keep about them所有者について Bot が覚えているメモリーread:memory
POST/api/memoryAdd 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/mcpThis 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 つの Botuse:mcp
POST/api/mcp/auditThe audit trail as an MCP serverMCP サーバーとしての監査証跡use:mcp
POST/api/mcp/routinesRoutines as an MCP serverMCP サーバーとしてのルーティンuse:mcp
POST/api/mcp/approvalsApprovals as an MCP serverMCP サーバーとしての承認use:mcp

Audit監査Copy link to this section

GET/api/audit/streamPull the audit trail as NDJSON, oldest first, from a cursorカーソルから古い順に NDJSON で監査証跡を取得read:audit

TasksタスクCopy link to this section

GET/api/me/tasksThe owner's tasks, open ones first所有者のタスク(未完了が先)read:tasks
POST/api/me/tasksAdd a task to the owner's list所有者のリストにタスクを追加write:tasks
GET/api/me/tasks/export.csvEvery task the owner keeps, as CSV所有者が持つすべてのタスクを CSV でread:tasks
GET/api/me/tasks/{taskId}/historyWho 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/skillsThe deployment's skills and the owner's ownデプロイのスキルと所有者自身のスキルmanage:skills
POST/api/plugins/skillsWrite 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 に与えられたもの:スキル、ツール、ほかの Botmanage:skills
POST/api/plugins/grantsGive a skill to a BotBot にスキルを与えるmanage:skills
DELETE/api/plugins/grantsTake a skill from a BotBot からスキルを外すmanage:skills

FilesファイルCopy link to this section

POST/api/computers/{botId}/files/listList a folder in a Bot's workspaceBot のワークスペースのフォルダーを一覧にするread:files
POST/api/computers/{botId}/files/readRead a text fileテキストファイルを読むread:files
POST/api/computers/{botId}/files/searchFind files by name pattern or by text inside them名前のパターンや中身のテキストでファイルを探すread:files
GET/api/computers/{botId}/files/downloadDownload a file as it isファイルをそのままダウンロードread:files
POST/api/computers/{botId}/files/uploadUpload a file, its bytes as the bodyファイルをアップロード(本文にバイト列)write:files
POST/api/computers/{botId}/files/writeWrite a text file, or add to the end of oneテキストファイルを書く、または末尾に追加するwrite:files
POST/api/computers/{botId}/files/mkdirMake a folderフォルダーを作るwrite:files
POST/api/computers/{botId}/files/moveMove or rename a file or folderファイルやフォルダーを移動または名前変更write:files
POST/api/computers/{botId}/files/deleteDelete a file or folderファイルやフォルダーを削除write:files

Short-lived tokens短時間有効なトークンCopy link to this section

POST/api/tokensExchange this key for a token that works for a few minutesこのキーを数分間使えるトークンに交換write:tokens

Boundaries境界Copy link to this section

GET/api/computers/policyThe boundary in force, and rules that can never match有効な境界と、決して一致しないルールmanage:boundaries
PUT/api/computers/policyPropose a new boundary, for another administrator to approve新しい境界を提案し、別の管理者の承認を待つmanage:boundaries
POST/api/computers/policy-validateCheck one rule, and where it stops being valid1 つのルールと、それが有効でなくなる箇所を確認manage:boundaries
POST/api/computers/policy-dry-runWhat a draft boundary would have decided for recent actions下書きの境界が最近の操作に対してどう判断したかmanage:boundaries
GET/api/computers/policy-changesProposed boundary changes and what became of them提案された境界の変更とその結果manage:boundaries

BatchバッチCopy link to this section

POST/api/batchSend up to 100 requests in one call, each answered on its own1 回の呼び出しで最大 100 件のリクエストを送り、それぞれに応答read:profile
GET/api/operationsThe 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 doctor

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

Last updated