mirror of
https://github.com/simstudioai/sim.git
synced 2026-09-21 13:00:04 +08:00
Waleed
c930830310
* fix(chat): resolve a caller-supplied conversation id through its owner The v2 chat route used the caller-supplied conversationId verbatim, with no existence, owner, or workspace check, against a store keyed by bare text with no owner column. A caller who knew another user's conversation id reached that conversation. Ids now resolve through the same owner-scoped loader the web chat path uses, and anything unresolvable answers one uniform 404 before any lifecycle work runs. Omitting the id mints a server-issued conversation. The contract also accepted any 1-128 character string for a column typed uuid, so a malformed id raised a driver error and rendered 500 while an unknown but well-formed id rendered 404 - a shape oracle, and a 500 on ordinary input. The ownership predicate had no coverage anywhere: the route test mocked the module and the lifecycle test drove a chain mock that ignores its where clause, so deleting the owner condition left both suites green. It is now asserted by composition and by condition count, which is what catches a dropped condition. Also renames the reply's model identifier away from a term the project's own copy rules forbid on a user-facing surface. * fix(v2): conceal workspace absence, and stop archived tables faulting their page Two reads answered a caller more than they were entitled to know. A workspace a caller cannot reach at all returned FORBIDDEN while one that does not exist returned NOT_FOUND, so a workspace-key holder could enumerate which workspace ids exist by diffing the two. Both now answer the same absence, using the concealment policy the billing routes already use. A refusal from inside the workspace - a member whose role is too low - still answers FORBIDDEN, because that caller already knows the workspace exists. Separately, archiving a folder cascades onto its tables but leaves each table pointing at the archived folder row. The archived listing resolved those paths strictly, so one such row faulted the whole page and no cursor could step past it - which also made the ids undiscoverable and left restore unreachable for exactly the tables that need it. The archived scope now resolves leniently to the root, where a restore would place them, matching the shipped workflows behavior. Active listings still fault loudly on a dangling folder. * fix(knowledge): validate upload processing options without stranding live sessions recipe and lang were accepted as free strings up to their length caps, silently discarded, and echoed back nowhere, so a typo was unobservable: uploading with a misspelled recipe returned 200 and quietly used the default. Both are now validated at the boundary and a bad value answers 400 naming what is accepted. The accepted recipe set deliberately includes the sentinel every first-party caller sends today alongside the three real chunker recipes, and the three are derived from the chunker's own union so removing one there is a compile error here rather than a silent 400 in production. The same schema also parses metadata read back off a persisted upload session, so tightening it would have thrown out of resume and complete for any session created before this - a 500 on work that could then never finish. The read-back path now drops a value it no longer recognises instead of rejecting it; the request boundary stays strict. Neither field reaches chunking, so nothing here moves chunk boundaries, embeddings, or search results. * fix(v2): honour a requested stats window, and answer a claimed graph id with a conflict Log statistics accepted a start and an end, filtered the totals by them, and then built the series against wall-clock now. Bucket width was computed over a span the caller never asked for, and every bucket past the requested end was structurally empty - so a bounded historical query returned a wrong-width series with fabricated trailing buckets, under a window label that disagreed with the request. Each edge now honours the bound it was given and keeps its previous derivation when omitted, so an unbounded request is unchanged. Separately, block, edge and subflow ids are global primary keys while the delete that precedes a state replace is scoped to one workflow. An id owned by another workflow survived that delete, the insert violated the key, and because callers pass their own transaction the driver error escaped unclassified as a server fault. The write now refuses such an id up front with a conflict naming it, and re-classifies the same violation if one races past the check, since the lock covers only the workflow being written. The dry run checks the ids a commit would insert and reports the warnings a commit would report, which is what its own contract already promised. * fix(secrets): let a workspace secret change its metadata without resending the value Restoring redaction cost more than removing it. The only way to flip a secret back to redacted was to re-send the plaintext, because the write required a value and omitting it fell into an interactive prompt that cannot run in CI. A workspace secret can now change its description or visibility on its own; the stored value is never re-encrypted or rewritten, a write that names no existing secret answers not-found rather than creating one, and a personal secret still requires a value because it has no other writable field. The path parameter was also one shared schema across the write and the delete, so a single description had to cover both and the delete documented an argument that could create and replace. Split, mirroring the credentials pair. The metadata write is a new update against the credentials table, so its scope is asserted by composition and by condition count: an unscoped update would let one workspace flip another workspace's identically-named secret out of redaction, and the cache invalidation would then carry that flag into the other workspace's runtime catalog. * fix(v2): say what an error means in terms the caller can act on A size-limit refusal collapsed every value under a kilobyte to "0 Bytes", so a 28-byte file over a 27-byte ceiling read "is 0 Bytes, above the 0 Bytes limit" - self-contradictory, and useless for choosing a value that would work. Errors and field descriptions also told callers to invoke raw HTTP endpoints. These strings serve the REST reference and the CLI's own help equally, so they now name the operation and its object rather than a method and a path. A sweep test walks every v2 schema description and holds the line, with the remaining offenders in files this change does not own recorded explicitly rather than left to be rediscovered. Listing the editors of a built-in skill claimed the skill did not exist, while reading the same id succeeded - a well-formed request for a real resource is not malformed, so the list answers an empty roster and only the mutations refuse. Bulk folder deletion recorded only the leaf name in its audit trail while the single delete recorded the full path, leaving two same-named folders under different parents indistinguishable after the fact. Bulk chunk enable, disable and delete each treated an unmatched id differently behind one sentence of documentation. They now follow one rule. A workspace-scoped list refused with the name of a resource the caller never addressed, which reads as an empty workspace rather than an unreachable one. * fix(cli): stop a config value forging a section it was never meant to write The config file is written by joining names and values into INI lines, and nothing checked what was in them. A profile name carrying a newline and a section header wrote a section that merged into a different profile and took over its endpoint - and the next command sent that profile's stored API key there. A workspace value could do the same from the other side, since only the endpoint flag validated its input. The refusal now lives at the writer, the single place untrusted text enters the document, with the flag-level checks kept for the better message. Either alone blocks the forgery; the pair is deliberate. Rejecting rather than escaping, because the format has no escape syntax and these files are hand-edited and read by other tools that would not decode one we invented. The forbidden set covers control characters and the two Unicode line separators, which the previous guard missed - those parse as an unreadable line, so the key silently vanished on read and the next write appended a duplicate while the command reported success. Login also wrote the key before the settings, so a malformed response from the deployment could leave a key on disk with no endpoint beside it, and the next command would send it to the default host. Settings are written first, and the response is checked before anything touches disk. Name validation applies only when creating a profile, so a hand-written one that predates the rule keeps working. * fix(docs): tell the reader which key a command needs, and stop the ids contradicting the CLI Around sixty v2 operations refuse a workspace API key, and the CLI's help said nothing about it - the caller found out from a 403 after the request went out. The restriction is already stated in the API spec, so the generator now reads it from there and the command description carries it. The sentinel sentences are imported from the spec's own constants rather than copied, so a reword cannot silently unmark every command, and the test pins the count as well as named operations because a reword confined to one family would otherwise slip past. The generated reference also rendered an empty default as a sentence pointing at nothing - "Defaults to ." - for every repeatable filter. Omitted now, while false and zero still render, which is the trap that shape of check usually walks into. The hand-written guides used a workflow-shaped id for workflows that the CLI's own help says never names one, and five other families were equally wrong. All of them now match the scheme the CLI declares, consistently per entity across pages, with the shared ones taken from that help text so the two read as one voice. The page documenting every flag was linked from nowhere; both landing links pointed at the overview instead. And the generator's test file was absent from the hand-maintained list CI runs, so its guards never executed. * fix(cli): stop a page-size default capping a destructive filter Every request field named limit inherited the pager's default of 100, but only a cursor-paginated command interprets that flag. The two filter-based row mutations declare no cursor, so the default went onto the wire as a row cap: a filter matching 250 rows deleted 100, exited 0, and said nothing - while the confirmation the user had just answered promised every matching row. The flag's own help offered 0 for everything, which those endpoints reject; the unbounded form is the field being absent. The pager's default now applies only where the pager runs, and the tests pin the omission on the request body rather than in help text. A cap typed alongside an explicit row list was silently ignored; it is now refused on the client, where refusing costs nothing to already-installed versions. Lists also truncated at a hundred with no signal in any format, and the two inventory endpoints that do report truncation had that field dropped on the way out - so a caller reconciling against a clipped list could not tell. One note now goes to stderr while stdout stays a bare array, and a flag raised on a later page survives the fold. Also: a folder whose name contains the separator no longer prints a path that resolves to a different folder; validation errors name the flag the user typed instead of the wire field; an unknown subcommand with --help exits non-zero instead of printing the parent's help; a fractional or negative page size is refused rather than floored; an empty query filter is refused rather than silently returning everything; and the two spellings of the missing-workspace message became one. * fix(cli): gate destructive table imports and fix follow-mode rendering A `tables import --mode replace` empties the table before its first batch, so the only warning was in the describe. It now confirms, and the wording tells the truth per mode: cancelling a replace leaves a prefix of the new file with the originals already gone, while an append re-adds its rows if the file is imported twice. `--yes` skips the gate, and the gate runs before the file is opened. Import and export cancellation carried no describe at all; the import one now confirms, the export one records why it deliberately does not. Follow-mode output truncated cells to whatever the first row happened to measure, so a longer status or workflow name arrived clipped with no signal. Cells now clamp at a shared ceiling and pad to the lock, and the log columns carry width floors so a short first page cannot pin a column narrower than its own values. Interrupting a staged download left the staging directory behind; it is now removed on SIGINT and SIGTERM before the signal is re-raised. `--select-output` without `--follow` selected from a response that does not carry outputs, and said nothing. It is refused client-side, with a separate message for `--async`. Its describe now names what the path addresses. `secrets set` always read a value, even when only metadata flags were passed. Off a TTY that was an immediate refusal, so a metadata-only edit exited 1 in CI for a value it was never asked for; on a TTY it stopped to prompt, and the prompt rejects an empty entry, so there was no way to say "leave the stored value alone" short of re-typing the secret. The read is now skipped and the field omitted, which is what lets a metadata-only edit run unattended. On a TTY, setting only a description no longer prompts. Passing both spellings of the reveal flag is refused rather than silently resolved. Four mandatory hand-authored flags now say so, `billing logs` names its key-type scope, and the dispatch list declares its columns. * fix: close the gaps an adversarial review of this branch found A conflict handler added earlier in this branch was dead code. It read the Postgres error code off the thrown object, but the driver error arrives wrapped with the real one on `cause`, so the check returned false on its first line and the 409 never fired. Its test passed only because it threw a flat shape production never produces. It now reads through the cause chain with the shared helpers, compares the constraint name exactly instead of matching a substring of the SQL, and its test throws the real wrapped error. Resuming a conversation checked its workflow and its workspace but not its type, so a conversation created by the web surface could be continued as a CLI turn. It now refuses through the same uniform 404 as every other mismatch, which closes the same omission on the web posting path. Minting one no longer leaves a blank untitled row at the top of the Chat list. The pre-write check on a minted API key refused fewer characters than the writer does, so a key the check accepted could still fail at the write — after the endpoint beside it was already stored, pairing a new endpoint with the previous key. The two had drifted because the set was spelled three times; there is now one. A description claimed a processed count reported only the chunks that changed. The update returns every row it matched, so re-enabling chunks that were already enabled counts them all. Two OpenAPI sentences promised no conflict detection and no persistence warnings in a dry run, both of which the same branch had just made false. A described window was wrong whenever a start was supplied without an end. Listing the editors of a built-in skill answered a read with a modification refusal on the internal surface. Archived table listings could reach the strict folder projector again through a third scope value the input type still allowed. A metadata-only secret write skipped the guard its personal-scope twin has. The internal document boundary still took the two processing fields as unbounded strings. Truncation was reported only from the response envelope, so a clipped file body, row search and workflow-stats list said nothing. A staged download stopped watching for signals before it finished removing its directory, and cleared every listener for the signal rather than its own. Three tests asserted a contract constant against itself; they now drive rendered help, real argv, or real render output. * chore: regenerate the API reference, CLI surface, and CLI docs The published reference still marked a secret value required and described the delete parameter as one that also creates, the CLI surface still lacked the marker that says which operations refuse a workspace key, and the reference rendered an empty sentence for every repeatable filter whose default is an empty list. * test(cli): use the package's own delay helper in the staging poll The audit bans a hand-rolled setTimeout promise. `sim-cli` does not depend on the shared utils package, and its own idiom is `node:timers/promises`. * fix: act on a second review round, and correct two earlier claims The conflict pre-check read block ids from the wrong side. The writer inserts each block's own `id` field while the check read the record key, and the two can diverge because preparation copies a value under its key without reconciling them. Edges already read the value and subflows are genuinely keyed by the record key, so only blocks were wrong — collecting every family from the values, as first suggested, would have broken subflows instead. A minted API key carrying leading or trailing whitespace passed the pre-write check but failed the writer, leaving the new endpoint on disk beside the previous key. It is refused up front now rather than trimmed: a key is opaque, so trimming would store a value the server never issued and turn a loud failure into an unexplained 401 later. The endpoint normalizer does trim, which is what made a padded `--endpoint` fail only after the browser flow had already minted a key. A metadata-only secret write raced with deletion returned 500, because the follow-up read that only assembles the response body threw an unclassified error; it now reports the same not-found the non-racing miss already gave. An unusable output format in the environment silently printed a table instead of refusing. Two validation messages printed control characters verbatim. A dry run now reports the preparation warnings its own commit path returns. The chat route created a titled conversation and never wrote a message, so it appeared in the Chat list promising content it did not have. Both sides of a successful turn are now persisted; a failed turn still writes nothing, so a question is never stored without its answer. Two claims of mine were wrong. The earlier commit message said `secrets set` sent an empty value that overwrote the stored secret — it did not; the prompt refuses off a TTY and rejects empty on one, so the old behaviour was a clean refusal. And the delay helper commit said this package's idiom is `node:timers/promises`; the package carries its own `sleep`, which is the audit's sanctioned home and has five callers. It uses that now. Also: a test asserting a deadlock stays unclassified could not fail, since every candidate rejects it; it now pins a unique violation carrying no constraint name. Workflow ids spelled with the file prefix are corrected in the remaining fixtures, leaving the genuine file ids alone. * fix: close a credential-misdirection path this branch had opened Making the endpoint normalizer trim handled whitespace around a value but not a control character inside one, and the URL parser removes those from anywhere in its input — so a value that reads as one host could resolve to another, and the profile's key went with it. The flag and environment paths never touch the config writer, so its guard did not cover this. The normalizer now refuses the same character set the writer does, which also keeps the invariant that nothing it blesses can be refused by the write that stores it. Comparing the parsed URL back against its input was the alternative and is wrong: the parser rewrites percent-encoding, case, internationalized hosts and default ports, so legitimate endpoints would be refused. The blank-query guard tested for exactly empty, so a whitespace-only value still reached the wire — as a real zero on a numeric filter, an explicit false on a boolean one, and as an encoded space the server then rejected. It now refuses any value that is blank once trimmed, while a body string keeps its meaning, an explicit zero still sends, and a value with content around its whitespace is passed through untouched rather than trimmed. A graph-id conflict reported 409 on the v2 route and fell through the older persistence wrapper as an unclassified 500. That wrapper now classifies orchestration failures through the cause chain, which also fixes a pre-existing case where a workflow archived between authorization and the locked read reported 500 rather than 404. Persisting a chat turn claimed its row by id alone, so a conversation soft-deleted mid-turn still received the messages and was bumped back up the list. It now requires a live row. A turn whose caller hung up after the model had already answered persisted nothing, though the work was done and billed; it now persists and still reports the connection as closed. An empty workspace id from the login response was read as no workspace at all. A published description still promised a language-tag standard the schema does not enforce. The test asserting that a turn is stored before the final event drained the whole response first, so it held whichever order the code used. It now reads the stream incrementally and fails if the write moves after the event.
9776 lines
350 KiB
JSON
9776 lines
350 KiB
JSON
{
|
||
"openapi": "3.1.0",
|
||
"info": {
|
||
"title": "Sim API v2 — Workspace Resources",
|
||
"description": "Version 2 of the Sim REST API for workspace metadata, members, MCP servers, skills, custom tools, credentials, write-only secrets, and the block, tool, and connector-type catalogs.",
|
||
"version": "2.0.0",
|
||
"contact": {
|
||
"name": "Sim Support",
|
||
"email": "help@sim.ai",
|
||
"url": "https://www.sim.ai"
|
||
},
|
||
"license": {
|
||
"name": "Apache 2.0",
|
||
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
|
||
}
|
||
},
|
||
"servers": [
|
||
{
|
||
"url": "https://www.sim.ai",
|
||
"description": "Production"
|
||
}
|
||
],
|
||
"tags": [
|
||
{
|
||
"name": "Meta",
|
||
"description": "Discover what the calling API key can reach."
|
||
},
|
||
{
|
||
"name": "Workspaces",
|
||
"description": "Read workspace metadata and its effective member roster."
|
||
},
|
||
{
|
||
"name": "MCP Servers",
|
||
"description": "Register and manage Model Context Protocol servers."
|
||
},
|
||
{
|
||
"name": "Skills",
|
||
"description": "Create and manage reusable instruction documents for agents."
|
||
},
|
||
{
|
||
"name": "Custom Tools",
|
||
"description": "Create and manage code-backed tools that agents can call."
|
||
},
|
||
{
|
||
"name": "Credentials",
|
||
"description": "Discover providers, create service-account credentials, connect or reconnect OAuth accounts, disconnect credentials, and list connections without secret material."
|
||
},
|
||
{
|
||
"name": "Secrets",
|
||
"description": "Set and manage write-only workspace and personal secret values."
|
||
},
|
||
{
|
||
"name": "Catalog",
|
||
"description": "Discover the blocks, tools, and connector types this workspace can build with."
|
||
}
|
||
],
|
||
"security": [
|
||
{
|
||
"apiKey": []
|
||
}
|
||
],
|
||
"paths": {
|
||
"/api/v2/workspaces": {
|
||
"get": {
|
||
"operationId": "listWorkspaces",
|
||
"summary": "List Workspaces",
|
||
"description": "List active workspaces available to the API key with opaque cursor pagination. A personal API key sees every accessible workspace that permits personal API keys; a workspace API key sees only its bound workspace.",
|
||
"tags": ["Workspaces"],
|
||
"parameters": [
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"schema": {
|
||
"default": "createdAt",
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"type": "string",
|
||
"enum": ["name", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "desc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum workspaces to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum workspaces to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Public metadata for workspaces available to the API key.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListWorkspacesResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/workspaces/{workspaceId}": {
|
||
"get": {
|
||
"operationId": "getWorkspace",
|
||
"summary": "Get Workspace",
|
||
"description": "Return public metadata for one accessible workspace. Governance identities, billing identities, and internal membership identifiers are intentionally omitted.",
|
||
"tags": ["Workspaces"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Workspace to retrieve.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace to retrieve."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Public workspace metadata.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GetWorkspaceResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/workspaces/{workspaceId}/members": {
|
||
"get": {
|
||
"operationId": "listWorkspaceMembers",
|
||
"summary": "List Workspace Members",
|
||
"description": "List the workspace's effective members ordered by email. Explicit workspace grants and inherited organization-administrator grants are merged; internal membership and billing identities are omitted.",
|
||
"tags": ["Workspaces"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Workspace to retrieve.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace to retrieve."
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum members to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum members to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "An email-ordered page of effective workspace members.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListWorkspaceMembersResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/mcp-servers": {
|
||
"get": {
|
||
"operationId": "listMcpServers",
|
||
"summary": "List MCP Servers",
|
||
"description": "List MCP servers registered in a workspace. Request-header values and OAuth client secrets are never returned. The discovery fields stay at their registration defaults until `GET /api/v2/mcp-servers/{mcpServerId}/tools` runs a discovery.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the MCP server.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the MCP server."
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the server name.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the server name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"schema": {
|
||
"default": "createdAt",
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"type": "string",
|
||
"enum": ["name", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "desc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum MCP servers to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum MCP servers to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "MCP servers registered in the workspace.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListMcpServersResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createMcpServer",
|
||
"summary": "Create MCP Server",
|
||
"description": "Register an MCP server in a workspace. The endpoint URL is the server identity, so a URL already registered here is a `409` — reconfigure that server with `PATCH /api/v2/mcp-servers/{mcpServerId}` instead. Registration never connects to the endpoint: the server comes back `disconnected` and stays unavailable until `GET /api/v2/mcp-servers/{mcpServerId}/tools` succeeds.",
|
||
"tags": ["MCP Servers"],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Configuration for a new MCP server.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateMcpServerRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The MCP server was registered.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateMcpServerResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/mcp-servers/{mcpServerId}": {
|
||
"get": {
|
||
"operationId": "getMcpServer",
|
||
"summary": "Get MCP Server",
|
||
"description": "Fetch one MCP server by identifier. Request-header values and OAuth client secrets are never returned.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "mcpServerId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique MCP server identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique MCP server identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the MCP server.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the MCP server."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The MCP server.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GetMcpServerResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateMcpServer",
|
||
"summary": "Update MCP Server",
|
||
"description": "Update the supplied MCP server fields. Omitted fields are retained, except where a field says otherwise. Any change that invalidates authentication revokes the stored OAuth grant, resets `connectionStatus` to `disconnected`, and clears `lastConnected` and `lastError`, so the server must be rediscovered.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "mcpServerId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique MCP server identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique MCP server identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "MCP server fields to change; omitted fields retain their stored values.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateMcpServerRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated MCP server.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateMcpServerResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteMcpServer",
|
||
"summary": "Delete MCP Server",
|
||
"description": "Remove an MCP server and revoke its OAuth tokens. Workflows retain blocks that referenced the server's tools, but those tools can no longer be called.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "mcpServerId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique MCP server identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique MCP server identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the MCP server.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the MCP server."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The MCP server was deleted.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/DeleteMcpServerResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/mcp-servers/{mcpServerId}/tools": {
|
||
"get": {
|
||
"operationId": "listMcpServerTools",
|
||
"summary": "List MCP Server Tools",
|
||
"description": "Connect to a registered MCP server and return the tools it exposes. This read has side effects: it opens a live connection to the third-party server and writes `connectionStatus`, `toolCount`, `lastError`, and `lastToolsRefresh`. A `HEAD` skips the effect but is authorized exactly as the `GET` is, so it answers `400`, `401`, `403`, or `404` wherever the `GET` would and an empty `200` otherwise. Skipping the effect means skipping the read that produces the payload, so that `200` carries none of the response headers documented below — it answers whether the `GET` would be allowed, not what the `GET` would return. Discovery is bounded at 1,000 tools and 5 MB of tool payload per server. The bounded set is returned in one page; `nextCursor` is always null. An unreachable, slow, or cooling-down server is a `503`; a stored OAuth grant that no longer works is a `409` with `error.details.code` `MCP_SERVER_REAUTHORIZATION_REQUIRED`, which only a human reauthorizing in Sim can clear. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "mcpServerId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique MCP server identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique MCP server identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the MCP server.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the MCP server."
|
||
}
|
||
},
|
||
{
|
||
"name": "refresh",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Bypass the short-lived per-workspace tool cache and reconnect under your own credentials. A cached result reflects whichever workspace member last ran discovery, so this is the only way to pick up a tool added since then; it costs a live round trip.",
|
||
"schema": {
|
||
"description": "Bypass the short-lived per-workspace tool cache and reconnect under your own credentials. A cached result reflects whichever workspace member last ran discovery, so this is the only way to pick up a tool added since then; it costs a live round trip.",
|
||
"type": "boolean"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Tools exposed by the MCP server.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListMcpServerToolsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/skills": {
|
||
"get": {
|
||
"operationId": "listSkills",
|
||
"summary": "List Skills",
|
||
"description": "List workspace and built-in skills with opaque cursor pagination. Built-ins are marked read-only. The list omits skill bodies; fetch one skill to read its content.",
|
||
"tags": ["Skills"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the skill.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the skill."
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the skill name.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the skill name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"schema": {
|
||
"default": "createdAt",
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"type": "string",
|
||
"enum": ["name", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "desc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum skills to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum skills to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Skills available in the workspace.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListSkillsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createSkill",
|
||
"summary": "Create Skill",
|
||
"description": "Create one skill in a workspace. Its kebab-case name must be unique and cannot be reserved by a built-in skill. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Skills"],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Definition of a new skill.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateSkillRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The skill was created.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateSkillResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/skills/{skillId}": {
|
||
"get": {
|
||
"operationId": "getSkill",
|
||
"summary": "Get Skill",
|
||
"description": "Fetch one workspace or built-in skill, including its full content. Built-in skills are marked read-only.",
|
||
"tags": ["Skills"],
|
||
"parameters": [
|
||
{
|
||
"name": "skillId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the skill.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the skill."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The skill.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GetSkillResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateSkill",
|
||
"summary": "Update Skill",
|
||
"description": "Update the supplied fields on a workspace skill. Omitted fields retain their stored values. Built-in skills are read-only. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Skills"],
|
||
"parameters": [
|
||
{
|
||
"name": "skillId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Skill fields to change; at least one editable field is required.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateSkillRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated skill.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateSkillResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteSkill",
|
||
"summary": "Delete Skill",
|
||
"description": "Delete a workspace skill. Built-in skills are read-only and cannot be deleted. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Skills"],
|
||
"parameters": [
|
||
{
|
||
"name": "skillId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the skill.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the skill."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The skill was deleted.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/DeleteSkillResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/skills/{skillId}/editors": {
|
||
"get": {
|
||
"operationId": "listSkillEditors",
|
||
"summary": "List Skill Editors",
|
||
"description": "List explicit skill editors and workspace administrators with opaque cursor pagination. Internal user and membership identifiers are never returned.",
|
||
"tags": ["Skills"],
|
||
"parameters": [
|
||
{
|
||
"name": "skillId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the skill.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the skill."
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"schema": {
|
||
"default": "email",
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"type": "string",
|
||
"enum": ["email", "name"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "asc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum skill editors to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum skill editors to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Users who can edit the skill.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListSkillEditorsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "grantSkillEditor",
|
||
"summary": "Grant Skill Editor",
|
||
"description": "Grant editor access to a current workspace member by email. The caller must already be a skill editor or workspace administrator. Workspace administrators already have derived editor access and cannot receive an explicit grant. A retried existing grant returns 200; a newly created grant returns 201. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Skills"],
|
||
"parameters": [
|
||
{
|
||
"name": "skillId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Workspace scope and email of the member to grant.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GrantSkillEditorRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The workspace member was already a skill editor.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GrantSkillEditorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"201": {
|
||
"description": "The skill editor grant was created.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GrantSkillEditorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "revokeSkillEditor",
|
||
"summary": "Revoke Skill Editor",
|
||
"description": "Revoke an explicit editor grant by email. The caller must already be a skill editor or workspace administrator. Workspace administrators have derived access that cannot be revoked. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Skills"],
|
||
"parameters": [
|
||
{
|
||
"name": "skillId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the skill.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the skill."
|
||
}
|
||
},
|
||
{
|
||
"name": "email",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Email address of a current workspace member.",
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "email",
|
||
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
|
||
"description": "Email address of a current workspace member."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The explicit editor grant was revoked.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/RevokeSkillEditorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/custom-tools": {
|
||
"get": {
|
||
"operationId": "listCustomTools",
|
||
"summary": "List Custom Tools",
|
||
"description": "List code-backed custom tools defined in a workspace, with opaque cursor pagination. Legacy personal tools are excluded.",
|
||
"tags": ["Custom Tools"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the custom tool.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the custom tool."
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the tool title.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the tool title.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result.",
|
||
"schema": {
|
||
"default": "createdAt",
|
||
"description": "Field used to sort the result.",
|
||
"type": "string",
|
||
"enum": ["title", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "desc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum custom tools to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum custom tools to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Custom tools defined in the workspace.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListCustomToolsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createCustomTool",
|
||
"summary": "Create Custom Tool",
|
||
"description": "Create a code-backed custom tool in a workspace. Its title must be unique because tools resolve by title at call time.",
|
||
"tags": ["Custom Tools"],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Definition and implementation of a new custom tool.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateCustomToolRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The custom tool was created.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateCustomToolResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/custom-tools/{customToolId}": {
|
||
"get": {
|
||
"operationId": "getCustomTool",
|
||
"summary": "Get Custom Tool",
|
||
"description": "Fetch one custom tool by identifier, scoped to its workspace.",
|
||
"tags": ["Custom Tools"],
|
||
"parameters": [
|
||
{
|
||
"name": "customToolId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique custom tool identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique custom tool identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the custom tool.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the custom tool."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The custom tool.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GetCustomToolResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateCustomTool",
|
||
"summary": "Update Custom Tool",
|
||
"description": "Update the supplied custom tool fields. Omitted fields retain their stored values, and titles must remain unique within the workspace.",
|
||
"tags": ["Custom Tools"],
|
||
"parameters": [
|
||
{
|
||
"name": "customToolId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique custom tool identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique custom tool identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Custom tool fields to change; at least one editable field is required.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateCustomToolRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated custom tool.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateCustomToolResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteCustomTool",
|
||
"summary": "Delete Custom Tool",
|
||
"description": "Delete a custom tool. Agent blocks retain their configuration but can no longer call the deleted tool.",
|
||
"tags": ["Custom Tools"],
|
||
"parameters": [
|
||
{
|
||
"name": "customToolId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique custom tool identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique custom tool identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace that owns the custom tool.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the custom tool."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The custom tool was deleted.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/DeleteCustomToolResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/credentials": {
|
||
"get": {
|
||
"operationId": "listCredentials",
|
||
"summary": "List Credentials",
|
||
"description": "List OAuth and service-account connections visible to the caller. Secret material is never returned.",
|
||
"tags": ["Credentials"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace whose credentials should be listed.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace whose credentials should be listed."
|
||
}
|
||
},
|
||
{
|
||
"name": "type",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict results to this credential type.",
|
||
"schema": {
|
||
"description": "Restrict results to this credential type.",
|
||
"type": "string",
|
||
"enum": ["oauth", "service_account"]
|
||
}
|
||
},
|
||
{
|
||
"name": "providerId",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict results to credentials for this integration provider.",
|
||
"schema": {
|
||
"description": "Restrict results to credentials for this integration provider.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the credential display name.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the credential display name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result.",
|
||
"schema": {
|
||
"default": "createdAt",
|
||
"description": "Field used to sort the result.",
|
||
"type": "string",
|
||
"enum": ["displayName", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "desc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum credentials to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum credentials to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Credentials visible to the caller.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListCredentialsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createServiceAccountCredential",
|
||
"summary": "Create Service-Account Credential",
|
||
"description": "Verify and store one service-account credential. Use provider discovery to select a service-account provider, then encode its required fields as the JSON object string in credentials. The credentials string is write-only and is never returned. A retried source match returns the existing credential with 200; a newly created credential returns 201. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Credentials"],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Provider identifier, optional display metadata, and a write-only JSON object string containing the fields declared by provider discovery.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateServiceAccountCredentialRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "An existing credential matched the verified source.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateServiceAccountCredentialResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"201": {
|
||
"description": "The service-account credential was created.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateServiceAccountCredentialResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/credentials/providers": {
|
||
"get": {
|
||
"operationId": "listCredentialProviders",
|
||
"summary": "List Credential Providers",
|
||
"description": "List catalogued OAuth and service-account connection methods and whether each is available to the caller in this workspace and deployment. Optionally search provider names with a case-insensitive substring match. OAuth authorization options contain the exact provider IDs accepted by the browser connection endpoint; service-account methods list the exact create-body fields and mark secret fields write-only. The bounded set is returned in one page; `nextCursor` is always null.",
|
||
"tags": ["Credentials"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace used to evaluate credential-provider availability and integration policy.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace used to evaluate credential-provider availability and integration policy."
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the credential provider name.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the credential provider name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Credential provider catalog with caller-specific availability.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListCredentialProvidersResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/credentials/connections": {
|
||
"post": {
|
||
"operationId": "createCredentialConnection",
|
||
"summary": "Create Credential Connection",
|
||
"description": "Create a short-lived browser URL for connecting an OAuth provider or reconnecting an existing OAuth credential. Open the URL in a browser, sign in as the personal API-key owner, complete provider authorization, then refresh the credentials list. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Credentials"],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "For a new connection, provide providerId and displayName. For a reconnect, provide only credentialId; the existing display name is preserved.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateCredentialConnectionBody"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "A short-lived browser authorization URL.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateCredentialConnectionResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/credentials/{credentialId}": {
|
||
"delete": {
|
||
"operationId": "deleteCredential",
|
||
"summary": "Disconnect Credential",
|
||
"description": "Disconnect an OAuth or service-account credential and clear its stored workflow, deployment, paused-run, knowledge-connector, and webhook references. Credential admin access is required. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Credentials"],
|
||
"parameters": [
|
||
{
|
||
"name": "credentialId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Credential to disconnect.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Credential to disconnect."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace expected to own the credential.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace expected to own the credential."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The credential was disconnected.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/DeleteCredentialResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateCredential",
|
||
"summary": "Update Credential",
|
||
"description": "Rotate a service-account credential's secret material, or rename it. Send only the fields to change: an omitted field is left unchanged, and `description: null` clears the stored description. Secret fields are write-only and are never returned, and only a service-account credential has any: sending one for a credential of another type answers `400` rather than dropping it. The provider re-verifies replacement secret material before it replaces the stored secret, so a rejected secret leaves the stored one untouched and answers `400` with the provider's code in `error.details.providerErrorCode`; a provider that cannot be reached answers `503`. The credential ID is preserved, so every workflow, deployment, paused run, knowledge connector, and webhook that references it keeps working — which disconnecting and re-creating does not. Credential admin access is required. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Credentials"],
|
||
"parameters": [
|
||
{
|
||
"name": "credentialId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Credential to update.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Credential to update."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace expected to own the credential.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace expected to own the credential."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Replacement display metadata and the write-only fields declared by provider discovery.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateCredentialRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated credential without secret material.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateCredentialResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/secrets": {
|
||
"get": {
|
||
"operationId": "listSecrets",
|
||
"summary": "List Secrets",
|
||
"description": "List workspace and caller-owned personal secret metadata with opaque cursor pagination. Rows for workspace secrets marked visible (unredacted) include the stored value; every other row is metadata-only and no other response ever carries a value. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Secrets"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace whose secret metadata should be listed.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace whose secret metadata should be listed."
|
||
}
|
||
},
|
||
{
|
||
"name": "scope",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict results to one ownership scope.",
|
||
"schema": {
|
||
"description": "Restrict results to one ownership scope.",
|
||
"type": "string",
|
||
"enum": ["workspace", "personal"]
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the secret name.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the secret name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"schema": {
|
||
"default": "name",
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"type": "string",
|
||
"enum": ["name", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "asc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum secrets to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum secrets to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Secret metadata visible to the caller.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListSecretsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/secrets/{name}": {
|
||
"put": {
|
||
"operationId": "setSecret",
|
||
"summary": "Set Secret",
|
||
"description": "Create or replace a workspace or caller-owned personal secret. The value is encrypted at rest, is write-only, and is never included in the response. Omit `value` on a workspace secret to update `description` and `unredacted` alone: the stored value is left untouched and is never re-encrypted, and because a metadata-only write cannot create a secret it answers `404` when the named secret does not exist. A personal secret always requires `value`, having no other writable field. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Secrets"],
|
||
"parameters": [
|
||
{
|
||
"name": "name",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Secret to create or replace.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"pattern": "^[A-Za-z0-9_]+$",
|
||
"description": "Secret to create or replace."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Ownership scope and write-only value for the secret. A workspace secret may instead send description or unredacted alone, without a value.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/SetSecretRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The existing secret value was replaced, or its metadata was updated in place.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/SetSecretResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"201": {
|
||
"description": "The secret was created.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/SetSecretResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteSecret",
|
||
"summary": "Delete Secret",
|
||
"description": "Delete a workspace or caller-owned personal secret without reading or returning its stored value. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["Secrets"],
|
||
"parameters": [
|
||
{
|
||
"name": "name",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Secret to delete.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"pattern": "^[A-Za-z0-9_]+$",
|
||
"description": "Secret to delete."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace the request is authorized against. A workspace secret is deleted from it; a personal secret is deleted for the caller in all of their workspaces.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace the request is authorized against. A workspace secret is deleted from it; a personal secret is deleted for the caller in all of their workspaces."
|
||
}
|
||
},
|
||
{
|
||
"name": "scope",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Whether the secret belongs to the workspace or to the caller. A personal secret belongs to the caller across every workspace, not to one workspace.",
|
||
"schema": {
|
||
"type": "string",
|
||
"enum": ["workspace", "personal"],
|
||
"description": "Whether the secret belongs to the workspace or to the caller. A personal secret belongs to the caller across every workspace, not to one workspace."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The secret was deleted.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/DeleteSecretResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/meta": {
|
||
"get": {
|
||
"operationId": "getApiMeta",
|
||
"summary": "Get API Capabilities",
|
||
"description": "Report whether v2 is available, whether the calling API key is personal or workspace-scoped, and when it expires. Requires a valid key.",
|
||
"tags": ["Meta"],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Availability and lifecycle facts about the calling key.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GetApiMetaResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/workflow-mcp-servers": {
|
||
"get": {
|
||
"operationId": "listWorkflowMcpServers",
|
||
"summary": "List Workflow MCP Servers",
|
||
"description": "List the MCP servers a workspace *publishes*. These serve deployed workflows as tools to outside MCP clients, which is the opposite direction from `GET /api/v2/mcp-servers` — that lists external servers Sim calls. Each entry carries the endpoint clients connect to and the tool names it exposes; those names are gathered under a 2,000-tool budget shared across the page, so on a page of unusually large servers the trailing entries can list fewer names than they publish. Read one server's full inventory with `GET /api/v2/workflow-mcp-servers/{serverId}/tools`. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace whose published MCP servers to list.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace whose published MCP servers to list."
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"schema": {
|
||
"default": "createdAt",
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"type": "string",
|
||
"enum": ["name", "createdAt", "updatedAt"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "desc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum workflow-MCP servers to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum workflow-MCP servers to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of published MCP servers.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListWorkflowMcpServersResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "createWorkflowMcpServer",
|
||
"summary": "Create Workflow MCP Server",
|
||
"description": "Publish a new MCP server for a workspace, optionally seeding it with workflows to expose as tools. Every workflow named in `workflowIds` must already be deployed. Setting `isPublic` lets any MCP client holding the server URL execute the workflows it publishes without a Sim API key. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["MCP Servers"],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "A new workspace-published MCP server and the workflows it exposes.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateWorkflowMcpServerRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"201": {
|
||
"description": "The published MCP server.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateWorkflowMcpServerResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/workflow-mcp-servers/{serverId}": {
|
||
"get": {
|
||
"operationId": "getWorkflowMcpServer",
|
||
"summary": "Get Workflow MCP Server",
|
||
"description": "Read one published MCP server. The list is the only other place this state is published, so a caller holding a server id would otherwise have to page the collection and filter client-side. The tools it publishes are on its `tools` sub-resource. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "serverId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique workflow-MCP server identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique workflow-MCP server identifier."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The MCP server.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GetWorkflowMcpServerResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"patch": {
|
||
"operationId": "updateWorkflowMcpServer",
|
||
"summary": "Update Workflow MCP Server",
|
||
"description": "Rename, re-describe, or change the public visibility of a published MCP server. Merge-patch shaped: an omitted key is unchanged and `description: null` clears the description. Publishing and unpublishing the workflows it serves are separate operations on its `tools` sub-resource. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "serverId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique workflow-MCP server identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique workflow-MCP server identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Merge-patch body for a published MCP server.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateWorkflowMcpServerRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The updated MCP server.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UpdateWorkflowMcpServerResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"delete": {
|
||
"operationId": "deleteWorkflowMcpServer",
|
||
"summary": "Delete Workflow MCP Server",
|
||
"description": "Unpublish an MCP server. Every tool it served stops answering and connected clients lose the endpoint. The workflows themselves are untouched — their own deployments stay live and executable through the workflow API. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "serverId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique workflow-MCP server identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique workflow-MCP server identifier."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The MCP server was unpublished.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/DeleteWorkflowMcpServerResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/workflow-mcp-servers/{serverId}/tools": {
|
||
"get": {
|
||
"operationId": "listWorkflowMcpTools",
|
||
"summary": "List Workflow MCP Tools",
|
||
"description": "Every tool a server publishes, tool-name ordered. The server list reports tool *names* only, so this is where a caller reads the `workflowId` that `DELETE /api/v2/workflow-mcp-servers/{serverId}/tools/{workflowId}` addresses. Returned in one page rather than paged — so `nextCursor` is always null — and capped at 2,000 tools, which is far above any real server's inventory. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "serverId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique workflow-MCP server identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique workflow-MCP server identifier."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The tools this server publishes.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListWorkflowMcpToolsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
},
|
||
"post": {
|
||
"operationId": "deployWorkflowMcpTool",
|
||
"summary": "Publish Workflow As MCP Tool",
|
||
"description": "Publish a deployed workflow as a tool on an MCP server. The tool's input schema is generated from the deployed workflow's input format, so the workflow must already be deployed. Idempotent per workflow: a server carries at most one tool per workflow, so a repeat call replaces the existing tool and answers `200` with `updated: true` rather than conflicting. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "serverId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique workflow-MCP server identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique workflow-MCP server identifier."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "The workflow to publish and the tool metadata MCP clients see.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/DeployWorkflowMcpToolRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The published tool.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/DeployWorkflowMcpToolResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"413": {
|
||
"$ref": "#/components/responses/PayloadTooLarge"
|
||
},
|
||
"415": {
|
||
"$ref": "#/components/responses/UnsupportedMediaType"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/workflow-mcp-servers/{serverId}/tools/{workflowId}": {
|
||
"delete": {
|
||
"operationId": "undeployWorkflowMcpTool",
|
||
"summary": "Unpublish Workflow MCP Tool",
|
||
"description": "Remove a workflow from an MCP server. Addressed by workflow rather than by tool identifier, because a server carries at most one live tool per workflow. The workflow's own deployment is untouched. A workspace API key is rejected with `403`; use a personal API key.",
|
||
"tags": ["MCP Servers"],
|
||
"parameters": [
|
||
{
|
||
"name": "serverId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Unique workflow-MCP server identifier.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Unique workflow-MCP server identifier."
|
||
}
|
||
},
|
||
{
|
||
"name": "workflowId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Workflow published as a tool on this server.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Workflow published as a tool on this server."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The tool was removed.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/UndeployWorkflowMcpToolResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"409": {
|
||
"$ref": "#/components/responses/Conflict"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/blocks": {
|
||
"get": {
|
||
"operationId": "listBlocks",
|
||
"summary": "List Blocks",
|
||
"description": "List the blocks available in a workspace, built-in and workspace-deployed alike, discriminated by `source`. Availability is caller-specific: the workspace’s integration allowlist, the organization’s revealed preview blocks, and the deployment’s allowlist all narrow the result. Use `capability=trigger` for the blocks that can start a workflow. Summaries name their tools and operations by id — resolve one with Get Block or Get Tool.",
|
||
"tags": ["Catalog"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains."
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the block id, name, and description.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the block id, name, and description.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "category",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict to one toolbar category.",
|
||
"schema": {
|
||
"description": "Restrict to one toolbar category.",
|
||
"type": "string",
|
||
"enum": ["blocks", "tools", "triggers"]
|
||
}
|
||
},
|
||
{
|
||
"name": "capability",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict to blocks that can start a workflow — the `triggers` category, blocks declaring `triggerAllowed`, and blocks with trigger-mode fields.",
|
||
"schema": {
|
||
"description": "Restrict to blocks that can start a workflow — the `triggers` category, blocks declaring `triggerAllowed`, and blocks with trigger-mode fields.",
|
||
"type": "string",
|
||
"enum": ["trigger"]
|
||
}
|
||
},
|
||
{
|
||
"name": "source",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict to shipped blocks or to this workspace’s deployed custom blocks.",
|
||
"schema": {
|
||
"description": "Restrict to shipped blocks or to this workspace’s deployed custom blocks.",
|
||
"type": "string",
|
||
"enum": ["builtin", "custom"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"schema": {
|
||
"default": "id",
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"type": "string",
|
||
"enum": ["id", "name", "category"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "asc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum blocks to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum blocks to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of blocks available in the workspace.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListBlocksResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/blocks/{blockId}": {
|
||
"get": {
|
||
"operationId": "getBlock",
|
||
"summary": "Get Block",
|
||
"description": "Read one block’s full configuration shape: its fields and their conditions, its operations with the tool each runs, every tool’s parameters and outputs, and its triggers. An unversioned base type resolves to the newest version this caller can see — `confluence` answers with `confluence_v2` — and the returned `id` is always the resolved one, matching Get Tool. A block this caller cannot see answers 404, identically to one that does not exist.",
|
||
"tags": ["Catalog"],
|
||
"parameters": [
|
||
{
|
||
"name": "blockId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Block type identifier. An unversioned base type resolves to the newest version, and the response echoes the resolved id.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Block type identifier. An unversioned base type resolves to the newest version, and the response echoes the resolved id."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The block.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GetBlockResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/tools": {
|
||
"get": {
|
||
"operationId": "listTools",
|
||
"summary": "List Tools",
|
||
"description": "List the built-in tools available in a workspace. Built-in tools only: a workspace’s MCP tools are discovered per server on List MCP Server Tools, and its code-backed custom tools are on List Custom Tools. A tool is available when a block the caller can see exposes it, so the same allowlist and visibility rules as List Blocks apply.",
|
||
"tags": ["Catalog"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains."
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the tool id, name, and description.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the tool id, name, and description.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
},
|
||
{
|
||
"name": "hostedApiKey",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict to tools by how their API key is supplied.",
|
||
"schema": {
|
||
"description": "Restrict to tools by how their API key is supplied.",
|
||
"type": "string",
|
||
"enum": ["always", "conditional", "none"]
|
||
}
|
||
},
|
||
{
|
||
"name": "oauthProvider",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Restrict to tools that authenticate against this OAuth service.",
|
||
"schema": {
|
||
"description": "Restrict to tools that authenticate against this OAuth service.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
}
|
||
},
|
||
{
|
||
"name": "sortBy",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"schema": {
|
||
"default": "id",
|
||
"description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
|
||
"type": "string",
|
||
"enum": ["id", "name"]
|
||
}
|
||
},
|
||
{
|
||
"name": "sortOrder",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Sort direction.",
|
||
"schema": {
|
||
"default": "asc",
|
||
"description": "Sort direction.",
|
||
"type": "string",
|
||
"enum": ["asc", "desc"]
|
||
}
|
||
},
|
||
{
|
||
"name": "limit",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Maximum tools to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"schema": {
|
||
"default": 50,
|
||
"description": "Maximum tools to return per page. Must be a whole number from 1 to 100. Defaults to 50.",
|
||
"type": "integer",
|
||
"minimum": 1,
|
||
"maximum": 100
|
||
}
|
||
},
|
||
{
|
||
"name": "cursor",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"schema": {
|
||
"description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "A page of built-in tools available in the workspace.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListToolsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/tools/{toolId}": {
|
||
"get": {
|
||
"operationId": "getTool",
|
||
"summary": "Get Tool",
|
||
"description": "Read one built-in tool’s declared parameters and outputs. A name that is itself a registered id answers as that exact tool; a name that is not resolves to the newest version of its family. The returned `id` is always the one that answered, so a caller can see which version it got. A tool the workspace’s visible blocks do not expose answers `404`, identically to one that does not exist.",
|
||
"tags": ["Catalog"],
|
||
"parameters": [
|
||
{
|
||
"name": "toolId",
|
||
"in": "path",
|
||
"required": true,
|
||
"description": "Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id."
|
||
}
|
||
},
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains."
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The tool.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/GetToolResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v2/connector-types": {
|
||
"get": {
|
||
"operationId": "listConnectorTypes",
|
||
"summary": "List Connector Types",
|
||
"description": "List every knowledge-base connector type and the source configuration each accepts. Two properties of a config field decide how its value is sent and are not inferable from the rest: a field with `multi: true` stores a `string[]` rather than a `string`, and a `canonicalParamId` links a picker field to a manual-entry field that write the SAME configuration key — send exactly one of the pair, keyed by `canonicalParamId` rather than by the field's own `id`. The bounded set is returned in one page; `nextCursor` is always null.",
|
||
"tags": ["Catalog"],
|
||
"parameters": [
|
||
{
|
||
"name": "workspaceId",
|
||
"in": "query",
|
||
"required": true,
|
||
"description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains."
|
||
}
|
||
},
|
||
{
|
||
"name": "search",
|
||
"in": "query",
|
||
"required": false,
|
||
"description": "Case-insensitive substring match against the connector name.",
|
||
"schema": {
|
||
"description": "Case-insensitive substring match against the connector name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "The connector-type catalog.",
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"$ref": "#/components/headers/X-RateLimit-Limit"
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"$ref": "#/components/headers/X-RateLimit-Remaining"
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"$ref": "#/components/headers/X-RateLimit-Reset"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ListConnectorTypesResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"$ref": "#/components/responses/BadRequest"
|
||
},
|
||
"401": {
|
||
"$ref": "#/components/responses/Unauthorized"
|
||
},
|
||
"403": {
|
||
"$ref": "#/components/responses/Forbidden"
|
||
},
|
||
"404": {
|
||
"$ref": "#/components/responses/NotFound"
|
||
},
|
||
"429": {
|
||
"$ref": "#/components/responses/RateLimited"
|
||
},
|
||
"500": {
|
||
"$ref": "#/components/responses/InternalError"
|
||
},
|
||
"503": {
|
||
"$ref": "#/components/responses/ServiceUnavailable"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"components": {
|
||
"securitySchemes": {
|
||
"apiKey": {
|
||
"type": "apiKey",
|
||
"in": "header",
|
||
"name": "X-API-Key",
|
||
"description": "Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description."
|
||
}
|
||
},
|
||
"headers": {
|
||
"X-RateLimit-Limit": {
|
||
"description": "Maximum requests allowed in the current window.",
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"title": "Rate limit",
|
||
"description": "Maximum requests allowed in the current window."
|
||
}
|
||
},
|
||
"X-RateLimit-Remaining": {
|
||
"description": "Requests remaining in the current window.",
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"title": "Rate limit remaining",
|
||
"description": "Requests remaining in the current window."
|
||
}
|
||
},
|
||
"X-RateLimit-Reset": {
|
||
"description": "ISO 8601 timestamp when the current rate-limit window resets.",
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"title": "Rate limit reset",
|
||
"description": "ISO 8601 timestamp when the current rate-limit window resets."
|
||
}
|
||
},
|
||
"Retry-After": {
|
||
"description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
|
||
"schema": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"title": "Retry after",
|
||
"description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
|
||
}
|
||
},
|
||
"X-Run-Id": {
|
||
"description": "Identifier assigned to the workflow run.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"title": "Run identifier",
|
||
"description": "Identifier assigned to the workflow run."
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"BadRequest": {
|
||
"description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "BAD_REQUEST",
|
||
"message": "Invalid request"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"Unauthorized": {
|
||
"description": "The API key is missing or invalid.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "UNAUTHORIZED",
|
||
"message": "API key required"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"Forbidden": {
|
||
"description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "FORBIDDEN",
|
||
"message": "Insufficient workspace permissions",
|
||
"details": {
|
||
"code": "INSUFFICIENT_WORKSPACE_ROLE"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"NotFound": {
|
||
"description": "The requested resource was not found.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "NOT_FOUND",
|
||
"message": "Not found"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"Conflict": {
|
||
"description": "The request conflicts with current resource state.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "CONFLICT",
|
||
"message": "API key name already exists"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"PayloadTooLarge": {
|
||
"description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "PAYLOAD_TOO_LARGE",
|
||
"message": "Request body is too large"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"UnsupportedMediaType": {
|
||
"description": "The request uses an unsupported media type.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "UNSUPPORTED_MEDIA_TYPE",
|
||
"message": "Request body must be sent as application/json"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"RateLimited": {
|
||
"description": "The caller exceeded the request rate limit.",
|
||
"headers": {
|
||
"Retry-After": {
|
||
"$ref": "#/components/headers/Retry-After"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "RATE_LIMITED",
|
||
"message": "API rate limit exceeded",
|
||
"details": {
|
||
"retryAfter": "2026-01-01T00:00:30.000Z"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"InternalError": {
|
||
"description": "An unexpected server error occurred.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "INTERNAL_ERROR",
|
||
"message": "Internal server error"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"ServiceUnavailable": {
|
||
"description": "A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.",
|
||
"headers": {
|
||
"Retry-After": {
|
||
"$ref": "#/components/headers/Retry-After"
|
||
}
|
||
},
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/V2Error"
|
||
},
|
||
"example": {
|
||
"error": {
|
||
"code": "SERVICE_UNAVAILABLE",
|
||
"message": "Service temporarily unavailable"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"schemas": {
|
||
"V2Error": {
|
||
"type": "object",
|
||
"properties": {
|
||
"error": {
|
||
"type": "object",
|
||
"properties": {
|
||
"code": {
|
||
"type": "string",
|
||
"description": "Stable machine-readable error code."
|
||
},
|
||
"message": {
|
||
"type": "string",
|
||
"description": "Human-readable explanation of the error."
|
||
},
|
||
"details": {
|
||
"description": "Structured error details. On a `403` whose cause a caller can act on, this carries a `code` from a closed set:\n- `INSUFFICIENT_WORKSPACE_ROLE` — The caller has access to the workspace but its role is below the one this operation requires.\n- `PERSONAL_API_KEYS_DISABLED` — The workspace's organization does not allow personal API keys. Use a workspace API key.\n- `WORKSPACE_KEY_OPERATION_NOT_PERMITTED` — This operation is not available to a workspace-scoped API key. Use a personal API key.\n- `PRINCIPAL_KIND_NOT_PERMITTED` — This operation does not accept the caller’s kind of API key.\n- `ORGANIZATION_MEMBERSHIP_REQUIRED` — The caller is not a member of the organization it named.\n- `ORGANIZATION_ADMIN_REQUIRED` — The caller is a member of the organization but not an admin or owner.\n- `ENTERPRISE_PLAN_REQUIRED` — The organization has no active enterprise subscription.\n- `ORGANIZATION_PLAN_REQUIRED` — The organization has no active organization subscription (Pro for Teams, Max for Teams, or Enterprise).\n- `AUDIT_LOGS_DISABLED` — Audit logging is not enabled for this deployment.\n- `SKILL_EDITOR_ACCESS_REQUIRED` — The caller can write in the workspace but is not an editor of this skill.\n- `SECRET_ADMIN_ACCESS_REQUIRED` — The caller can write in the workspace but is not an admin of this secret. Ask a workspace admin, or someone holding admin on the secret, to grant access or set the value.\n- `WORKSPACE_RESOURCE_LIMIT_REACHED` — The workspace already holds the maximum number of resources of this kind. Delete one, or contact Sim to raise the limit; the message names the ceiling.\n- `PUBLIC_SHARING_NOT_ALLOWED` — The workspace's organization does not permit sharing this resource publicly. An organization admin controls the policy.\n- `CREDENTIAL_ADMIN_ACCESS_REQUIRED` — The caller can reach the workspace but cannot administer this credential.\n- `MCP_SERVER_URL_NOT_ALLOWED` — The supplied MCP server URL is outside the allowed domains or resolves to an internal address.\n- `WORKSPACE_PLAN_CAPABILITY_REQUIRED` — The workspace's plan does not include a capability this request depends on. The message names the capability; upgrading the workspace's plan is the remedy.\n- `CHAT_AUTH_MODE_NOT_PERMITTED` — The workspace's permission group does not allow the chat authentication mode the request selected. A mode already saved on the deployment may still be re-saved; changing to a disallowed one cannot.\n- `CONNECTOR_MANAGED_RESOURCE_READ_ONLY` — This resource is managed by a knowledge base connector and cannot be edited directly. Change it at the source and re-sync, or exclude the document from the connector."
|
||
}
|
||
},
|
||
"required": ["code", "message"],
|
||
"additionalProperties": false,
|
||
"description": "Canonical error details."
|
||
}
|
||
},
|
||
"required": ["error"],
|
||
"additionalProperties": false,
|
||
"title": "v2 error response",
|
||
"description": "Canonical error envelope returned by the public v2 API.",
|
||
"examples": [
|
||
{
|
||
"error": {
|
||
"code": "BAD_REQUEST",
|
||
"message": "The request is invalid."
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2Workspace": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Unique workspace identifier."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Workspace display name."
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "Workspace color as a hexadecimal color value."
|
||
},
|
||
"logoUrl": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Workspace logo URL, or null when none is configured."
|
||
},
|
||
"memberCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of effective members, including inherited organization administrators."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the workspace was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the workspace was last updated."
|
||
}
|
||
},
|
||
"required": ["id", "name", "color", "logoUrl", "memberCount", "createdAt", "updatedAt"],
|
||
"additionalProperties": false,
|
||
"title": "Workspace",
|
||
"description": "Public metadata for an accessible workspace."
|
||
},
|
||
"ListWorkspacesResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2Workspace"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List workspaces response",
|
||
"description": "Public metadata for workspaces available to the API key.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "Engineering",
|
||
"color": "#33C482",
|
||
"logoUrl": null,
|
||
"memberCount": 14,
|
||
"createdAt": "2026-01-15T10:30:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"GetWorkspaceResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2Workspace"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Get workspace response",
|
||
"description": "Public metadata for one workspace.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "Engineering",
|
||
"color": "#33C482",
|
||
"logoUrl": null,
|
||
"memberCount": 14,
|
||
"createdAt": "2026-01-15T10:30:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2WorkspaceMember": {
|
||
"type": "object",
|
||
"properties": {
|
||
"email": {
|
||
"type": "string",
|
||
"format": "email",
|
||
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
|
||
"description": "Member email address and public member identifier."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Member display name."
|
||
},
|
||
"image": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Member profile image URL, or null when absent."
|
||
},
|
||
"role": {
|
||
"type": "string",
|
||
"enum": ["admin", "write", "read"],
|
||
"description": "Effective role in the workspace."
|
||
},
|
||
"isExternal": {
|
||
"type": "boolean",
|
||
"description": "Whether the member belongs to a different organization than the workspace. True only for an explicitly granted member whose own organization differs; inherited organization-administrator access is always reported as false, so this does not detect every outside caller."
|
||
},
|
||
"joinedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when access was granted."
|
||
}
|
||
},
|
||
"required": ["email", "name", "image", "role", "isExternal", "joinedAt"],
|
||
"additionalProperties": false,
|
||
"title": "Workspace member",
|
||
"description": "An effective workspace member and their public access role."
|
||
},
|
||
"ListWorkspaceMembersResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2WorkspaceMember"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List workspace members response",
|
||
"description": "A cursor-paginated page of effective workspace members.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"email": "jane@example.com",
|
||
"name": "Jane Smith",
|
||
"image": null,
|
||
"role": "admin",
|
||
"isExternal": false,
|
||
"joinedAt": "2026-01-15T10:30:00.000Z"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"V2McpServer": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique server identifier derived from the workspace and endpoint URL."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Server display name."
|
||
},
|
||
"description": {
|
||
"description": "Optional server description.",
|
||
"type": "string"
|
||
},
|
||
"transport": {
|
||
"default": "streamable-http",
|
||
"description": "Transport used to communicate with the server.",
|
||
"type": "string",
|
||
"enum": ["streamable-http"]
|
||
},
|
||
"authType": {
|
||
"description": "Authentication method used by the server.",
|
||
"type": "string",
|
||
"enum": ["none", "headers", "oauth"]
|
||
},
|
||
"url": {
|
||
"description": "Server endpoint URL.",
|
||
"type": "string"
|
||
},
|
||
"timeout": {
|
||
"description": "Per-request timeout in milliseconds.",
|
||
"type": "number"
|
||
},
|
||
"retries": {
|
||
"description": "Number of retries attempted per request.",
|
||
"type": "number"
|
||
},
|
||
"enabled": {
|
||
"type": "boolean",
|
||
"description": "Whether the server tools are available to workflows."
|
||
},
|
||
"connectionStatus": {
|
||
"description": "Result of the most recent connection attempt. Registration and re-registration establish no connection — the auth-type probe they may send does not count as one — so a server begins, and returns to, `disconnected` until a tool discovery runs.",
|
||
"type": "string",
|
||
"enum": ["connected", "disconnected", "error"]
|
||
},
|
||
"lastError": {
|
||
"description": "Message from the most recent failed connection, or null when absent. A re-registration clears it, since the configuration it described no longer applies.",
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
]
|
||
},
|
||
"toolCount": {
|
||
"description": "Number of tools discovered on the server.",
|
||
"type": "number"
|
||
},
|
||
"lastToolsRefresh": {
|
||
"description": "ISO 8601 timestamp of the most recent tool-list refresh.",
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
"lastConnected": {
|
||
"description": "ISO 8601 timestamp of the most recent successful connection. Absent until the server completes one; registering a server does not set it.",
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
"createdAt": {
|
||
"description": "ISO 8601 timestamp when the server was registered.",
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
"updatedAt": {
|
||
"description": "ISO 8601 timestamp when the server was last updated.",
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
"oauthClientId": {
|
||
"description": "Pre-registered OAuth client identifier, when configured.",
|
||
"type": "string"
|
||
},
|
||
"hasHeaders": {
|
||
"type": "boolean",
|
||
"description": "Whether any request headers are configured."
|
||
},
|
||
"headerNames": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"description": "Configured header name."
|
||
},
|
||
"description": "Names of configured request headers. Header values are never returned."
|
||
},
|
||
"hasOauthClientSecret": {
|
||
"type": "boolean",
|
||
"description": "Whether an OAuth client secret is stored. The value is never returned."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"name",
|
||
"transport",
|
||
"enabled",
|
||
"createdAt",
|
||
"updatedAt",
|
||
"hasHeaders",
|
||
"headerNames",
|
||
"hasOauthClientSecret"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "MCP server",
|
||
"description": "Public MCP server configuration without write-only credential values."
|
||
},
|
||
"ListMcpServersResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2McpServer"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List MCP servers response",
|
||
"description": "MCP servers registered in the workspace.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "mcp-3f7a9c21",
|
||
"name": "Docs server",
|
||
"description": "Internal documentation tools",
|
||
"transport": "streamable-http",
|
||
"authType": "headers",
|
||
"url": "https://mcp.example.com/sse",
|
||
"timeout": 30000,
|
||
"retries": 3,
|
||
"enabled": true,
|
||
"connectionStatus": "connected",
|
||
"lastError": null,
|
||
"toolCount": 7,
|
||
"lastToolsRefresh": "2026-06-20T14:02:11.000Z",
|
||
"lastConnected": "2026-06-20T14:02:11.000Z",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z",
|
||
"hasHeaders": true,
|
||
"headerNames": ["Authorization"],
|
||
"hasOauthClientSecret": false
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"CreateMcpServerResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2McpServer"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Create MCP server response",
|
||
"description": "The registered MCP server without write-only credentials.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "mcp-3f7a9c21",
|
||
"name": "Docs server",
|
||
"description": "Internal documentation tools",
|
||
"transport": "streamable-http",
|
||
"authType": "headers",
|
||
"url": "https://mcp.example.com/sse",
|
||
"timeout": 30000,
|
||
"retries": 3,
|
||
"enabled": true,
|
||
"connectionStatus": "disconnected",
|
||
"lastError": null,
|
||
"toolCount": 0,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z",
|
||
"hasHeaders": true,
|
||
"headerNames": ["Authorization"],
|
||
"hasOauthClientSecret": false
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"CreateMcpServerRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace in which to register the server."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Server display name."
|
||
},
|
||
"description": {
|
||
"description": "Optional server description.",
|
||
"type": "string",
|
||
"maxLength": 2000
|
||
},
|
||
"transport": {
|
||
"description": "Transport used to communicate with the server. Applied server-side as `streamable-http` when omitted on create.",
|
||
"default": "streamable-http",
|
||
"type": "string",
|
||
"enum": ["streamable-http"]
|
||
},
|
||
"url": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 2048,
|
||
"description": "Absolute HTTP or HTTPS endpoint URL without `{{ENV_VAR}}` references. It determines server identity and is immutable: delete and recreate the server to change endpoints."
|
||
},
|
||
"authType": {
|
||
"description": "Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method.",
|
||
"type": "string",
|
||
"enum": ["none", "headers", "oauth"]
|
||
},
|
||
"headers": {
|
||
"description": "Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat.",
|
||
"writeOnly": true,
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"additionalProperties": {
|
||
"type": "string",
|
||
"description": "Header value sent to the MCP server."
|
||
}
|
||
},
|
||
"timeout": {
|
||
"description": "Per-request timeout in milliseconds. Applied server-side as 30000 when omitted on create.",
|
||
"default": 30000,
|
||
"type": "integer",
|
||
"minimum": 1000,
|
||
"maximum": 300000
|
||
},
|
||
"retries": {
|
||
"description": "Number of retries per request. Applied server-side as 3 when omitted on create.",
|
||
"default": 3,
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 10
|
||
},
|
||
"enabled": {
|
||
"description": "Whether the server tools are available to workflows. Applied server-side as true when omitted on create.",
|
||
"default": true,
|
||
"type": "boolean"
|
||
},
|
||
"oauthClientId": {
|
||
"description": "Pre-registered OAuth client identifier. Changing it on update revokes the stored OAuth grant and forces reauthorization.",
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"maxLength": 512
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
]
|
||
},
|
||
"oauthClientSecret": {
|
||
"description": "Write-only pre-registered OAuth client secret. Sending it on update as null or a new value revokes the stored OAuth grant and forces reauthorization, as does switching away from OAuth authentication.",
|
||
"writeOnly": true,
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"maxLength": 2048
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"required": ["workspaceId", "name", "url"],
|
||
"additionalProperties": false,
|
||
"title": "Create MCP server request",
|
||
"description": "Configuration for a new MCP server.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "Docs server",
|
||
"url": "https://mcp.example.com/sse",
|
||
"authType": "headers",
|
||
"headers": {
|
||
"Authorization": "Bearer YOUR_TOKEN"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"GetMcpServerResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2McpServer"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Get MCP server response",
|
||
"description": "One MCP server without write-only credentials.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "mcp-3f7a9c21",
|
||
"name": "Docs server",
|
||
"description": "Internal documentation tools",
|
||
"transport": "streamable-http",
|
||
"authType": "headers",
|
||
"url": "https://mcp.example.com/sse",
|
||
"timeout": 30000,
|
||
"retries": 3,
|
||
"enabled": true,
|
||
"connectionStatus": "connected",
|
||
"lastError": null,
|
||
"toolCount": 7,
|
||
"lastToolsRefresh": "2026-06-20T14:02:11.000Z",
|
||
"lastConnected": "2026-06-20T14:02:11.000Z",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z",
|
||
"hasHeaders": true,
|
||
"headerNames": ["Authorization"],
|
||
"hasOauthClientSecret": false
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateMcpServerResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2McpServer"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Update MCP server response",
|
||
"description": "The updated MCP server.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "mcp-3f7a9c21",
|
||
"name": "Docs server",
|
||
"description": "Internal documentation tools",
|
||
"transport": "streamable-http",
|
||
"authType": "headers",
|
||
"url": "https://mcp.example.com/sse",
|
||
"timeout": 30000,
|
||
"retries": 3,
|
||
"enabled": false,
|
||
"connectionStatus": "connected",
|
||
"lastError": null,
|
||
"toolCount": 7,
|
||
"lastToolsRefresh": "2026-06-20T14:02:11.000Z",
|
||
"lastConnected": "2026-06-20T14:02:11.000Z",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z",
|
||
"hasHeaders": true,
|
||
"headerNames": ["Authorization"],
|
||
"hasOauthClientSecret": false
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateMcpServerRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the MCP server."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Server display name."
|
||
},
|
||
"description": {
|
||
"description": "Optional server description.",
|
||
"type": "string",
|
||
"maxLength": 2000
|
||
},
|
||
"transport": {
|
||
"description": "Transport used to communicate with the server. Applied server-side as `streamable-http` when omitted on create.",
|
||
"default": "streamable-http",
|
||
"type": "string",
|
||
"enum": ["streamable-http"]
|
||
},
|
||
"url": {
|
||
"description": "Immutable server URL. When provided, it must equal the current URL; use delete and create to change endpoints.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 2048
|
||
},
|
||
"authType": {
|
||
"description": "Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method.",
|
||
"type": "string",
|
||
"enum": ["none", "headers", "oauth"]
|
||
},
|
||
"headers": {
|
||
"description": "Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat.",
|
||
"writeOnly": true,
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"additionalProperties": {
|
||
"type": "string",
|
||
"description": "Header value sent to the MCP server."
|
||
}
|
||
},
|
||
"timeout": {
|
||
"description": "Per-request timeout in milliseconds. Applied server-side as 30000 when omitted on create.",
|
||
"default": 30000,
|
||
"type": "integer",
|
||
"minimum": 1000,
|
||
"maximum": 300000
|
||
},
|
||
"retries": {
|
||
"description": "Number of retries per request. Applied server-side as 3 when omitted on create.",
|
||
"default": 3,
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 10
|
||
},
|
||
"enabled": {
|
||
"description": "Whether the server tools are available to workflows. Applied server-side as true when omitted on create.",
|
||
"default": true,
|
||
"type": "boolean"
|
||
},
|
||
"oauthClientId": {
|
||
"description": "Pre-registered OAuth client identifier. Changing it on update revokes the stored OAuth grant and forces reauthorization.",
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"maxLength": 512
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
]
|
||
},
|
||
"oauthClientSecret": {
|
||
"description": "Write-only pre-registered OAuth client secret. Sending it on update as null or a new value revokes the stored OAuth grant and forces reauthorization, as does switching away from OAuth authentication.",
|
||
"writeOnly": true,
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"maxLength": 2048
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update MCP server request",
|
||
"description": "MCP server fields to change; omitted fields retain their stored values.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"enabled": false
|
||
}
|
||
]
|
||
},
|
||
"V2McpServerDeleteData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifier of the deleted MCP server."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether the server was deleted."
|
||
}
|
||
},
|
||
"required": ["id", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Delete MCP server data",
|
||
"description": "MCP server deletion acknowledgement."
|
||
},
|
||
"DeleteMcpServerResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2McpServerDeleteData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Delete MCP server response",
|
||
"description": "Acknowledgement that the MCP server was deleted.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "mcp-3f7a9c21",
|
||
"deleted": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2McpTool": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Tool name, as the MCP server reports it."
|
||
},
|
||
"description": {
|
||
"description": "Tool description reported by the server.",
|
||
"type": "string"
|
||
},
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"const": "object",
|
||
"description": "JSON Schema type of the argument object. MCP requires `object`."
|
||
},
|
||
"properties": {
|
||
"description": "Argument schemas keyed by argument name.",
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Server-defined JSON Schema for one tool argument."
|
||
}
|
||
},
|
||
"required": {
|
||
"description": "Names of the arguments the tool requires.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"description": "Name of a required argument."
|
||
}
|
||
}
|
||
},
|
||
"required": ["type"],
|
||
"additionalProperties": {
|
||
"description": "Additional JSON Schema keyword reported by the server."
|
||
},
|
||
"description": "JSON Schema for the tool's arguments, as reported by the server."
|
||
},
|
||
"serverId": {
|
||
"type": "string",
|
||
"description": "Identifier of the MCP server exposing the tool."
|
||
},
|
||
"serverName": {
|
||
"type": "string",
|
||
"description": "Display name of the MCP server exposing the tool."
|
||
}
|
||
},
|
||
"required": ["name", "inputSchema", "serverId", "serverName"],
|
||
"additionalProperties": false,
|
||
"title": "MCP tool",
|
||
"description": "A tool exposed by a registered MCP server."
|
||
},
|
||
"ListMcpServerToolsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2McpTool"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List MCP server tools response",
|
||
"description": "Tools exposed by the MCP server.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"name": "search_docs",
|
||
"description": "Search the internal documentation",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"query": {
|
||
"type": "string",
|
||
"description": "Search terms"
|
||
}
|
||
},
|
||
"required": ["query"]
|
||
},
|
||
"serverId": "mcp-3f7a9c21",
|
||
"serverName": "Docs server"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"V2SkillSummary": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Kebab-case name that agents use to reference the skill."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"description": "One-line summary of when the skill applies."
|
||
},
|
||
"readOnly": {
|
||
"type": "boolean",
|
||
"description": "Whether this is a built-in skill that cannot be modified or deleted."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the skill was created. Built-in skills report the Unix epoch."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the skill was last updated. Built-in skills report the Unix epoch."
|
||
}
|
||
},
|
||
"required": ["id", "name", "description", "readOnly", "createdAt", "updatedAt"],
|
||
"additionalProperties": false,
|
||
"title": "Skill summary",
|
||
"description": "Public summary metadata for a workspace or built-in skill."
|
||
},
|
||
"ListSkillsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2SkillSummary"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List skills response",
|
||
"description": "Skill summaries available in the workspace.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "V1StGXR8Z5jdHi6BmyT",
|
||
"name": "refund-policy",
|
||
"description": "How support should handle refund requests",
|
||
"readOnly": false,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"V2Skill": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Kebab-case name that agents use to reference the skill."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"description": "One-line summary of when the skill applies."
|
||
},
|
||
"readOnly": {
|
||
"type": "boolean",
|
||
"description": "Whether this is a built-in skill that cannot be modified or deleted."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the skill was created. Built-in skills report the Unix epoch."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the skill was last updated. Built-in skills report the Unix epoch."
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"description": "Skill body containing the instructions given to the agent."
|
||
}
|
||
},
|
||
"required": ["id", "name", "description", "readOnly", "createdAt", "updatedAt", "content"],
|
||
"additionalProperties": false,
|
||
"title": "Skill",
|
||
"description": "A workspace or built-in skill including its instruction body."
|
||
},
|
||
"CreateSkillResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2Skill"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Create skill response",
|
||
"description": "The created skill including its content.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "V1StGXR8Z5jdHi6BmyT",
|
||
"name": "refund-policy",
|
||
"description": "How support should handle refund requests",
|
||
"readOnly": false,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z",
|
||
"content": "# Refund policy\n\nAlways check the order date first."
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"CreateSkillRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace in which to create the skill."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 64,
|
||
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
|
||
"description": "Kebab-case name, unique within the workspace and not reserved by a built-in skill."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 1024,
|
||
"description": "One-line summary of when the skill applies."
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 50000,
|
||
"description": "Skill body containing the instructions given to the agent."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "name", "description", "content"],
|
||
"additionalProperties": false,
|
||
"title": "Create skill request",
|
||
"description": "Definition of a new skill.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"name": "refund-policy",
|
||
"description": "How support should handle refund requests",
|
||
"content": "# Refund policy\n\nAlways check the order date first."
|
||
}
|
||
]
|
||
},
|
||
"GetSkillResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2Skill"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Get skill response",
|
||
"description": "One skill including its full content.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "V1StGXR8Z5jdHi6BmyT",
|
||
"name": "refund-policy",
|
||
"description": "How support should handle refund requests",
|
||
"readOnly": false,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z",
|
||
"content": "# Refund policy\n\nAlways check the order date first."
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateSkillResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2Skill"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Update skill response",
|
||
"description": "The updated skill including its full content.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "V1StGXR8Z5jdHi6BmyT",
|
||
"name": "refund-policy",
|
||
"description": "Updated refund guidance",
|
||
"readOnly": false,
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z",
|
||
"content": "# Refund policy\n\nAlways check the order date first."
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateSkillRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the skill."
|
||
},
|
||
"name": {
|
||
"description": "New kebab-case skill name.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 64,
|
||
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
|
||
},
|
||
"description": {
|
||
"description": "New one-line summary of when the skill applies.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 1024
|
||
},
|
||
"content": {
|
||
"description": "Replacement skill body.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 50000
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update skill request",
|
||
"description": "Skill fields to change; at least one editable field is required.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"description": "Updated refund guidance"
|
||
}
|
||
]
|
||
},
|
||
"V2SkillDeleteData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifier of the deleted skill."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether the skill was deleted."
|
||
}
|
||
},
|
||
"required": ["id", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Delete skill data",
|
||
"description": "Skill deletion acknowledgement."
|
||
},
|
||
"DeleteSkillResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2SkillDeleteData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Delete skill response",
|
||
"description": "Acknowledgement that the skill was deleted.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "V1StGXR8Z5jdHi6BmyT",
|
||
"deleted": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2SkillEditor": {
|
||
"type": "object",
|
||
"properties": {
|
||
"email": {
|
||
"type": "string",
|
||
"format": "email",
|
||
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
|
||
"description": "Email address of the skill editor."
|
||
},
|
||
"name": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Display name of the skill editor."
|
||
},
|
||
"image": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Profile image URL of the skill editor."
|
||
},
|
||
"isWorkspaceAdmin": {
|
||
"type": "boolean",
|
||
"description": "Whether editor access is derived from workspace administration."
|
||
}
|
||
},
|
||
"required": ["email", "name", "image", "isWorkspaceAdmin"],
|
||
"additionalProperties": false,
|
||
"title": "Skill editor",
|
||
"description": "Public identity fields for a user who can edit a skill."
|
||
},
|
||
"ListSkillEditorsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2SkillEditor"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List skill editors response",
|
||
"description": "Public identity fields for users who can edit the skill.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"email": "jane@example.com",
|
||
"name": "Jane Smith",
|
||
"image": null,
|
||
"isWorkspaceAdmin": false
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"GrantSkillEditorResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2SkillEditor"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Grant skill editor response",
|
||
"description": "Public identity fields for the editor.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"email": "jane@example.com",
|
||
"name": "Jane Smith",
|
||
"image": null,
|
||
"isWorkspaceAdmin": false
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"GrantSkillEditorRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the skill."
|
||
},
|
||
"email": {
|
||
"type": "string",
|
||
"format": "email",
|
||
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
|
||
"description": "Email address of a current workspace member."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "email"],
|
||
"additionalProperties": false,
|
||
"title": "Grant skill editor request",
|
||
"description": "Workspace scope and email of the member to grant.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"email": "jane@example.com"
|
||
}
|
||
]
|
||
},
|
||
"V2SkillEditorDeleteData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"email": {
|
||
"type": "string",
|
||
"format": "email",
|
||
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
|
||
"description": "Email address whose explicit editor grant was revoked."
|
||
},
|
||
"revoked": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether the explicit editor grant was revoked."
|
||
}
|
||
},
|
||
"required": ["email", "revoked"],
|
||
"additionalProperties": false,
|
||
"title": "Revoke skill editor data",
|
||
"description": "Skill editor revocation acknowledgement."
|
||
},
|
||
"RevokeSkillEditorResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2SkillEditorDeleteData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Revoke skill editor response",
|
||
"description": "Acknowledgement that the explicit editor grant was revoked.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"email": "jane@example.com",
|
||
"revoked": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2CustomTool": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique custom tool identifier."
|
||
},
|
||
"title": {
|
||
"type": "string",
|
||
"description": "Display title, unique within the workspace."
|
||
},
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"const": "function",
|
||
"description": "Function declaration discriminator."
|
||
},
|
||
"function": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Function name presented to the model."
|
||
},
|
||
"description": {
|
||
"description": "Optional explanation of what the function does.",
|
||
"type": "string"
|
||
},
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "JSON Schema type for the arguments, usually `object`."
|
||
},
|
||
"properties": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Caller-defined JSON Schema for one tool argument."
|
||
},
|
||
"description": "Caller-defined argument schemas keyed by argument name."
|
||
},
|
||
"required": {
|
||
"description": "Names of required arguments.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": ["type", "properties"],
|
||
"additionalProperties": {
|
||
"description": "Caller-defined extension value preserved by the public API."
|
||
},
|
||
"description": "JSON Schema describing the arguments accepted by the tool."
|
||
}
|
||
},
|
||
"required": ["name", "parameters"],
|
||
"additionalProperties": {
|
||
"description": "Caller-defined extension value preserved by the public API."
|
||
},
|
||
"description": "OpenAI-style function definition."
|
||
}
|
||
},
|
||
"required": ["type", "function"],
|
||
"additionalProperties": {
|
||
"description": "Caller-defined extension value preserved by the public API."
|
||
},
|
||
"description": "OpenAI-style function declaration describing the callable tool surface."
|
||
},
|
||
"code": {
|
||
"type": "string",
|
||
"description": "Tool implementation executed in the sandboxed function runtime."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the tool was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the tool was last updated."
|
||
}
|
||
},
|
||
"required": ["id", "title", "schema", "code", "createdAt", "updatedAt"],
|
||
"additionalProperties": false,
|
||
"title": "Custom tool",
|
||
"description": "A workspace custom tool and its callable function declaration."
|
||
},
|
||
"ListCustomToolsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2CustomTool"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List custom tools response",
|
||
"description": "Custom tools defined in the workspace.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "V1StGXR8Z5jdHi6BmyT",
|
||
"title": "lookup_order",
|
||
"schema": {
|
||
"type": "function",
|
||
"function": {
|
||
"name": "lookup_order",
|
||
"description": "Look up an order by id",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"orderId": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": ["orderId"]
|
||
}
|
||
}
|
||
},
|
||
"code": "return { ok: true }",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"CreateCustomToolResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2CustomTool"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Create custom tool response",
|
||
"description": "The created custom tool.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "V1StGXR8Z5jdHi6BmyT",
|
||
"title": "lookup_order",
|
||
"schema": {
|
||
"type": "function",
|
||
"function": {
|
||
"name": "lookup_order",
|
||
"description": "Look up an order by id",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"orderId": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": ["orderId"]
|
||
}
|
||
}
|
||
},
|
||
"code": "return { ok: true }",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"CreateCustomToolRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace in which to create the custom tool."
|
||
},
|
||
"title": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200,
|
||
"description": "Display title, unique within the workspace."
|
||
},
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"const": "function",
|
||
"description": "Function declaration discriminator."
|
||
},
|
||
"function": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Function name presented to the model."
|
||
},
|
||
"description": {
|
||
"description": "Optional explanation of what the function does.",
|
||
"type": "string"
|
||
},
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "JSON Schema type for the arguments, usually `object`."
|
||
},
|
||
"properties": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Caller-defined JSON Schema for one tool argument."
|
||
},
|
||
"description": "Caller-defined argument schemas keyed by argument name."
|
||
},
|
||
"required": {
|
||
"description": "Names of required arguments.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": ["type", "properties"],
|
||
"additionalProperties": {
|
||
"description": "Caller-defined extension value preserved by the public API."
|
||
},
|
||
"description": "JSON Schema describing the arguments accepted by the tool."
|
||
}
|
||
},
|
||
"required": ["name", "parameters"],
|
||
"additionalProperties": {
|
||
"description": "Caller-defined extension value preserved by the public API."
|
||
},
|
||
"description": "OpenAI-style function definition."
|
||
}
|
||
},
|
||
"required": ["type", "function"],
|
||
"additionalProperties": {
|
||
"description": "Caller-defined extension value preserved by the public API."
|
||
},
|
||
"description": "OpenAI-style function declaration describing the callable tool surface."
|
||
},
|
||
"code": {
|
||
"type": "string",
|
||
"maxLength": 100000,
|
||
"description": "Tool implementation executed in the sandboxed function runtime."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "title", "schema", "code"],
|
||
"additionalProperties": false,
|
||
"title": "Create custom tool request",
|
||
"description": "Definition and implementation of a new custom tool.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"title": "lookup_order",
|
||
"schema": {
|
||
"type": "function",
|
||
"function": {
|
||
"name": "lookup_order",
|
||
"description": "Look up an order by id",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"orderId": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": ["orderId"]
|
||
}
|
||
}
|
||
},
|
||
"code": "return { ok: true }"
|
||
}
|
||
]
|
||
},
|
||
"GetCustomToolResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2CustomTool"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Get custom tool response",
|
||
"description": "One custom tool.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "V1StGXR8Z5jdHi6BmyT",
|
||
"title": "lookup_order",
|
||
"schema": {
|
||
"type": "function",
|
||
"function": {
|
||
"name": "lookup_order",
|
||
"description": "Look up an order by id",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"orderId": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": ["orderId"]
|
||
}
|
||
}
|
||
},
|
||
"code": "return { ok: true }",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateCustomToolResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2CustomTool"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Update custom tool response",
|
||
"description": "The updated custom tool.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "V1StGXR8Z5jdHi6BmyT",
|
||
"title": "lookup_order",
|
||
"schema": {
|
||
"type": "function",
|
||
"function": {
|
||
"name": "lookup_order",
|
||
"description": "Look up an order by id",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"orderId": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": ["orderId"]
|
||
}
|
||
}
|
||
},
|
||
"code": "return { ok: false }",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateCustomToolRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that owns the custom tool."
|
||
},
|
||
"title": {
|
||
"description": "New display title for the tool.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 200
|
||
},
|
||
"schema": {
|
||
"description": "Replacement function declaration.",
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"const": "function",
|
||
"description": "Function declaration discriminator."
|
||
},
|
||
"function": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Function name presented to the model."
|
||
},
|
||
"description": {
|
||
"description": "Optional explanation of what the function does.",
|
||
"type": "string"
|
||
},
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "JSON Schema type for the arguments, usually `object`."
|
||
},
|
||
"properties": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Caller-defined JSON Schema for one tool argument."
|
||
},
|
||
"description": "Caller-defined argument schemas keyed by argument name."
|
||
},
|
||
"required": {
|
||
"description": "Names of required arguments.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": ["type", "properties"],
|
||
"additionalProperties": {
|
||
"description": "Caller-defined extension value preserved by the public API."
|
||
},
|
||
"description": "JSON Schema describing the arguments accepted by the tool."
|
||
}
|
||
},
|
||
"required": ["name", "parameters"],
|
||
"additionalProperties": {
|
||
"description": "Caller-defined extension value preserved by the public API."
|
||
},
|
||
"description": "OpenAI-style function definition."
|
||
}
|
||
},
|
||
"required": ["type", "function"],
|
||
"additionalProperties": {
|
||
"description": "Caller-defined extension value preserved by the public API."
|
||
}
|
||
},
|
||
"code": {
|
||
"description": "Replacement tool implementation.",
|
||
"type": "string",
|
||
"maxLength": 100000
|
||
}
|
||
},
|
||
"required": ["workspaceId"],
|
||
"additionalProperties": false,
|
||
"title": "Update custom tool request",
|
||
"description": "Custom tool fields to change; at least one editable field is required.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"code": "return { ok: false }"
|
||
}
|
||
]
|
||
},
|
||
"V2CustomToolDeleteData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifier of the deleted custom tool."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether the custom tool was deleted."
|
||
}
|
||
},
|
||
"required": ["id", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Delete custom tool data",
|
||
"description": "Custom tool deletion acknowledgement."
|
||
},
|
||
"DeleteCustomToolResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2CustomToolDeleteData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Delete custom tool response",
|
||
"description": "Acknowledgement that the custom tool was deleted.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "V1StGXR8Z5jdHi6BmyT",
|
||
"deleted": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2Credential": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique credential identifier."
|
||
},
|
||
"type": {
|
||
"type": "string",
|
||
"enum": ["oauth", "service_account"],
|
||
"description": "Authenticated connection type."
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"description": "Credential display name."
|
||
},
|
||
"description": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Optional credential description."
|
||
},
|
||
"providerId": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Integration provider authenticated by this credential."
|
||
},
|
||
"accountId": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Linked account identifier for OAuth credentials."
|
||
},
|
||
"hasServiceAccountKey": {
|
||
"type": "boolean",
|
||
"description": "Whether a service-account payload is stored. Its contents are never returned."
|
||
},
|
||
"role": {
|
||
"type": "string",
|
||
"enum": ["admin", "member"],
|
||
"description": "Caller role for the credential."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the credential was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the credential was last updated."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"type",
|
||
"displayName",
|
||
"description",
|
||
"providerId",
|
||
"accountId",
|
||
"hasServiceAccountKey",
|
||
"role",
|
||
"createdAt",
|
||
"updatedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Credential",
|
||
"description": "Public authenticated-connection metadata without secret material."
|
||
},
|
||
"ListCredentialsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2Credential"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List credentials response",
|
||
"description": "Credential metadata visible to the caller.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"type": "service_account",
|
||
"displayName": "Zoom service account",
|
||
"description": null,
|
||
"providerId": "zoom-service-account",
|
||
"accountId": null,
|
||
"hasServiceAccountKey": true,
|
||
"role": "admin",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"V2CredentialProvider": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"const": "oauth",
|
||
"description": "Browser-based OAuth connection method."
|
||
},
|
||
"serviceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Stable credential-provider identifier."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Credential provider display name."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 1000,
|
||
"description": "Credential provider description."
|
||
},
|
||
"providerFamily": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Owning provider family identifier."
|
||
},
|
||
"available": {
|
||
"type": "boolean",
|
||
"description": "Whether this caller can connect the provider in the current deployment."
|
||
},
|
||
"supportsReconnect": {
|
||
"type": "boolean",
|
||
"description": "Whether existing credentials for this service can be reconnected."
|
||
},
|
||
"authorizationOptions": {
|
||
"minItems": 1,
|
||
"maxItems": 10,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"providerId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Exact OAuth provider identifier accepted by the connection endpoint."
|
||
},
|
||
"label": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Human-readable authorization-server label."
|
||
}
|
||
},
|
||
"required": ["providerId", "label"],
|
||
"additionalProperties": false
|
||
},
|
||
"description": "Authorization servers available for this OAuth service."
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"serviceId",
|
||
"name",
|
||
"description",
|
||
"providerFamily",
|
||
"available",
|
||
"supportsReconnect",
|
||
"authorizationOptions"
|
||
],
|
||
"additionalProperties": false
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"const": "service_account",
|
||
"description": "Direct service-account credential method."
|
||
},
|
||
"serviceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Stable credential-provider identifier."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Credential provider display name."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 1000,
|
||
"description": "Credential provider description."
|
||
},
|
||
"providerFamily": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Owning provider family identifier."
|
||
},
|
||
"available": {
|
||
"type": "boolean",
|
||
"description": "Whether this caller can connect the provider in the current deployment."
|
||
},
|
||
"providerId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Exact service-account provider ID accepted by credential creation."
|
||
},
|
||
"docsUrl": {
|
||
"type": "string",
|
||
"format": "uri",
|
||
"description": "Setup guide for the provider."
|
||
},
|
||
"helpText": {
|
||
"description": "Provider-specific setup guidance.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 2000
|
||
},
|
||
"requiresClientGeneratedCredentialId": {
|
||
"type": "boolean",
|
||
"description": "Whether the caller must generate and submit the credential ID before setup."
|
||
},
|
||
"fields": {
|
||
"minItems": 1,
|
||
"maxItems": 20,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Exact create-body field name."
|
||
},
|
||
"label": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Human-readable field label."
|
||
},
|
||
"placeholder": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 1000,
|
||
"description": "Suggested input placeholder."
|
||
},
|
||
"required": {
|
||
"type": "boolean",
|
||
"description": "Whether the field is required for the selected flow."
|
||
},
|
||
"secret": {
|
||
"type": "boolean",
|
||
"description": "Whether the submitted field is write-only secret material."
|
||
},
|
||
"multiline": {
|
||
"type": "boolean",
|
||
"description": "Whether the field is intended for multi-line input."
|
||
},
|
||
"requiredForAuthMethods": {
|
||
"description": "Authentication methods for which this field is required.",
|
||
"minItems": 1,
|
||
"maxItems": 10,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 64
|
||
}
|
||
},
|
||
"options": {
|
||
"description": "Fixed values accepted by a selector field.",
|
||
"minItems": 1,
|
||
"maxItems": 20,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"value": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Submitted option value."
|
||
},
|
||
"label": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Human-readable option label."
|
||
}
|
||
},
|
||
"required": ["value", "label"],
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"hint": {
|
||
"description": "Provider-specific setup guidance.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 2000
|
||
}
|
||
},
|
||
"required": ["id", "label", "placeholder", "required", "secret", "multiline"],
|
||
"additionalProperties": false
|
||
},
|
||
"description": "Create-body fields accepted by this provider. Secret fields are write-only."
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"serviceId",
|
||
"name",
|
||
"description",
|
||
"providerFamily",
|
||
"available",
|
||
"providerId",
|
||
"docsUrl",
|
||
"requiresClientGeneratedCredentialId",
|
||
"fields"
|
||
],
|
||
"additionalProperties": false
|
||
}
|
||
],
|
||
"title": "Credential Provider",
|
||
"description": "An OAuth or service-account connection method available to a workspace."
|
||
},
|
||
"ListCredentialProvidersResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2CredentialProvider"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List credential providers response",
|
||
"description": "OAuth and service-account connection methods.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"type": "oauth",
|
||
"serviceId": "salesforce",
|
||
"name": "Salesforce",
|
||
"description": "Connect to Salesforce CRM data and operations.",
|
||
"providerFamily": "salesforce",
|
||
"available": true,
|
||
"supportsReconnect": true,
|
||
"authorizationOptions": [
|
||
{
|
||
"providerId": "salesforce",
|
||
"label": "Production"
|
||
},
|
||
{
|
||
"providerId": "salesforce-sandbox",
|
||
"label": "Sandbox"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"type": "service_account",
|
||
"serviceId": "zoom-service-account",
|
||
"providerId": "zoom-service-account",
|
||
"name": "Zoom server-to-server app",
|
||
"description": "Connect Zoom with a server-to-server app.",
|
||
"providerFamily": "zoom",
|
||
"available": true,
|
||
"docsUrl": "https://docs.sim.ai/integrations/zoom-service-account",
|
||
"requiresClientGeneratedCredentialId": false,
|
||
"fields": [
|
||
{
|
||
"id": "clientId",
|
||
"label": "Client ID",
|
||
"placeholder": "Paste the client ID",
|
||
"required": true,
|
||
"secret": false,
|
||
"multiline": false
|
||
},
|
||
{
|
||
"id": "clientSecret",
|
||
"label": "Client secret",
|
||
"placeholder": "Paste the client secret",
|
||
"required": true,
|
||
"secret": true,
|
||
"multiline": false
|
||
},
|
||
{
|
||
"id": "orgId",
|
||
"label": "Account ID",
|
||
"placeholder": "Paste the account ID",
|
||
"required": true,
|
||
"secret": false,
|
||
"multiline": false
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"CreateServiceAccountCredentialResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2Credential"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Create service-account credential response",
|
||
"description": "Verified credential metadata without secret material.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"type": "service_account",
|
||
"displayName": "Zoom service account",
|
||
"description": null,
|
||
"providerId": "zoom-service-account",
|
||
"accountId": null,
|
||
"hasServiceAccountKey": true,
|
||
"role": "admin",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"CreateServiceAccountCredentialRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that will own the credential."
|
||
},
|
||
"type": {
|
||
"type": "string",
|
||
"const": "service_account",
|
||
"description": "Service-account credential discriminator."
|
||
},
|
||
"providerId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Exact service-account provider ID returned by provider discovery."
|
||
},
|
||
"displayName": {
|
||
"description": "Optional name; providers may derive one from the verified account identity.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"description": {
|
||
"description": "Optional credential description.",
|
||
"type": "string",
|
||
"maxLength": 500
|
||
},
|
||
"id": {
|
||
"description": "Required only when provider discovery requests a client-generated ID.",
|
||
"type": "string",
|
||
"format": "uuid",
|
||
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
|
||
},
|
||
"credentials": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 131072,
|
||
"description": "Write-only JSON object string containing the fields declared by credential-provider discovery.",
|
||
"writeOnly": true
|
||
}
|
||
},
|
||
"required": ["workspaceId", "type", "providerId", "credentials"],
|
||
"additionalProperties": false,
|
||
"title": "Create service-account credential request",
|
||
"description": "Provider identifier, optional display metadata, and a write-only JSON object string containing the fields declared by provider discovery."
|
||
},
|
||
"V2CredentialConnectionAuthorization": {
|
||
"type": "object",
|
||
"properties": {
|
||
"authorizationUrl": {
|
||
"type": "string",
|
||
"format": "uri",
|
||
"description": "Short-lived Sim browser URL that starts the OAuth authorization flow."
|
||
},
|
||
"expiresAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the connection link expires."
|
||
}
|
||
},
|
||
"required": ["authorizationUrl", "expiresAt"],
|
||
"additionalProperties": false,
|
||
"title": "Credential Connection Authorization",
|
||
"description": "A short-lived browser entrypoint for an OAuth connection flow."
|
||
},
|
||
"CreateCredentialConnectionResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2CredentialConnectionAuthorization"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Create credential connection response",
|
||
"description": "Short-lived Sim browser entrypoint and its expiry.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize?draftId=draft-123",
|
||
"expiresAt": "2026-06-20T14:17:11.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"CreateCredentialConnectionBody": {
|
||
"anyOf": [
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace that will own the credential."
|
||
},
|
||
"providerId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Exact OAuth provider ID returned by credential-provider discovery."
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Name shown for the new credential in Sim."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "providerId", "displayName"],
|
||
"additionalProperties": false
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace expected to own the credential."
|
||
},
|
||
"credentialId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Existing OAuth credential to reconnect in place."
|
||
}
|
||
},
|
||
"required": ["workspaceId", "credentialId"],
|
||
"additionalProperties": false
|
||
}
|
||
],
|
||
"title": "Create credential connection body",
|
||
"description": "For a new connection, provide providerId and displayName. For a reconnect, provide only credentialId; the existing display name is preserved."
|
||
},
|
||
"V2CredentialDeleteData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Disconnected credential identifier."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether the credential was disconnected."
|
||
}
|
||
},
|
||
"required": ["id", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Delete credential data",
|
||
"description": "Credential disconnection acknowledgement."
|
||
},
|
||
"DeleteCredentialResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2CredentialDeleteData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Disconnect credential response",
|
||
"description": "Acknowledgement that the credential was disconnected.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"deleted": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2SecretWithValue": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"pattern": "^[A-Za-z0-9_]+$",
|
||
"description": "Secret name containing only letters, numbers, and underscores."
|
||
},
|
||
"scope": {
|
||
"type": "string",
|
||
"enum": ["workspace", "personal"],
|
||
"description": "Whether the secret belongs to the workspace or to the caller. A personal secret belongs to the caller across every workspace, not to one workspace."
|
||
},
|
||
"description": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "What the secret is for, as set on the workspace secret. Always null for a personal secret, which has no shared audience."
|
||
},
|
||
"unredacted": {
|
||
"type": "boolean",
|
||
"description": "Whether the workspace secret opts out of redaction, so its value appears in plaintext in run logs and model-visible content. Always false for a personal secret."
|
||
},
|
||
"role": {
|
||
"type": "string",
|
||
"enum": ["admin", "member"],
|
||
"description": "Caller role for the secret."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the secret was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the secret was last updated."
|
||
},
|
||
"value": {
|
||
"description": "The stored secret value. Present only when the workspace secret is marked visible (unredacted); omitted for every other secret.",
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"name",
|
||
"scope",
|
||
"description",
|
||
"unredacted",
|
||
"role",
|
||
"createdAt",
|
||
"updatedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Secret metadata with visible value",
|
||
"description": "Secret metadata; the stored value is included only for a workspace secret marked visible (unredacted)."
|
||
},
|
||
"ListSecretsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2SecretWithValue"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List secrets response",
|
||
"description": "Secret metadata visible to the caller; visible (unredacted) workspace secrets carry their value.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"name": "STRIPE_API_KEY",
|
||
"scope": "workspace",
|
||
"description": "Production billing key — rotate quarterly.",
|
||
"unredacted": false,
|
||
"role": "admin",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
},
|
||
{
|
||
"name": "STAGING_BASE_URL",
|
||
"scope": "workspace",
|
||
"description": "Staging environment base URL.",
|
||
"unredacted": true,
|
||
"role": "member",
|
||
"createdAt": "2026-06-03T11:30:00.000Z",
|
||
"updatedAt": "2026-06-21T08:45:09.000Z",
|
||
"value": "https://staging.example.com"
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"V2Secret": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"pattern": "^[A-Za-z0-9_]+$",
|
||
"description": "Secret name containing only letters, numbers, and underscores."
|
||
},
|
||
"scope": {
|
||
"type": "string",
|
||
"enum": ["workspace", "personal"],
|
||
"description": "Whether the secret belongs to the workspace or to the caller. A personal secret belongs to the caller across every workspace, not to one workspace."
|
||
},
|
||
"description": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "What the secret is for, as set on the workspace secret. Always null for a personal secret, which has no shared audience."
|
||
},
|
||
"unredacted": {
|
||
"type": "boolean",
|
||
"description": "Whether the workspace secret opts out of redaction, so its value appears in plaintext in run logs and model-visible content. Always false for a personal secret."
|
||
},
|
||
"role": {
|
||
"type": "string",
|
||
"enum": ["admin", "member"],
|
||
"description": "Caller role for the secret."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the secret was created."
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
|
||
"description": "ISO 8601 timestamp when the secret was last updated."
|
||
}
|
||
},
|
||
"required": [
|
||
"name",
|
||
"scope",
|
||
"description",
|
||
"unredacted",
|
||
"role",
|
||
"createdAt",
|
||
"updatedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Secret metadata",
|
||
"description": "Public secret metadata without the stored secret value."
|
||
},
|
||
"SetSecretResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2Secret"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Set secret response",
|
||
"description": "Metadata for the created or replaced secret without its value.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"name": "STRIPE_API_KEY",
|
||
"scope": "workspace",
|
||
"description": "Production billing key — rotate quarterly.",
|
||
"unredacted": false,
|
||
"role": "admin",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"SetSecretRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace the request is authorized against. A workspace secret is written to it; a personal secret is written to the caller and is available in all of their workspaces."
|
||
},
|
||
"scope": {
|
||
"type": "string",
|
||
"enum": ["workspace", "personal"],
|
||
"description": "Whether the secret belongs to the workspace or to the caller. A personal secret belongs to the caller across every workspace, not to one workspace."
|
||
},
|
||
"value": {
|
||
"description": "Write-only secret value. It is never returned. Omit it on a workspace secret to change description or unredacted alone, leaving the stored value untouched; the secret must already exist. Always required for a personal secret, which carries no other writable field.",
|
||
"writeOnly": true,
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 65536
|
||
},
|
||
"description": {
|
||
"description": "What the secret is for, shown to teammates. Workspace scope only — sending it for a personal secret is rejected. Omit it to leave an existing description untouched; send null or an empty string to clear one.",
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"maxLength": 500
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
]
|
||
},
|
||
"unredacted": {
|
||
"description": "Opt the workspace secret out of redaction: its value then appears in plaintext in run logs, model-visible content, and files, including publicly shared log links. Workspace scope only — sending it for a personal secret is rejected. Omit it to leave the current setting untouched.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["workspaceId", "scope"],
|
||
"additionalProperties": false,
|
||
"title": "Set secret request",
|
||
"description": "Ownership scope and write-only value for the secret. A workspace secret may instead send description or unredacted alone, without a value.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"scope": "workspace",
|
||
"value": "YOUR_SECRET_VALUE"
|
||
},
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"scope": "workspace",
|
||
"unredacted": false
|
||
}
|
||
]
|
||
},
|
||
"V2SecretDeleteData": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"pattern": "^[A-Za-z0-9_]+$",
|
||
"description": "Secret name containing only letters, numbers, and underscores."
|
||
},
|
||
"scope": {
|
||
"type": "string",
|
||
"enum": ["workspace", "personal"],
|
||
"description": "Whether the secret belongs to the workspace or to the caller. A personal secret belongs to the caller across every workspace, not to one workspace."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether the secret was deleted."
|
||
}
|
||
},
|
||
"required": ["name", "scope", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Delete secret data",
|
||
"description": "Secret deletion acknowledgement without the stored value."
|
||
},
|
||
"DeleteSecretResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2SecretDeleteData"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Delete secret response",
|
||
"description": "Acknowledgement that the secret was deleted.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"name": "STRIPE_API_KEY",
|
||
"scope": "workspace",
|
||
"deleted": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2Meta": {
|
||
"type": "object",
|
||
"properties": {
|
||
"v2Enabled": {
|
||
"type": "boolean",
|
||
"description": "Whether this API version is available. This is true when the endpoint is served."
|
||
},
|
||
"keyType": {
|
||
"type": "string",
|
||
"enum": ["personal", "workspace"],
|
||
"description": "Whether the calling key carries the full authority of its owner across their workspaces, or is scoped to one workspace."
|
||
},
|
||
"expiresAt": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "ISO 8601 timestamp when the calling key expires, or null when it never does."
|
||
}
|
||
},
|
||
"required": ["v2Enabled", "keyType", "expiresAt"],
|
||
"additionalProperties": false,
|
||
"title": "API capabilities",
|
||
"description": "API availability and lifecycle facts about the calling API key."
|
||
},
|
||
"GetApiMetaResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2Meta"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "API capabilities response",
|
||
"description": "API availability, key type, and expiry for the calling key.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"v2Enabled": true,
|
||
"keyType": "personal",
|
||
"expiresAt": null
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"WorkflowMcpServerListItem": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique workflow-MCP server identifier."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Server display name, shown to connecting MCP clients."
|
||
},
|
||
"description": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Optional server description, or null when unset."
|
||
},
|
||
"isPublic": {
|
||
"type": "boolean",
|
||
"description": "Whether the server answers MCP clients without a Sim API key."
|
||
},
|
||
"mcpServerUrl": {
|
||
"type": "string",
|
||
"description": "Endpoint an MCP client connects to. Published here so callers never build it.",
|
||
"examples": ["https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2"]
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the server was created.",
|
||
"format": "date-time"
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the server was last modified.",
|
||
"format": "date-time"
|
||
},
|
||
"toolCount": {
|
||
"type": "integer",
|
||
"minimum": 0,
|
||
"maximum": 9007199254740991,
|
||
"description": "Number of workflows published as tools."
|
||
},
|
||
"toolNames": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Tool names this server publishes, alphabetically ordered."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"name",
|
||
"description",
|
||
"isPublic",
|
||
"mcpServerUrl",
|
||
"createdAt",
|
||
"updatedAt",
|
||
"toolCount",
|
||
"toolNames"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Workflow MCP server list item",
|
||
"description": "A published MCP server together with the tool names it exposes."
|
||
},
|
||
"ListWorkflowMcpServersResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/WorkflowMcpServerListItem"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
},
|
||
"toolNamesTruncated": {
|
||
"type": "boolean",
|
||
"description": "Whether `toolCount` and `toolNames` under-report. The names are gathered for the whole page under one ceiling, so a page whose servers publish more tools than that ceiling between them reports only part of each server's inventory. Read one server's tool inventory and check that response's own `truncated`, which reports the same ceiling applied to a single server — only an untruncated response is the authoritative set. Unrelated to `nextCursor`, which is how this list says there are further servers."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor", "toolNamesTruncated"],
|
||
"additionalProperties": false,
|
||
"title": "List workflow MCP servers response",
|
||
"description": "A cursor-paginated page of published MCP servers.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"name": "Support agents",
|
||
"description": "Ticket triage and escalation workflows.",
|
||
"isPublic": false,
|
||
"mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"createdAt": "2026-06-12T10:30:00.000Z",
|
||
"updatedAt": "2026-06-12T10:30:00.000Z",
|
||
"toolCount": 1,
|
||
"toolNames": ["triage_ticket"]
|
||
}
|
||
],
|
||
"nextCursor": null,
|
||
"toolNamesTruncated": false
|
||
}
|
||
]
|
||
},
|
||
"WorkflowMcpServer": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique workflow-MCP server identifier."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Server display name, shown to connecting MCP clients."
|
||
},
|
||
"description": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Optional server description, or null when unset."
|
||
},
|
||
"isPublic": {
|
||
"type": "boolean",
|
||
"description": "Whether the server answers MCP clients without a Sim API key."
|
||
},
|
||
"mcpServerUrl": {
|
||
"type": "string",
|
||
"description": "Endpoint an MCP client connects to. Published here so callers never build it.",
|
||
"examples": ["https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2"]
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the server was created.",
|
||
"format": "date-time"
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the server was last modified.",
|
||
"format": "date-time"
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"name",
|
||
"description",
|
||
"isPublic",
|
||
"mcpServerUrl",
|
||
"createdAt",
|
||
"updatedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Workflow MCP server",
|
||
"description": "A workspace-published MCP server exposing deployed workflows as tools."
|
||
},
|
||
"CreateWorkflowMcpServerResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/WorkflowMcpServer"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Create workflow MCP server response",
|
||
"description": "The published MCP server.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"name": "Support agents",
|
||
"description": "Ticket triage and escalation workflows.",
|
||
"isPublic": false,
|
||
"mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"createdAt": "2026-06-12T10:30:00.000Z",
|
||
"updatedAt": "2026-06-12T10:30:00.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"CreateWorkflowMcpServerRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workspaceId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128,
|
||
"description": "Workspace in which to publish the server."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Server display name, shown to connecting MCP clients."
|
||
},
|
||
"description": {
|
||
"description": "Optional server description.",
|
||
"type": "string",
|
||
"maxLength": 2000
|
||
},
|
||
"isPublic": {
|
||
"description": "Whether the server answers MCP clients without a Sim API key. Defaults to false — a public server executes the workflows it publishes for anyone holding its URL.",
|
||
"default": false,
|
||
"type": "boolean"
|
||
},
|
||
"workflowIds": {
|
||
"description": "Deployed workflows to publish as tools on the new server.",
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"required": ["workspaceId", "name"],
|
||
"additionalProperties": false,
|
||
"title": "Create workflow MCP server request",
|
||
"description": "A new workspace-published MCP server and the workflows it exposes.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
|
||
"name": "Support agents",
|
||
"workflowIds": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
|
||
}
|
||
]
|
||
},
|
||
"GetWorkflowMcpServerResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/WorkflowMcpServer"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Get workflow MCP server response",
|
||
"description": "A single published MCP server.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"name": "Support agents",
|
||
"description": "Ticket triage and escalation workflows.",
|
||
"isPublic": false,
|
||
"mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"createdAt": "2026-06-12T10:30:00.000Z",
|
||
"updatedAt": "2026-06-12T10:30:00.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"WorkflowMcpToolListItem": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique tool identifier."
|
||
},
|
||
"serverId": {
|
||
"type": "string",
|
||
"description": "Server that publishes this tool."
|
||
},
|
||
"workflowId": {
|
||
"type": "string",
|
||
"description": "Workflow this tool executes."
|
||
},
|
||
"toolName": {
|
||
"type": "string",
|
||
"description": "Name an MCP client calls. Derived from the supplied name or the workflow name, normalized to the MCP tool-name grammar."
|
||
},
|
||
"toolDescription": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Description shown to MCP clients."
|
||
},
|
||
"mcpServerUrl": {
|
||
"type": "string",
|
||
"description": "Endpoint an MCP client connects to."
|
||
},
|
||
"apiEndpoint": {
|
||
"type": "string",
|
||
"description": "Sim execution endpoint this tool calls through."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the tool was created.",
|
||
"format": "date-time"
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the tool was last modified.",
|
||
"format": "date-time"
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"serverId",
|
||
"workflowId",
|
||
"toolName",
|
||
"toolDescription",
|
||
"mcpServerUrl",
|
||
"apiEndpoint",
|
||
"createdAt",
|
||
"updatedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Workflow MCP tool list item",
|
||
"description": "A tool a server publishes, as returned by a read."
|
||
},
|
||
"ListWorkflowMcpToolsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/WorkflowMcpToolListItem"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
|
||
},
|
||
"truncated": {
|
||
"type": "boolean",
|
||
"description": "Whether this inventory was cut short by the server-side ceiling on how many tools one response may carry. `nextCursor` is null either way — this list takes no `cursor`, so a truncated set cannot be paged past and this flag is the only way to tell a partial inventory from a complete one. A reconciling caller must not treat a truncated set as the full published inventory."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor", "truncated"],
|
||
"additionalProperties": false,
|
||
"title": "List workflow MCP tools response",
|
||
"description": "The tools a published MCP server exposes.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "wfmcptool_01J8ZK3QW4M6X2R9T7B5C0V3",
|
||
"serverId": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
|
||
"toolName": "triage_ticket",
|
||
"toolDescription": "Execute Ticket triage workflow",
|
||
"mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"apiEndpoint": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute",
|
||
"createdAt": "2026-06-12T10:30:00.000Z",
|
||
"updatedAt": "2026-06-12T10:30:00.000Z"
|
||
}
|
||
],
|
||
"nextCursor": null,
|
||
"truncated": false
|
||
}
|
||
]
|
||
},
|
||
"UpdateWorkflowMcpServerResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/WorkflowMcpServer"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Update workflow MCP server response",
|
||
"description": "The updated MCP server.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"name": "Support agents",
|
||
"description": "Ticket triage and escalation workflows.",
|
||
"isPublic": true,
|
||
"mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"createdAt": "2026-06-12T10:30:00.000Z",
|
||
"updatedAt": "2026-06-12T10:30:00.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateWorkflowMcpServerRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Server display name, shown to connecting MCP clients."
|
||
},
|
||
"description": {
|
||
"description": "New server description, or null to clear it.",
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"maxLength": 2000
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
]
|
||
},
|
||
"isPublic": {
|
||
"description": "Whether the server answers MCP clients without a Sim API key.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"additionalProperties": false,
|
||
"title": "Update workflow MCP server request",
|
||
"description": "Merge-patch body for a published MCP server.",
|
||
"examples": [
|
||
{
|
||
"isPublic": true
|
||
}
|
||
]
|
||
},
|
||
"DeleteWorkflowMcpServerResult": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifier of the unpublished server."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether the server was unpublished."
|
||
}
|
||
},
|
||
"required": ["id", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Delete workflow MCP server result",
|
||
"description": "Unpublish acknowledgement."
|
||
},
|
||
"DeleteWorkflowMcpServerResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/DeleteWorkflowMcpServerResult"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Delete workflow MCP server response",
|
||
"description": "Acknowledgement that the MCP server was unpublished.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"deleted": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"WorkflowMcpTool": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Unique tool identifier."
|
||
},
|
||
"serverId": {
|
||
"type": "string",
|
||
"description": "Server that publishes this tool."
|
||
},
|
||
"workflowId": {
|
||
"type": "string",
|
||
"description": "Workflow this tool executes."
|
||
},
|
||
"toolName": {
|
||
"type": "string",
|
||
"description": "Name an MCP client calls. Derived from the supplied name or the workflow name, normalized to the MCP tool-name grammar."
|
||
},
|
||
"toolDescription": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Description shown to MCP clients."
|
||
},
|
||
"mcpServerUrl": {
|
||
"type": "string",
|
||
"description": "Endpoint an MCP client connects to."
|
||
},
|
||
"apiEndpoint": {
|
||
"type": "string",
|
||
"description": "Sim execution endpoint this tool calls through."
|
||
},
|
||
"updated": {
|
||
"type": "boolean",
|
||
"description": "False when the workflow was newly published on this server, true when an existing tool was replaced. Publishing is idempotent per workflow, so a repeat call answers 200 with true rather than conflicting."
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the tool was created.",
|
||
"format": "date-time"
|
||
},
|
||
"updatedAt": {
|
||
"type": "string",
|
||
"description": "ISO 8601 timestamp when the tool was last modified.",
|
||
"format": "date-time"
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"serverId",
|
||
"workflowId",
|
||
"toolName",
|
||
"toolDescription",
|
||
"mcpServerUrl",
|
||
"apiEndpoint",
|
||
"updated",
|
||
"createdAt",
|
||
"updatedAt"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Workflow MCP tool",
|
||
"description": "A deployed workflow published as a tool on a workflow-MCP server."
|
||
},
|
||
"DeployWorkflowMcpToolResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/WorkflowMcpTool"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Publish workflow as MCP tool response",
|
||
"description": "The published tool.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "wfmcptool_01J8ZK3QW4M6X2R9T7B5C0V3",
|
||
"serverId": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
|
||
"toolName": "triage_ticket",
|
||
"toolDescription": "Execute Ticket triage workflow",
|
||
"mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"apiEndpoint": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute",
|
||
"updated": false,
|
||
"createdAt": "2026-06-12T10:30:00.000Z",
|
||
"updatedAt": "2026-06-12T10:30:00.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"DeployWorkflowMcpToolRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"workflowId": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Deployed workflow to publish. The workflow must already be deployed."
|
||
},
|
||
"toolName": {
|
||
"description": "Name MCP clients call. Normalized to the MCP tool-name grammar, and derived from the workflow name when omitted.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 128
|
||
},
|
||
"toolDescription": {
|
||
"description": "Description shown to MCP clients. Derived from the workflow name when omitted.",
|
||
"type": "string",
|
||
"maxLength": 2000
|
||
},
|
||
"parameterDescriptions": {
|
||
"description": "Per-field description overrides applied to the schema generated from the deployed workflow inputs. A name matching no input field is ignored.",
|
||
"maxItems": 100,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "Input field of the deployed workflow to describe."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 2000,
|
||
"description": "Text MCP clients see for that field."
|
||
}
|
||
},
|
||
"required": ["name", "description"],
|
||
"additionalProperties": false
|
||
}
|
||
}
|
||
},
|
||
"required": ["workflowId"],
|
||
"additionalProperties": false,
|
||
"title": "Publish workflow as MCP tool request",
|
||
"description": "The workflow to publish and the tool metadata MCP clients see.",
|
||
"examples": [
|
||
{
|
||
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
|
||
"toolName": "triage_ticket"
|
||
}
|
||
]
|
||
},
|
||
"UndeployWorkflowMcpToolResult": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifier of the removed tool."
|
||
},
|
||
"serverId": {
|
||
"type": "string",
|
||
"description": "Server the tool was removed from."
|
||
},
|
||
"workflowId": {
|
||
"type": "string",
|
||
"description": "Workflow that is no longer published."
|
||
},
|
||
"deleted": {
|
||
"type": "boolean",
|
||
"const": true,
|
||
"description": "Whether the tool was removed."
|
||
}
|
||
},
|
||
"required": ["id", "serverId", "workflowId", "deleted"],
|
||
"additionalProperties": false,
|
||
"title": "Unpublish workflow MCP tool result",
|
||
"description": "Tool removal acknowledgement."
|
||
},
|
||
"UndeployWorkflowMcpToolResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/UndeployWorkflowMcpToolResult"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Unpublish workflow MCP tool response",
|
||
"description": "Acknowledgement that the tool was removed.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "wfmcptool_01J8ZK3QW4M6X2R9T7B5C0V3",
|
||
"serverId": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
|
||
"workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
|
||
"deleted": true
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateCredentialResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2Credential"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Update credential response",
|
||
"description": "Updated credential metadata without secret material.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
|
||
"type": "service_account",
|
||
"displayName": "Zoom service account",
|
||
"description": null,
|
||
"providerId": "zoom-service-account",
|
||
"accountId": null,
|
||
"hasServiceAccountKey": true,
|
||
"role": "admin",
|
||
"createdAt": "2026-06-01T09:14:00.000Z",
|
||
"updatedAt": "2026-06-20T14:02:11.000Z"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"UpdateCredentialRequest": {
|
||
"type": "object",
|
||
"properties": {
|
||
"displayName": {
|
||
"description": "New name shown for the credential in Sim.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"description": {
|
||
"description": "New credential description. Send null to clear the stored one.",
|
||
"anyOf": [
|
||
{
|
||
"type": "string",
|
||
"maxLength": 500
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
]
|
||
},
|
||
"serviceAccountJson": {
|
||
"description": "Write-only Google service-account JSON key.",
|
||
"writeOnly": true,
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 65536
|
||
},
|
||
"apiToken": {
|
||
"description": "Write-only provider API token.",
|
||
"writeOnly": true,
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 8192
|
||
},
|
||
"domain": {
|
||
"description": "Provider account domain.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 2048
|
||
},
|
||
"signingSecret": {
|
||
"description": "Write-only webhook signing secret.",
|
||
"writeOnly": true,
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 8192
|
||
},
|
||
"botToken": {
|
||
"description": "Write-only bot token.",
|
||
"writeOnly": true,
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 8192
|
||
},
|
||
"clientId": {
|
||
"description": "OAuth client identifier.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 512
|
||
},
|
||
"clientSecret": {
|
||
"description": "Write-only OAuth client secret.",
|
||
"writeOnly": true,
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 1024
|
||
},
|
||
"certificateId": {
|
||
"description": "Provider certificate mapping identifier.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 512
|
||
},
|
||
"orgId": {
|
||
"description": "Provider organization ID.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
},
|
||
"dataCenter": {
|
||
"description": "Provider data center.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 32
|
||
},
|
||
"authMethod": {
|
||
"description": "Provider authentication method.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 64
|
||
},
|
||
"privateKey": {
|
||
"description": "Write-only PEM private key.",
|
||
"writeOnly": true,
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 8192
|
||
},
|
||
"username": {
|
||
"description": "Provider run-as username.",
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255
|
||
}
|
||
},
|
||
"additionalProperties": false,
|
||
"title": "Update credential request",
|
||
"description": "Replacement display metadata and the write-only fields declared by provider discovery.",
|
||
"examples": [
|
||
{
|
||
"clientSecret": "YOUR_ROTATED_CLIENT_SECRET"
|
||
}
|
||
]
|
||
},
|
||
"V2BlockSummary": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Block type identifier, used as a workflow block’s `type`."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Display name."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"description": "One-line summary of what the block does."
|
||
},
|
||
"longDescription": {
|
||
"description": "Extended explanation, when the block has one.",
|
||
"type": "string"
|
||
},
|
||
"category": {
|
||
"type": "string",
|
||
"description": "Toolbar category: `blocks`, `tools`, or `triggers`."
|
||
},
|
||
"integrationType": {
|
||
"description": "Integration category, e.g. `communication`, `databases`.",
|
||
"type": "string"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"enum": ["builtin", "custom"],
|
||
"description": "Where the block comes from: `builtin` is the shipped registry, `custom` is a workflow this workspace deployed as a block."
|
||
},
|
||
"authMode": {
|
||
"description": "How the block authenticates: `oauth`, `api_key`, or `bot_token`.",
|
||
"type": "string"
|
||
},
|
||
"triggerAllowed": {
|
||
"type": "boolean",
|
||
"description": "Whether the block declares itself usable as a trigger."
|
||
},
|
||
"triggerCapable": {
|
||
"type": "boolean",
|
||
"description": "Whether the block can start a workflow — a trigger-category block, one declaring `triggerAllowed`, or one with trigger-mode fields."
|
||
},
|
||
"triggerIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Identifiers of the triggers this block supports."
|
||
},
|
||
"toolIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Built-in tools this block can run. Read a tool by its id for the full definition."
|
||
},
|
||
"operationIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Operations this block exposes. Their fields and tools are on the block read."
|
||
},
|
||
"preview": {
|
||
"type": "boolean",
|
||
"description": "Whether the block is unreleased and revealed only to this caller."
|
||
},
|
||
"sunset": {
|
||
"description": "Post-release lifecycle state. Absent for a block in normal support.",
|
||
"type": "object",
|
||
"properties": {
|
||
"status": {
|
||
"type": "string",
|
||
"enum": ["legacy", "deprecated"],
|
||
"description": "`legacy` is superseded but supported; `deprecated` is slated for removal."
|
||
},
|
||
"replacedBy": {
|
||
"description": "Block type to migrate to, when one exists.",
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": ["status"],
|
||
"additionalProperties": false
|
||
},
|
||
"docsLink": {
|
||
"description": "Sim documentation page for the integration.",
|
||
"type": "string"
|
||
},
|
||
"tags": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Catalog tags, e.g. `messaging`, `version-control`."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"name",
|
||
"description",
|
||
"category",
|
||
"source",
|
||
"triggerAllowed",
|
||
"triggerCapable",
|
||
"triggerIds",
|
||
"toolIds",
|
||
"operationIds",
|
||
"preview",
|
||
"tags"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Block summary",
|
||
"description": "List view of a block: what it is and what it references, by id."
|
||
},
|
||
"ListBlocksResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2BlockSummary"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List blocks response",
|
||
"description": "Blocks available in the workspace.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "slack",
|
||
"name": "Slack",
|
||
"description": "Send messages and read channels in Slack.",
|
||
"category": "tools",
|
||
"integrationType": "communication",
|
||
"source": "builtin",
|
||
"authMode": "oauth",
|
||
"triggerAllowed": true,
|
||
"triggerCapable": true,
|
||
"triggerIds": ["slack_webhook"],
|
||
"toolIds": ["slack_message", "slack_canvas_read"],
|
||
"operationIds": ["send", "read"],
|
||
"preview": false,
|
||
"docsLink": "https://docs.sim.ai/tools/slack",
|
||
"tags": ["messaging"]
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"V2BlockField": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Field identifier, and the key its value is stored under."
|
||
},
|
||
"type": {
|
||
"type": "string",
|
||
"description": "Editor control the field renders as, e.g. `short-input`."
|
||
},
|
||
"title": {
|
||
"description": "Human-readable label.",
|
||
"type": "string"
|
||
},
|
||
"required": {
|
||
"description": "Whether a value must be supplied. A conditionally required field reports `true` and carries `requiredWhen`.",
|
||
"type": "boolean"
|
||
},
|
||
"requiredWhen": {
|
||
"description": "Condition under which the field is required.",
|
||
"$ref": "#/components/schemas/V2CatalogCondition"
|
||
},
|
||
"description": {
|
||
"description": "Authored explanation of the field.",
|
||
"type": "string"
|
||
},
|
||
"placeholder": {
|
||
"description": "Placeholder shown in the editor.",
|
||
"type": "string"
|
||
},
|
||
"mode": {
|
||
"description": "Where the field renders: `basic`, `advanced`, `both`, `trigger`, or `trigger-advanced`.",
|
||
"type": "string"
|
||
},
|
||
"hidden": {
|
||
"description": "Whether the field is hidden in the editor.",
|
||
"type": "boolean"
|
||
},
|
||
"condition": {
|
||
"description": "Condition under which the field applies at all.",
|
||
"$ref": "#/components/schemas/V2CatalogCondition"
|
||
},
|
||
"options": {
|
||
"description": "Selectable options. Absent on fields whose options are fetched per workspace at edit time.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Value stored when this option is selected."
|
||
},
|
||
"label": {
|
||
"description": "Human-readable option label.",
|
||
"type": "string"
|
||
},
|
||
"hasIcon": {
|
||
"description": "Whether the option renders with an icon. The icon itself is not published.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["id"],
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"min": {
|
||
"description": "Minimum accepted numeric value.",
|
||
"type": "number"
|
||
},
|
||
"max": {
|
||
"description": "Maximum accepted numeric value.",
|
||
"type": "number"
|
||
},
|
||
"step": {
|
||
"description": "Increment for numeric controls.",
|
||
"type": "number"
|
||
},
|
||
"integer": {
|
||
"description": "Whether the numeric value must be a whole number.",
|
||
"type": "boolean"
|
||
},
|
||
"rows": {
|
||
"description": "Visible row count for multi-line text.",
|
||
"type": "number"
|
||
},
|
||
"password": {
|
||
"description": "Whether the stored value is masked in the editor.",
|
||
"type": "boolean"
|
||
},
|
||
"multiSelect": {
|
||
"description": "Whether more than one option may be selected.",
|
||
"type": "boolean"
|
||
},
|
||
"language": {
|
||
"description": "Language of a code field.",
|
||
"type": "string"
|
||
},
|
||
"generationType": {
|
||
"description": "Kind of content AI assistance generates here.",
|
||
"type": "string"
|
||
},
|
||
"serviceId": {
|
||
"description": "OAuth service this credential field authenticates.",
|
||
"type": "string"
|
||
},
|
||
"requiredScopes": {
|
||
"description": "OAuth scopes the credential selected here must carry.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"mimeType": {
|
||
"description": "MIME type filter applied to a file picker.",
|
||
"type": "string"
|
||
},
|
||
"acceptedTypes": {
|
||
"description": "Accepted file extensions for an upload field.",
|
||
"type": "string"
|
||
},
|
||
"multiple": {
|
||
"description": "Whether more than one file may be supplied.",
|
||
"type": "boolean"
|
||
},
|
||
"maxSize": {
|
||
"description": "Maximum upload size in megabytes.",
|
||
"type": "number"
|
||
},
|
||
"connectionDroppable": {
|
||
"description": "Whether another block’s output can be dropped onto this field.",
|
||
"type": "boolean"
|
||
},
|
||
"columns": {
|
||
"description": "Column headings for a table field.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"dependsOn": {
|
||
"description": "Sibling fields this field is cleared by when they change.",
|
||
"anyOf": [
|
||
{
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"all": {
|
||
"description": "Every listed field must hold a value.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"any": {
|
||
"description": "At least one listed field must hold a value.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"additionalProperties": false
|
||
}
|
||
]
|
||
},
|
||
"canonicalParamId": {
|
||
"description": "Shared key for a picker/manual-entry pair. Both fields write the same value, so supply exactly one of the pair.",
|
||
"type": "string"
|
||
},
|
||
"defaultValue": {
|
||
"description": "Value used when the field is left unset.",
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "boolean"
|
||
},
|
||
{
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Member of an object-valued default. Shape varies by field type."
|
||
}
|
||
},
|
||
{
|
||
"type": "array",
|
||
"items": {
|
||
"description": "Element of an array-valued default. Shape varies by field type."
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"hasComputedDefault": {
|
||
"description": "Whether the field derives its value from the block’s other values. The deriving function is not published.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["id", "type"],
|
||
"additionalProperties": false,
|
||
"title": "Block field",
|
||
"description": "One configuration field on a block."
|
||
},
|
||
"V2CatalogCondition": {
|
||
"type": "object",
|
||
"properties": {
|
||
"field": {
|
||
"type": "string",
|
||
"description": "Sibling field id whose value decides this condition."
|
||
},
|
||
"value": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "boolean"
|
||
},
|
||
{
|
||
"type": "array",
|
||
"items": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "boolean"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
],
|
||
"description": "Value, or set of accepted values, the named field must hold."
|
||
},
|
||
"not": {
|
||
"description": "Invert the match: every value EXCEPT `value`.",
|
||
"type": "boolean"
|
||
},
|
||
"and": {
|
||
"description": "A second clause that must hold as well.",
|
||
"type": "object",
|
||
"properties": {
|
||
"field": {
|
||
"type": "string",
|
||
"description": "Sibling field id for the second clause."
|
||
},
|
||
"value": {
|
||
"description": "Value the second clause matches. Absent means \"holds any value\".",
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "boolean"
|
||
},
|
||
{
|
||
"type": "array",
|
||
"items": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "boolean"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"not": {
|
||
"description": "Invert the second clause.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["field"],
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"required": ["field", "value"],
|
||
"additionalProperties": false,
|
||
"title": "Catalog condition",
|
||
"description": "When a configuration field applies, expressed against a sibling field."
|
||
},
|
||
"V2OperationInput": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "Value type."
|
||
},
|
||
"required": {
|
||
"description": "Whether the value must be supplied.",
|
||
"type": "boolean"
|
||
},
|
||
"visibility": {
|
||
"description": "Who may supply the value: `user-or-llm`, `user-only`, `llm-only`, or `hidden`.",
|
||
"type": "string"
|
||
},
|
||
"description": {
|
||
"description": "What the value means.",
|
||
"type": "string"
|
||
},
|
||
"default": {
|
||
"description": "Value used when this input is omitted."
|
||
},
|
||
"items": {
|
||
"description": "JSON-Schema-shaped constraints declared by the tool parameter."
|
||
},
|
||
"schema": {
|
||
"description": "JSON-Schema-shaped structure declared by the block input."
|
||
}
|
||
},
|
||
"required": ["type"],
|
||
"additionalProperties": false,
|
||
"title": "Operation input",
|
||
"description": "One value a block operation needs, from its tool or its block-level inputs."
|
||
},
|
||
"V2ToolOutput": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "Value type of the output field."
|
||
},
|
||
"description": {
|
||
"description": "What the field holds.",
|
||
"type": "string"
|
||
},
|
||
"optional": {
|
||
"description": "Whether the field may be absent.",
|
||
"type": "boolean"
|
||
},
|
||
"nullable": {
|
||
"description": "Whether the field may be null.",
|
||
"type": "boolean"
|
||
},
|
||
"properties": {
|
||
"description": "Members of an object-typed output, keyed by field name.",
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Nested output field, in this same shape."
|
||
}
|
||
},
|
||
"items": {
|
||
"description": "Element shape of an array-typed output.",
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "Element value type."
|
||
},
|
||
"description": {
|
||
"description": "What an element holds.",
|
||
"type": "string"
|
||
},
|
||
"properties": {
|
||
"description": "Members of an object-typed element, keyed by field name.",
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"description": "Nested output field, in this same shape."
|
||
}
|
||
}
|
||
},
|
||
"required": ["type"],
|
||
"additionalProperties": false
|
||
},
|
||
"fileConfig": {
|
||
"description": "File metadata for a file-typed output.",
|
||
"type": "object",
|
||
"properties": {
|
||
"mimeType": {
|
||
"description": "MIME type of the produced file.",
|
||
"type": "string"
|
||
},
|
||
"extension": {
|
||
"description": "File extension of the produced file.",
|
||
"type": "string"
|
||
}
|
||
},
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"required": ["type"],
|
||
"additionalProperties": false,
|
||
"title": "Tool output",
|
||
"description": "One declared output field of a built-in tool."
|
||
},
|
||
"V2ToolDetail": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Registered tool identifier, including its version suffix."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Display name."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"description": "What the tool does."
|
||
},
|
||
"version": {
|
||
"description": "Tool version.",
|
||
"type": "string"
|
||
},
|
||
"hostedApiKey": {
|
||
"type": "string",
|
||
"enum": ["always", "conditional", "none"],
|
||
"description": "Whether Sim supplies the API key on THIS deployment: `always`, `conditional` (only for some parameter combinations), or `none` (bring your own). Self-hosted deployments supply no hosted keys, so every tool reports `none` there regardless of what it declares."
|
||
},
|
||
"oauth": {
|
||
"description": "OAuth requirement, when the tool has one.",
|
||
"type": "object",
|
||
"properties": {
|
||
"required": {
|
||
"type": "boolean",
|
||
"description": "Whether the tool cannot run without an OAuth credential."
|
||
},
|
||
"provider": {
|
||
"type": "string",
|
||
"description": "OAuth service the credential must authenticate."
|
||
},
|
||
"requiredScopes": {
|
||
"description": "Scopes the credential must carry.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": ["required", "provider"],
|
||
"additionalProperties": false
|
||
},
|
||
"params": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"$ref": "#/components/schemas/V2ToolParam"
|
||
},
|
||
"description": "Parameters the tool accepts."
|
||
},
|
||
"outputs": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"$ref": "#/components/schemas/V2ToolOutput"
|
||
},
|
||
"description": "Fields the tool produces."
|
||
}
|
||
},
|
||
"required": ["id", "name", "description", "hostedApiKey", "params", "outputs"],
|
||
"additionalProperties": false,
|
||
"title": "Tool",
|
||
"description": "A built-in tool with its declared parameters and outputs."
|
||
},
|
||
"V2ToolParam": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "Parameter value type."
|
||
},
|
||
"required": {
|
||
"description": "Whether the parameter must be supplied.",
|
||
"type": "boolean"
|
||
},
|
||
"visibility": {
|
||
"description": "Who may supply the value: `user-or-llm`, `user-only`, `llm-only`, or `hidden`.",
|
||
"type": "string"
|
||
},
|
||
"description": {
|
||
"description": "What the parameter means.",
|
||
"type": "string"
|
||
},
|
||
"default": {
|
||
"description": "Value used when the parameter is omitted."
|
||
},
|
||
"items": {
|
||
"description": "JSON-Schema-shaped constraints for structured params."
|
||
}
|
||
},
|
||
"required": ["type"],
|
||
"additionalProperties": false,
|
||
"title": "Tool parameter",
|
||
"description": "One declared parameter of a built-in tool."
|
||
},
|
||
"V2BlockDetail": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Block type identifier, used as a workflow block’s `type`."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Display name."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"description": "One-line summary of what the block does."
|
||
},
|
||
"longDescription": {
|
||
"description": "Extended explanation, when the block has one.",
|
||
"type": "string"
|
||
},
|
||
"category": {
|
||
"type": "string",
|
||
"description": "Toolbar category: `blocks`, `tools`, or `triggers`."
|
||
},
|
||
"integrationType": {
|
||
"description": "Integration category, e.g. `communication`, `databases`.",
|
||
"type": "string"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"enum": ["builtin", "custom"],
|
||
"description": "Where the block comes from: `builtin` is the shipped registry, `custom` is a workflow this workspace deployed as a block."
|
||
},
|
||
"authMode": {
|
||
"description": "How the block authenticates: `oauth`, `api_key`, or `bot_token`.",
|
||
"type": "string"
|
||
},
|
||
"triggerAllowed": {
|
||
"type": "boolean",
|
||
"description": "Whether the block declares itself usable as a trigger."
|
||
},
|
||
"triggerCapable": {
|
||
"type": "boolean",
|
||
"description": "Whether the block can start a workflow — a trigger-category block, one declaring `triggerAllowed`, or one with trigger-mode fields."
|
||
},
|
||
"triggerIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Identifiers of the triggers this block supports."
|
||
},
|
||
"toolIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Built-in tools this block can run. Read a tool by its id for the full definition."
|
||
},
|
||
"operationIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Operations this block exposes. Their fields and tools are on the block read."
|
||
},
|
||
"preview": {
|
||
"type": "boolean",
|
||
"description": "Whether the block is unreleased and revealed only to this caller."
|
||
},
|
||
"sunset": {
|
||
"description": "Post-release lifecycle state. Absent for a block in normal support.",
|
||
"type": "object",
|
||
"properties": {
|
||
"status": {
|
||
"type": "string",
|
||
"enum": ["legacy", "deprecated"],
|
||
"description": "`legacy` is superseded but supported; `deprecated` is slated for removal."
|
||
},
|
||
"replacedBy": {
|
||
"description": "Block type to migrate to, when one exists.",
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": ["status"],
|
||
"additionalProperties": false
|
||
},
|
||
"docsLink": {
|
||
"description": "Sim documentation page for the integration.",
|
||
"type": "string"
|
||
},
|
||
"tags": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Catalog tags, e.g. `messaging`, `version-control`."
|
||
},
|
||
"bestPractices": {
|
||
"description": "Authored guidance on using the block correctly.",
|
||
"type": "string"
|
||
},
|
||
"inputSchema": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2BlockField"
|
||
},
|
||
"description": "Configuration fields that apply regardless of the selected operation."
|
||
},
|
||
"operationInputSchema": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2BlockField"
|
||
}
|
||
},
|
||
"description": "Configuration fields keyed by the operation that reveals them."
|
||
},
|
||
"inputDefinitions": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "Value type: `string`, `number`, `boolean`, `json`, `array`, or `file`."
|
||
},
|
||
"description": {
|
||
"description": "What the input means.",
|
||
"type": "string"
|
||
},
|
||
"schema": {
|
||
"description": "JSON-Schema-shaped structure for object and array inputs."
|
||
}
|
||
},
|
||
"required": ["type"],
|
||
"additionalProperties": false
|
||
},
|
||
"description": "Block-level input definitions, keyed by parameter name."
|
||
},
|
||
"operations": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"type": "object",
|
||
"properties": {
|
||
"toolId": {
|
||
"description": "Built-in tool that performs this operation.",
|
||
"type": "string"
|
||
},
|
||
"toolName": {
|
||
"description": "Display name of that tool.",
|
||
"type": "string"
|
||
},
|
||
"description": {
|
||
"description": "What the operation does.",
|
||
"type": "string"
|
||
},
|
||
"inputs": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"$ref": "#/components/schemas/V2OperationInput"
|
||
},
|
||
"description": "Values this operation needs, excluding the ones the block supplies from its own block-level inputs."
|
||
},
|
||
"outputs": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"$ref": "#/components/schemas/V2ToolOutput"
|
||
},
|
||
"description": "Fields the operation produces."
|
||
},
|
||
"inputSchema": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2BlockField"
|
||
},
|
||
"description": "Configuration fields that appear when this operation is selected."
|
||
}
|
||
},
|
||
"required": ["inputs", "outputs", "inputSchema"],
|
||
"additionalProperties": false
|
||
},
|
||
"description": "Operations the block exposes, keyed by operation id."
|
||
},
|
||
"tools": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2ToolDetail"
|
||
},
|
||
"description": "Every built-in tool the block can run, with parameters and outputs."
|
||
},
|
||
"triggers": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Trigger identifier."
|
||
},
|
||
"outputs": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "Value type of the output."
|
||
},
|
||
"description": {
|
||
"description": "What the output holds.",
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": ["type"],
|
||
"additionalProperties": false
|
||
},
|
||
"description": "Top-level fields the trigger event delivers."
|
||
},
|
||
"configFields": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "Editor control the field renders as."
|
||
},
|
||
"required": {
|
||
"type": "boolean",
|
||
"description": "Whether a value must be supplied."
|
||
},
|
||
"title": {
|
||
"description": "Human-readable label.",
|
||
"type": "string"
|
||
},
|
||
"description": {
|
||
"description": "Authored explanation of the field.",
|
||
"type": "string"
|
||
},
|
||
"placeholder": {
|
||
"description": "Placeholder shown in the editor.",
|
||
"type": "string"
|
||
},
|
||
"default": {
|
||
"description": "Value used when the field is left unset."
|
||
},
|
||
"options": {
|
||
"description": "Selectable options.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Value stored when this option is selected."
|
||
},
|
||
"label": {
|
||
"type": "string",
|
||
"description": "Human-readable option label."
|
||
}
|
||
},
|
||
"required": ["id", "label"],
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"condition": {
|
||
"description": "Condition under which the field applies.",
|
||
"$ref": "#/components/schemas/V2CatalogCondition"
|
||
}
|
||
},
|
||
"required": ["type", "required"],
|
||
"additionalProperties": false
|
||
},
|
||
"description": "Fields that configure the trigger, keyed by field id."
|
||
}
|
||
},
|
||
"required": ["id", "outputs", "configFields"],
|
||
"additionalProperties": false
|
||
},
|
||
"description": "Triggers the block can run on."
|
||
},
|
||
"outputs": {
|
||
"type": "object",
|
||
"propertyNames": {
|
||
"type": "string"
|
||
},
|
||
"additionalProperties": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "Value type of the output."
|
||
},
|
||
"description": {
|
||
"description": "What the output holds.",
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": ["type"],
|
||
"additionalProperties": false
|
||
},
|
||
"description": "Fields the block produces."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"name",
|
||
"description",
|
||
"category",
|
||
"source",
|
||
"triggerAllowed",
|
||
"triggerCapable",
|
||
"triggerIds",
|
||
"toolIds",
|
||
"operationIds",
|
||
"preview",
|
||
"tags",
|
||
"inputSchema",
|
||
"operationInputSchema",
|
||
"inputDefinitions",
|
||
"operations",
|
||
"tools",
|
||
"triggers",
|
||
"outputs"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Block",
|
||
"description": "A block with its configuration fields, operations, tools, and triggers."
|
||
},
|
||
"GetBlockResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2BlockDetail"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Get block response",
|
||
"description": "One block with its fields, operations, tools, and triggers.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "slack",
|
||
"name": "Slack",
|
||
"description": "Send messages and read channels in Slack.",
|
||
"category": "tools",
|
||
"integrationType": "communication",
|
||
"source": "builtin",
|
||
"authMode": "oauth",
|
||
"triggerAllowed": true,
|
||
"triggerCapable": true,
|
||
"triggerIds": ["slack_webhook"],
|
||
"toolIds": ["slack_message", "slack_canvas_read"],
|
||
"operationIds": ["send", "read"],
|
||
"preview": false,
|
||
"docsLink": "https://docs.sim.ai/tools/slack",
|
||
"tags": ["messaging"],
|
||
"inputSchema": [
|
||
{
|
||
"id": "operation",
|
||
"type": "dropdown",
|
||
"title": "Operation",
|
||
"required": true,
|
||
"options": [
|
||
{
|
||
"id": "send",
|
||
"label": "Send message"
|
||
},
|
||
{
|
||
"id": "read",
|
||
"label": "Read messages"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"operationInputSchema": {
|
||
"send": [
|
||
{
|
||
"id": "text",
|
||
"type": "long-input",
|
||
"title": "Message",
|
||
"required": true
|
||
}
|
||
]
|
||
},
|
||
"inputDefinitions": {
|
||
"channel": {
|
||
"type": "string",
|
||
"description": "Channel to post into."
|
||
}
|
||
},
|
||
"operations": {
|
||
"send": {
|
||
"toolId": "slack_message",
|
||
"toolName": "Slack Send Message",
|
||
"description": "Send a message to a Slack channel.",
|
||
"inputs": {
|
||
"text": {
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Message body."
|
||
}
|
||
},
|
||
"outputs": {
|
||
"ts": {
|
||
"type": "string",
|
||
"description": "Message timestamp."
|
||
}
|
||
},
|
||
"inputSchema": [
|
||
{
|
||
"id": "text",
|
||
"type": "long-input",
|
||
"title": "Message",
|
||
"required": true
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"tools": [
|
||
{
|
||
"id": "slack_message",
|
||
"name": "Slack Send Message",
|
||
"description": "Send a message to a Slack channel.",
|
||
"version": "1.0.0",
|
||
"hostedApiKey": "none",
|
||
"oauth": {
|
||
"required": true,
|
||
"provider": "slack",
|
||
"requiredScopes": ["chat:write"]
|
||
},
|
||
"params": {
|
||
"text": {
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Message body."
|
||
}
|
||
},
|
||
"outputs": {
|
||
"ts": {
|
||
"type": "string",
|
||
"description": "Message timestamp."
|
||
}
|
||
}
|
||
}
|
||
],
|
||
"triggers": [
|
||
{
|
||
"id": "slack_webhook",
|
||
"outputs": {
|
||
"text": {
|
||
"type": "string",
|
||
"description": "Message text."
|
||
}
|
||
},
|
||
"configFields": {
|
||
"channels": {
|
||
"type": "short-input",
|
||
"required": false,
|
||
"title": "Channels"
|
||
}
|
||
}
|
||
}
|
||
],
|
||
"outputs": {
|
||
"ts": {
|
||
"type": "string",
|
||
"description": "Message timestamp."
|
||
}
|
||
}
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2ToolSummary": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Registered tool identifier, including its version suffix."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Display name."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"description": "What the tool does."
|
||
},
|
||
"version": {
|
||
"description": "Tool version.",
|
||
"type": "string"
|
||
},
|
||
"hostedApiKey": {
|
||
"type": "string",
|
||
"enum": ["always", "conditional", "none"],
|
||
"description": "Whether Sim supplies the API key on THIS deployment: `always`, `conditional` (only for some parameter combinations), or `none` (bring your own). Self-hosted deployments supply no hosted keys, so every tool reports `none` there regardless of what it declares."
|
||
},
|
||
"oauth": {
|
||
"description": "OAuth requirement, when the tool has one.",
|
||
"type": "object",
|
||
"properties": {
|
||
"required": {
|
||
"type": "boolean",
|
||
"description": "Whether the tool cannot run without an OAuth credential."
|
||
},
|
||
"provider": {
|
||
"type": "string",
|
||
"description": "OAuth service the credential must authenticate."
|
||
},
|
||
"requiredScopes": {
|
||
"description": "Scopes the credential must carry.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": ["required", "provider"],
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"required": ["id", "name", "description", "hostedApiKey"],
|
||
"additionalProperties": false,
|
||
"title": "Tool summary",
|
||
"description": "List view of a built-in tool: identity, auth, and key hosting."
|
||
},
|
||
"ListToolsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2ToolSummary"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List tools response",
|
||
"description": "Built-in tools available in the workspace.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "slack_message",
|
||
"name": "Slack Send Message",
|
||
"description": "Send a message to a Slack channel.",
|
||
"version": "1.0.0",
|
||
"hostedApiKey": "none",
|
||
"oauth": {
|
||
"required": true,
|
||
"provider": "slack",
|
||
"requiredScopes": ["chat:write"]
|
||
}
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
},
|
||
"GetToolResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"description": "Response data.",
|
||
"$ref": "#/components/schemas/V2ToolDetail"
|
||
}
|
||
},
|
||
"required": ["data"],
|
||
"additionalProperties": false,
|
||
"title": "Get tool response",
|
||
"description": "One built-in tool with its parameters and outputs.",
|
||
"examples": [
|
||
{
|
||
"data": {
|
||
"id": "slack_message",
|
||
"name": "Slack Send Message",
|
||
"description": "Send a message to a Slack channel.",
|
||
"version": "1.0.0",
|
||
"hostedApiKey": "none",
|
||
"oauth": {
|
||
"required": true,
|
||
"provider": "slack",
|
||
"requiredScopes": ["chat:write"]
|
||
},
|
||
"params": {
|
||
"channel": {
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Channel ID to post into."
|
||
},
|
||
"text": {
|
||
"type": "string",
|
||
"required": true,
|
||
"description": "Message body."
|
||
}
|
||
},
|
||
"outputs": {
|
||
"ts": {
|
||
"type": "string",
|
||
"description": "Message timestamp."
|
||
}
|
||
}
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"V2ConnectorType": {
|
||
"type": "object",
|
||
"properties": {
|
||
"connectorType": {
|
||
"type": "string",
|
||
"description": "Exact identifier to send when creating a connector of this type."
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "Display name."
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"description": "What the connector syncs."
|
||
},
|
||
"version": {
|
||
"type": "string",
|
||
"description": "Connector version."
|
||
},
|
||
"auth": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"mode": {
|
||
"type": "string",
|
||
"const": "oauth",
|
||
"description": "Authenticates with an OAuth credential."
|
||
},
|
||
"provider": {
|
||
"type": "string",
|
||
"description": "OAuth service the credential must authenticate."
|
||
},
|
||
"requiredScopes": {
|
||
"description": "Scopes the credential must carry.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": ["mode", "provider"],
|
||
"additionalProperties": false
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"mode": {
|
||
"type": "string",
|
||
"const": "apiKey",
|
||
"description": "Authenticates with a stored API key."
|
||
},
|
||
"label": {
|
||
"description": "Label shown above the key field.",
|
||
"type": "string"
|
||
},
|
||
"placeholder": {
|
||
"description": "Placeholder shown in the key field.",
|
||
"type": "string"
|
||
},
|
||
"optional": {
|
||
"type": "boolean",
|
||
"description": "Whether the key may be left blank, for a source reachable without authentication."
|
||
}
|
||
},
|
||
"required": ["mode", "optional"],
|
||
"additionalProperties": false
|
||
}
|
||
],
|
||
"description": "How the connector authenticates against its source."
|
||
},
|
||
"configFields": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2ConnectorConfigField"
|
||
},
|
||
"description": "Fields that make up the connector’s `sourceConfig`."
|
||
},
|
||
"supportsIncrementalSync": {
|
||
"type": "boolean",
|
||
"description": "Whether syncs after the first fetch only what changed."
|
||
},
|
||
"tagDefinitions": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Semantic tag identifier the connector populates."
|
||
},
|
||
"displayName": {
|
||
"type": "string",
|
||
"description": "Human-readable tag name."
|
||
},
|
||
"fieldType": {
|
||
"type": "string",
|
||
"enum": ["text", "number", "date", "boolean"],
|
||
"description": "Value type, which decides the tag slot pool it draws from."
|
||
}
|
||
},
|
||
"required": ["id", "displayName", "fieldType"],
|
||
"additionalProperties": false
|
||
},
|
||
"description": "Tags this connector writes onto the documents it syncs."
|
||
}
|
||
},
|
||
"required": [
|
||
"connectorType",
|
||
"name",
|
||
"description",
|
||
"version",
|
||
"auth",
|
||
"configFields",
|
||
"supportsIncrementalSync",
|
||
"tagDefinitions"
|
||
],
|
||
"additionalProperties": false,
|
||
"title": "Connector type",
|
||
"description": "A knowledge-base connector type and the configuration it accepts."
|
||
},
|
||
"V2ConnectorConfigField": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Field identifier."
|
||
},
|
||
"title": {
|
||
"type": "string",
|
||
"description": "Human-readable label."
|
||
},
|
||
"type": {
|
||
"type": "string",
|
||
"enum": ["short-input", "dropdown", "selector"],
|
||
"description": "Control the field renders as. A `selector` fetches its options from the connected account."
|
||
},
|
||
"placeholder": {
|
||
"description": "Placeholder shown in the editor.",
|
||
"type": "string"
|
||
},
|
||
"required": {
|
||
"description": "Whether a value must be supplied.",
|
||
"type": "boolean"
|
||
},
|
||
"description": {
|
||
"description": "Authored explanation of the field.",
|
||
"type": "string"
|
||
},
|
||
"options": {
|
||
"description": "Static options, for a `dropdown` field.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Value stored when this option is selected."
|
||
},
|
||
"label": {
|
||
"type": "string",
|
||
"description": "Human-readable option label."
|
||
}
|
||
},
|
||
"required": ["id", "label"],
|
||
"additionalProperties": false
|
||
}
|
||
},
|
||
"selectorKey": {
|
||
"description": "Names the picker a `selector` field renders. Its options are fetched per workspace.",
|
||
"type": "string"
|
||
},
|
||
"mimeType": {
|
||
"description": "MIME type filter applied to the picker.",
|
||
"type": "string"
|
||
},
|
||
"dependsOn": {
|
||
"description": "Sibling fields this field is cleared by when they change.",
|
||
"anyOf": [
|
||
{
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"all": {
|
||
"description": "Every listed field must hold a value.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"any": {
|
||
"description": "At least one listed field must hold a value.",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"additionalProperties": false
|
||
}
|
||
]
|
||
},
|
||
"mode": {
|
||
"description": "Which half of a canonical pair this field is: `basic` is the picker, `advanced` the manual entry.",
|
||
"type": "string",
|
||
"enum": ["basic", "advanced"]
|
||
},
|
||
"canonicalParamId": {
|
||
"description": "Shared `sourceConfig` key for a picker/manual-entry pair. Send exactly one of the pair, keyed by this value rather than by the field’s own `id`.",
|
||
"type": "string"
|
||
},
|
||
"multi": {
|
||
"description": "When true the stored `sourceConfig` value is a `string[]`, not a `string`: a `selector` renders a multi-select picker and a `short-input` accepts a comma-separated list.",
|
||
"type": "boolean"
|
||
}
|
||
},
|
||
"required": ["id", "title", "type"],
|
||
"additionalProperties": false,
|
||
"title": "Connector config field",
|
||
"description": "One field of a knowledge-base connector’s source configuration."
|
||
},
|
||
"ListConnectorTypesResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"data": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/V2ConnectorType"
|
||
},
|
||
"description": "Items in the current page."
|
||
},
|
||
"nextCursor": {
|
||
"anyOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "null"
|
||
}
|
||
],
|
||
"description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"additionalProperties": false,
|
||
"title": "List connector types response",
|
||
"description": "Knowledge-base connector types and their configuration fields.",
|
||
"examples": [
|
||
{
|
||
"data": [
|
||
{
|
||
"connectorType": "google_drive",
|
||
"name": "Google Drive",
|
||
"description": "Sync documents from a Google Drive folder.",
|
||
"version": "1.0.0",
|
||
"auth": {
|
||
"mode": "oauth",
|
||
"provider": "google-drive",
|
||
"requiredScopes": ["https://www.googleapis.com/auth/drive.readonly"]
|
||
},
|
||
"configFields": [
|
||
{
|
||
"id": "folderSelector",
|
||
"title": "Folder",
|
||
"type": "selector",
|
||
"selectorKey": "google-drive-folder",
|
||
"mimeType": "application/vnd.google-apps.folder",
|
||
"mode": "basic",
|
||
"canonicalParamId": "folderId",
|
||
"required": true
|
||
},
|
||
{
|
||
"id": "manualFolderId",
|
||
"title": "Folder ID",
|
||
"type": "short-input",
|
||
"placeholder": "Enter the folder ID",
|
||
"mode": "advanced",
|
||
"canonicalParamId": "folderId"
|
||
}
|
||
],
|
||
"supportsIncrementalSync": true,
|
||
"tagDefinitions": [
|
||
{
|
||
"id": "owner",
|
||
"displayName": "Owner",
|
||
"fieldType": "text"
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"nextCursor": null
|
||
}
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"x-generated-by": "scripts/generate-openapi.ts"
|
||
}
|