Create a toolbox — also the stamping endpoint
/toolbox
Requires `toolbox:create`. Two ways to build one, combinable: pass `template_id` to STAMP it — copies that template's entries once, at creation time, never a live link; requires `use` access to the template — with `connection_map` (connector_slug -> connection_id) filling each stamped proxy entry's connector from one of the caller's own usable connections (the caller becomes that entry's delegator); a connector `connection_map` does not name is left `connection_id: null` ("needs connection") rather than rejected. And/or pass `entries` for hand-written ones beyond whatever stamping copied, validated the same way `PATCH /toolbox/{id}` validates them. `name` defaults to the template's name when stamping and is otherwise required. `shares` grants access at creation time and additionally needs `toolbox:share`; sharing DELEGATES (§6), which is what the response's `delegation` summary discloses — always present, not only when `shares` was sent, because the console opens "Manage access" straight off the row it just created and the disclosure has to be readable BEFORE that first grant.
Request Body
connector_slug -> connection_id (conn_…), filling stamped proxy entries. Ignored when template_id is absent.
Pin this entry to one connection (conn_…) the ACTING EDITOR can use — they become its delegator (docs/access-model.md §6). null = "needs connection." On PATCH /toolbox/{id}, an incoming entry whose (connection_id, tool_name) pair matches a pre-existing row keeps that row's original delegator rather than re-stamping the caller (the carry-forward rule) — only genuinely new pairs get the usability check and the caller's own stamp.
Connector slug — connectors are keyed by slug, not by id.
Arguments pinned by the author. Unlike overrides.defaults, a caller cannot change these.
Optional identity hint (tbxe_… on a toolbox, tple_… on a template): the id of a row this resource already has. On PATCH /toolbox/{id} and PATCH /template/{id} a row echoed back with its own id keeps it, so a client that keys per-row state by entry id (a switch mid-save) is not orphaned by the replacement. It is a hint, never an assertion: an id that is not one of THIS resource's current rows, is repeated, or would put the row out of stored order (rows list in id order) is ignored and the row gets a fresh id — and so is a value that is not a usable string (not a string, or over 200 characters). Never a 400, and never adopted from another resource. Omit it for a new row. Ignored on create.
How the tool is presented to the model. Each key REPLACES the derived value.
4 properties
Default argument values the caller may still override.
Must be a JSON Schema object with "type": "object". Replaces the derived schema entirely.
Required for synthetic entries (syn_…).
Exact tool name from GET /connector/{slug}/tools.
Defaults to proxy.
proxysynthetic
Required unless template_id is set, where it defaults to the template's own name.
Grants to create alongside the resource. Omit, or send [], for a private one. A non-empty array additionally needs <resource>:share.
User id (usr_…) or team id (team_…). Omit or send null for grantee_type: "org".
user and team grants target one grantee_id; org applies to every member of the organization and takes no id.
userteamorg
Same ladder for every shareable resource, low to high. view — see it exists, read its metadata/config; cannot exercise it. use — view + exercise it, resource-specific: run tools through a connection; execute a toolbox's tools through its bound connections (this DELEGATES — the caller runs through each entry's pinning editor's own authority, not necessarily their own); stamp a new toolbox by copying a template's entries; create connections from a connector. edit — use + change its settings, entries and its own grants.
viewuseedit
Markdown guidance on how to use these tools well. Trimmed, then capped at 10,000 Unicode code points (an emoji counts once) — longer is a 400 naming the limit, never a silent cut. null or an empty string clears it; omit the key to leave it unchanged. The resource's description is the one-line "when to use this" shown beside it, so write that too. Moderated like the description. When stamping, omitting it copies the template's skill (and skill_origin_template_id names the template); sending it — a string, or null for none — wins.
Template id (tpl_…) to stamp from. Requires use access to it.
Response Body
The caller's access: owner, or a granted view/use/edit level. Always owner for a dynamic row. Never oversight — toolboxes have no org-wide oversight fallback.
Present on a GET /toolbox stored row exactly when that row's can_see_shares is true — the caller owns it, holds edit, or administers a team it is granted to. Absent from dynamic rows, and deliberately absent for a view/use grantee: the grantee set, counts included, is information about colleagues (docs/access-model.md §8). Read can_see_shares to distinguish "not permitted" from "not carried"; never infer it from this field's absence.
Level of the org-wide grant, or null when there is none.
viewuseeditnull
At most 5 grantees, broadest first (org, then teams, then members), for a hover preview.
4 properties
userteamorg
viewuseedit
Display name; null for org grants and for grantees no longer in the org.
Every grant, the org-wide one included.
How the CALLER reaches this toolbox — not who else can. owner — they own it. direct — a grant naming them personally. team — a grant to a team they belong to (or, per §6.2, one they administer), named in access_via_team. org — an organization-wide grant. When several sources apply the BROADEST wins and the caller's access level is not consulted: owner, else org, else team, else direct. So a caller granted edit personally AND view org-wide reads org — a narrower grant must never mask org-wide exposure, since this field says how far the toolbox reaches, not what the caller may do with it. Deliberately NOT gated on can_see_shares, and deliberately not a widening of it: this is the caller's OWN grant and their OWN team memberships, so a view/use grantee receives it while the grantee list — information about colleagues — stays closed to them. No other member is ever named. ABSENT when nothing reaches the caller — a transfer answering the ex-owner of a resource that was never shared, or a catalog row browsed with no grant behind it. Absent means "no source to name", never "not permitted", and never an implied org.
ownerdirectteamorg
Present exactly when access_via is team, absent otherwise. The team the caller reaches this toolbox through — one of their own teams, never a disclosure about anybody else.
Team id (team_…).
Team display name, or null when the team no longer resolves in the directory — the same null contract every resolved grantee name carries.
Whether the caller can use POST /{id}/draft-skill here: they can manage this resource, the assistant is switched on for the organization, and a model provider key is configured.
Whether the caller may edit this toolbox's own settings — owner, or edit access. No toolbox:manage fallback. Mirrors PATCH /toolbox/{id}.
can_share, verbatim — a THIRD formula, distinct from can_manage: an edit grantee whose role omits toolbox:share can edit the toolbox but was never meant to grant or revoke someone else's access to it. Mirrors DELETE /toolbox/{id}/share/{aclId}.
Whether the caller may share this toolbox — owner, edit access, or toolbox:share. No toolbox:manage fallback. Mirrors POST /toolbox/{id}/share's own check.
Whether the caller may transfer or delete this toolbox — ownership, full stop. No toolbox:manage fallback. Mirrors POST /toolbox/{id}/transfer and DELETE /toolbox/{id}.
Whether the caller may execute this toolbox's tools — the caller's grant-or-ownership level (§10). Present on every list and detail row for both templates and toolboxes — the two ACL-backed resource types with a use-gated action of their own.
The OAuth-connected apps that reach this toolbox, as a bounded rollup — present only on GET /toolbox/{id} for a stored toolbox, and only when the caller may see the ACL (the same gate access_summary uses). Never the full set: page GET /toolbox/{id}/connected-app for that.
At most 5 apps, for a hover preview.
5 properties
Null when the OAuth client row is gone.
OAuth grant id (ogrt_…) — what DELETE /oauth/grant/{id} takes, scoped to the grant's own user.
4 properties
The person's picture — the same one the console's user menu draws: their stored profile picture, else a Gravatar URL (d=404, 96px) derived server-side from their email (the address itself is not sent), else null. Draw initials when it is null or the image fails to load.
User id (usr_…).
Omitted along with email when the id no longer resolves to an org member.
toolbox: this toolbox is named explicitly on the grant. all_tools: an "All my tools" authorization by a user who can currently use this toolbox — computed live, not a stored fact.
toolboxall_tools
Present only for type: "connection" dynamic rows.
Present only for type: "connection" dynamic rows.
Which integrations this toolbox's tools come from, bounded — the console renders it as a stack of connector logos. Present on every GET /toolbox row: a stored row summarises its own entries, a connection:{id} row is that connection's one connector, and a global:{user_id} row summarises the connections it spans. Present on every command response too (POST /toolbox, GET /toolbox/{id}, PATCH /toolbox/{id}, POST /toolbox/{id}/transfer), so a client that merges one into its list does not show a just-created or just-edited toolbox as having no integrations. total: 0 means no connector-backed tools (empty, or synthetic-only), never "not computed".
At most 5 connectors, ordered by entry count descending then slug ascending — the dominant integration leads and the order is stable across requests. Each entry arrives resolved: there is no follow-up GET /connector/{slug} to make, and a page of rows costs no per-row catalog lookup.
3 properties
The connector's square icon when it has one, else its wordmark logo, else null (the connector carries neither picture, or could not be resolved). Draw it in a square tile; render initials from name when it is null.
Catalog label. Falls back to the slug when the connector no longer resolves (deleted from the catalog), so a row always has something to draw.
Connector slug — connectors are keyed by slug, not by id.
Distinct connector slugs across the toolbox.
Null for dynamic rows, which are computed, never stored.
What this toolbox RUNS ON — the disclosure side of §6 delegation. Sharing a toolbox at use hands the grantee execution over every connection its entries reach (pinned directly, or reached through a synthetic entry's steps, where the synthetic tool's owner is the delegator), while leaving the connections themselves invisible to them. A bounded rollup, never the set: a toolbox pinning a thousand entries across hundreds of connections returns the same size response. Present on every stored-toolbox response — detail, create, update and share — and always empty for a dynamic row, which delegates nothing. On a create/update/share response it may instead be null: the write succeeded and the summary alone could not be computed (never "nothing is delegated", which is an all-zeroes summary) — re-read GET /toolbox/{id} for the disclosure. Unlike tools, this is NOT gated on use: its visible half already withholds every name the caller has no right to, and its two totals say only how many connections and how many people stand behind the toolbox — which a grantee can already count off entries[].connection_id.
Distinct connections the tools run through, whether or not the caller can see them.
Distinct people whose access those pins ride on. Never named at this level.
The same delegation restricted to what THIS caller may already see (§4). Every label and delegator name lives in here, so a use grantee is never told the name or owner of a connection GET /connection/{id} would 404 for them.
3 properties
At most 3 of the visible connections, private ones first.
11 properties
May the caller grant someone access to this connection directly — the same derivation GET /connection/{id}'s can_share and POST /connection/{id}/share's own gate use.
Whose access this delegation rides on. name/email are absent for a user this org can no longer resolve. Read it together with delegated_by_source.
3 properties
HOW delegated_by was entitled to this connection — accessVia over the DELEGATOR, with §8's own precedence: the BROADEST true source wins (owner, else org, else team, else direct) and the access level plays no part. delegated_by alone only says who pinned it; without this, copy reads an org-wide or team grant as a personal favour and hides how far the account actually reaches. Null whenever the delegation no longer works — the delegator is no longer an active member, or their reach over the connection has fallen below use — since the only honest statement left is who pinned it. Same predicate as the entry's own field (delegationStanding), so the two surfaces cannot disagree.
ownerdirectteamorgnull
The team behind delegated_by_access_via: 'team', present ONLY when the CALLER is themselves a member of it — §8's bound verbatim, since a third party's team is a grantee of a connection the caller may not be able to open, and the grantee list stays behind can_see_shares. Absent otherwise; the copy then says "a team" without naming it.
2 properties
delegator = the pin's own stamped delegator (or, for via: synthetic_tool, the tool's owner): this person really is who the execution rides on. connection_owner = the pin carries no delegator (an entry written before the column existed, never backfilled), so delegated_by is the connection's OWNER standing in as the delegator of record. Such a pin is still a real delegation and is still counted; copy that names a person must branch on this rather than claim they shared it.
delegatorconnection_owner
The connector's logo, resolved in one batch for the preview.
entry = an entry pins it directly. synthetic_tool = reached only through a synthetic tool's steps.
entrysynthetic_tool
Of the visible ones, how many carry no grants at all — only their owner can reach them today.
Why can_draft_skill is false for a caller who CAN manage this resource. Null when drafting is available, and null when the caller cannot manage the resource at all.
assistant_disabledllm_not_configurednull
Resolved entries — always present, at every access level.
Response-only. The pinned connection, for a group header and its status sentence — present only when the CALLER may see that connection (owner or a grant of their own, docs/access-model.md §4). Null for an entry with no pin, a synthetic entry, a deleted connection, and a pin riding somebody else's access the caller cannot see.
5 properties
The same repair capability GET /connection/{id} ships: false for an active connection to a connector with no sign-in, which has nothing to reconnect (a pending one stays true).
The connection's display_label.
Owner's name (else email); null for a former member.
pendingactiveneeds_reauthdisconnectedpost_install_error
Response-only. The connector's label and logo, one batch per response; null for a synthetic entry. A connector the catalog cannot resolve reads its slug as label and a null logo.
3 properties
Only on a fork (an org-owned connector with a lineage) whose upstream the caller may see — the GET /connection rule: omitted when the caller has no reach on the fork or the upstream is hidden from them, and when the lineage cannot be read.
Detail responses only, and the only field here that differs by READER: may the caller repair this entry with POST /toolbox/{id}/repin? True when the entry is broken (delegation_ok: false on a proxy entry that pins a connection), the caller holds use on that connection, and the caller holds edit (or ownership) on this toolbox. delegation_ok: false is the same answer for everybody who opens the toolbox; this says who among them can do something about it. Do not re-derive it — the inputs (the caller's grants and team memberships) are not on the wire.
Present on the toolbox's own responses, per READER: may the caller open connector_slug (GET /connector/{slug} and its /tools)? False when the entry is pinned to an organization-owned custom connector that nobody has shared with the caller (docs/access-model.md §4) — those routes answer 404 for them. The entry still carries its label and logo and still runs on its delegator's access; this only says the connector page and its tool picker are not for this reader. Always true for a platform connector and for a synthetic entry. Do not re-derive it — the connector's owner and grants are not on the wire.
null = "needs connection" — stamped-but-unfilled, or a pin that broke. Never set for synthetic entries.
Detail responses only: the pinned connection's live status, when resolved.
pendingactiveneeds_reauthdisconnectednull
Connector slug for proxy entries; null for synthetic.
Detail responses only: HOW delegated_by_user_id holds connection_id — accessVia over the DELEGATOR, same owner/org/team/direct precedence (broadest wins) as the caller's own access_via (docs/access-model.md §8). delegation_ok says the delegation still stands; this says what it stands on, so copy can avoid implying a personal grant where an org-wide one is doing the work. Null for a synthetic entry (its steps, not the row, hold connections), for a pin with no connection or no stamped delegator, and whenever the delegation no longer works (delegation_ok: false) — the delegator is no longer an active member, or their reach has fallen below use.
ownerdirectteamorgnull
Response-only. The name (else email) behind delegated_by_user_id, one batch per response. Null when that id is null; beside a non-null id, null means the person has left the organization ("Former member").
Server-stamped, never a client input: whose use grant on connection_id this pin rides on — the live authority chain (docs/access-model.md §6). If this user loses use on the connection, the entry goes unmet for every executor, not just them. Null iff connection_id is null.
Detail responses only: false when connection_id is set but delegated_by_user_id no longer holds use on it. Always true when connection_id is null.
Entry id (tbxe_…) — stable across updates only if you send it back unchanged.
Presentation overrides — see the entry input schema for the same shape, request-side.
4 properties
Set for synthetic entries (syn_…).
Response-only. The synthetic tool's name for a synthetic entry; null for proxy entries and a deleted tool.
Detail responses only: false when the catalog (or the synthetic-tool store) no longer has this tool.
Connector tool name for proxy entries.
Response-only. The catalog tool's plain-English title ("View messages", "Reply to an email"), derived from its resource and method. Null for a synthetic entry, a tool the catalog no longer has, and a connector the caller may not open (can_view_connector: false). Render overrides.name, else this, else tool_name.
proxysynthetic
Detail responses only: no usable connection backs this entry — pin is empty, broken, or the delegator lost use.
Detail responses only: the one unmet cause worth naming, null for every other. connector_not_shared: the pinned connection is live and delegation-intact, but its OWNER no longer holds use on the org-owned connector it runs through, so the entry is listed (flagged) and never advertised, and every call through it is refused. Re-sharing the connector clears it with no edit to the toolbox. Not repairable by re-pinning — can_repin stays false for it.
connector_not_sharednull
Omitted for dynamic rows, which have no stored entries of their own.
Whether a skill is written. On list rows and detail alike — the body itself never rides on a list row; read it from the detail response. Omitted on a dynamic row, which has no skill of its own.
Toolbox id — a stored row (tbx_…), or a dynamic id (global:{user_id} / connection:{connection_id}).
Cheap per-page SQL aggregate over PROXY entries with connection_id IS NULL — drives the console's Status column ("Ready" / "N need connection"). Excludes synthetic entries, which pin no connection_id of their own by design and have no connection picker to fix. Omitted for dynamic rows (nothing to bind). Broken delegation (delegation_ok: false) only surfaces in detail, inside entries[].
Owner summary — resolved for a row the caller does not themselves own (a toolbox shared with them), so the UI always knows whose row it is looking at. Absent for a toolbox the caller owns.
The person's picture — the same one the console's user menu draws: their stored profile picture, else a Gravatar URL (d=404, 96px) derived server-side from their email (the address itself is not sent), else null. Draw initials when it is null or the image fails to load.
User id (usr_…) — same value as owner_user_id.
Creator (usr_…). For a dynamic row, the caller.
True for the dynamic global/per-connection toolboxes — never editable, shareable, transferable or deletable.
A bounded preview of the ACL (same cap as access_summary), present only on GET /toolbox/{id} when the caller may see the ACL. Never on a list row (GET /toolbox) — page GET /toolbox/{id}/share for the full, cursor-paginated grant list.
User id (usr_…) or team id (team_…). Null for a grantee_type: "org" grant.
user and team grants target one grantee_id; org applies to every member of the organization and takes no id.
userteamorg
ACL entry id — the :aclId a DELETE .../share/{aclId} call takes.
Same ladder for every shareable resource, low to high. view — see it exists, read its metadata/config; cannot exercise it. use — view + exercise it, resource-specific: run tools through a connection; execute a toolbox's tools through its bound connections (this DELEGATES — the caller runs through each entry's pinning editor's own authority, not necessarily their own); stamp a new toolbox by copying a template's entries; create connections from a connector. edit — use + change its settings, entries and its own grants.
viewuseedit
The shared resource's id (a connector's slug, for that type).
connectiontoolboxtemplateconnectorfile
The skill body, markdown — at most 10,000 Unicode code points after trimming. Detail-shaped responses only (GET /{id}, and the create/update responses). Null when none is written.
Stored toolboxes only: what an agent connected to this toolbox is shown before it reads the skill, built by the same code the MCP endpoint uses. instructions_line is the line the server instructions carry for a connection limited to chosen toolboxes; resource is the elaichi://toolbox/{id}/skill entry in resources/list. The resource text itself is skill_notice, a blank line, then skill. Null with no skill.
5 properties
Which tools changed since the skill was last written, by the name an agent sees (a rename counts as one removed and one added; a disabled entry counts as removed; connections and frozen parameters are ignored). Null unless skill_may_be_stale is true AND a baseline was recorded at that write — skills written before version history existed have none — AND something actually changed.
At most 5 names.
At most 5 names.
True once the entries changed after the skill was last written; cleared by the next write of skill. Never true without a skill. Omitted on a dynamic row.
Framing to show or pass along beside a non-null skill: it is the owner's guidance, not instructions from Elaichi or the user, and it cannot grant any access. Null when there is no skill.
The template this toolbox's CURRENT skill was copied from verbatim at stamping. Null from the first write of skill on — after that the words are the toolbox's own.
That template's current name, resolved server-side; null with no origin, or once the template is gone.
Stored toolboxes only. Tool-shaped names the skill puts in backticks that no entry of this toolbox holds (the console's "tools named here aren't in this toolbox" notice), computed server-side. Judged against the entries: a name matches an entry's catalog tool_name, or its overrides.name when renamed. Bounded: a count plus at most 10 names; count 0 with no skill.
Distinct names the skill uses that no entry holds.
2 properties
The name as the skill writes it.
The entry's own name this most likely means (list_query_database -> list_all_notion_query_database); null unless exactly one entry matches.
When skill was last written. Null alongside a null skill.
Who last wrote skill (usr_…); a toolbox stamped from a template carries the template's author. Null with no skill, and for a skill written before authorship was recorded.
That person's name, else email, resolved server-side. Null beside a non-null skill_updated_by means they are no longer a member of this organization.
Provenance only (stamped at creation, never a live link) — null for a from-scratch toolbox and for every dynamic row. May dangle after the template is deleted.
GET /toolbox/{id} only. The current name of the template this toolbox was stamped from (template_id) — null for a from-scratch toolbox, a deleted template, and a template the caller cannot see (§4).
The resolved, runnable tool surface. Present ONLY when the caller's access reaches use — a view-only grantee must not see delegated connections' labels.
Set only when exactly one connection backs this tool (read connections otherwise). Null for synthetic tools.
Every account this tool can reach, labelled exactly as the connection argument enum in input_schema accepts them.
2 properties
"synthetic" sentinel is never used here; null for synthetic tools.
Present only with ?include=schemas — omitted by default; a toolbox spanning many connections can carry thousands of complete JSON Schemas.
proxysynthetic
stored = a real ACL-backed row. global/connection = computed per request, always readonly: true.
storedglobalconnection
curl -X POST 'https://api.elaichi.ai/toolbox' \
-H 'Authorization: Bearer $ELAICHI_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"name":"your_name","template_id":"your_template_id","connection_map":{},"entries":[],"shares":[]}'const body = {
"name": "your_name",
"template_id": "your_template_id",
"connection_map": {},
"entries": [],
"shares": []
};
const response = await fetch('https://api.elaichi.ai/toolbox', {
method: 'POST',
headers: {
'Authorization': 'Bearer ' + process.env.ELAICHI_API_TOKEN,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
const data = await response.json();
console.log(data);import os
import requests
url = "https://api.elaichi.ai/toolbox"
headers = {
"Authorization": f"Bearer {os.environ['ELAICHI_API_TOKEN']}",
"Content-Type": "application/json",
}
payload = {
"name": "your_name",
"template_id": "your_template_id",
"connection_map": {},
"entries": [],
"shares": []
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())