mirror of
https://github.com/simstudioai/sim.git
synced 2026-09-21 13:00:04 +08:00
WaleedandTheodore Li
656840a1b1
* feat(v2): download run output files by API key
Adds GET /api/v2/workflows/{id}/runs/{runId}/files/{fileId}, closing the
async-run loop for headless callers. A run's output carries UserFile URLs
pointing at /api/files/serve/..., which rejects x-api-key outright, so an
async run that produces a file previously had no byte path out for an API
key at all.
The file is addressed by the id the run reported and resolved against the
run's own recorded execution data, from which the storage key is read. The
request never supplies a storage key, so the endpoint cannot be aimed at
bytes the run did not produce. Resolution deliberately reads the
materialized-but-undisplayed recording, because the display projection
strips exactly the `key`/`context` fields a byte read needs.
Also hardens normalizeStartFile to derive a file's storage key only from a
validated internal serve URL, discarding any caller-supplied `key`/`context`.
A workspace API key has no human subject, so the executor resolves its actor
to the workspace billing owner (preprocessing.ts -> resolveSystemBillingAttribution);
verifyFileAccess then authorizes a workspace-context key as that owner, whose
reach is not bounded by the key's workspace. Accepting an attacker-authorable
key made that substitution exploitable as a confused deputy. Normalization is
all-or-nothing, so a forged file now drops the whole files input.
* feat(workflows): one graph-write door, principal-derived audit source, and v2 authoring endpoints
Extract replaceWorkflowNormalizedState as the single persistence primitive for a
workflow graph replace and route both the internal editor save and the Copilot
edit tool through it, so neither can skip state preparation, the row lock, the
lastSynced stamp, or custom-tool extraction by choosing a different entry point.
Derive the audit source from the acting principal instead of hardcoding
'copilot', then widen workflows.variables.apply_operations and
workflows.bulk.move to every principal kind.
Add GET/PUT /api/v2/workflows/{id}/state, POST /operations, /duplicate,
/restore, PATCH /variables, and POST /api/v2/workflows/move over surface-neutral
application use cases; move the edit engine to lib/workflows/editing.
* test(workflows): cover the graph-write primitive, audit source, and the v2 authoring surface
Pin the two-doors fix (preparation runs, the row is locked, custom-tool
extraction is post-commit and best-effort) and the false-audit fix (a session
principal writes source: 'session', a delegated one writes its service). Both
were verified to fail with the fix reverted.
Add the application matrix for replaceWorkflowState, applyWorkflowOperations,
readWorkflowGraph, and restoreWorkflow — role floor, principal-kind rejection
before canonical load, asserted-scope concealment, lock, validation, atomic
conflict, plan gate, and audit-then-notify ordering — plus route tests for
every new endpoint.
* test(workflows): pin the internal graph-write door and the v2 list scope
Characterize saveWorkflowNormalizedState's statuses, messages, and notification
after the persistence extraction, and cover the new scope filter on
GET /api/v2/workflows including a cursor replayed under a different scope.
* feat(api): add v2 block, tool, connector-type, and enrichment catalogs
Adds six read endpoints under /api/v2 that publish Sim's code-defined
catalogs: GET /blocks, GET /blocks/{blockId}, GET /tools,
GET /tools/{toolId}, GET /connector-types, and GET /enrichments.
These read like static reference data and are not. What a caller may
place is decided per workspace by its permission-group integration
allowlist, per organization by which unreleased blocks have been
revealed, per deployment by ALLOWED_INTEGRATIONS, and per workspace
again by the workflows it has deployed as blocks. So all six are plain
defineWorkspaceOperation reads at minimumRole 'read' with
workspaceApiKey 'allow' — the exact policy of credentials.providers.list
— and every response keeps Cache-Control: private, no-store, because an
unrevealed preview block's existence must not leak across organizations
through a shared cache.
Trigger blocks ride as ?capability=trigger rather than a second
endpoint, and workspace custom blocks ride inside /blocks discriminated
by `source`, so "what may I place?" stays a one-call question.
The block projection is extracted out of the Copilot get_blocks_metadata
tool and rewritten onto @/tools/metadata and @/tools/metadata-outputs.
That cuts the tool's own @/tools/registry edge as a side effect: its
module graph drops from 6,756 to 1,318, and the new routes land at
1,673-1,734, next to the shipped /v2/credentials/providers baseline of
1,668.
Supporting changes:
- scripts/sync-tool-metadata.ts derives hostedApiKey ('always' |
'conditional' | 'none') from each tool's `hosting`. The config itself
stays excluded because it holds closures, but "does Sim host the key"
is a first-order authoring question, so the answer is emitted.
- getCopilotToolDescription takes hostedApiKey as an option instead of
reading `hosting` off the tool, so both an executable ToolConfig and
the generated metadata can answer it through one shared derivation.
- principalUserId / allowedIntegrationTypes move out of
lib/credentials/application/provider-catalog.ts into
lib/integrations/principal-scope.server.ts. Two copies of the
workspace integration gate would diverge first on the workspace-key
path, which has no user for permission groups to key on.
- scripts/check-tool-registry-boundary.ts walked page.tsx/layout.tsx
under app/workspace only, so a route importing the executable registry
passed green. It now walks a list of entry sources, seeded with the
four catalog route subtrees and the shared projection barrel. Routes
are covered per subtree rather than wholesale because 122 of ~1,130
route files legitimately execute tools.
Registry sweeps parse every block, tool, connector type, and enrichment
through its published response schema and compare against the wire
round-trip. They caught a real drift while being written: an operation's
inputs were typed as a union of the tool-param and block-input shapes,
and the union resolved to whichever member matched first, silently
dropping a block input's `schema`.
* docs(api): stop publishing a 413 GET /workflows/{id}/state cannot emit
* feat(v2): read upload-session state
Adds GET /api/v2/files/uploads/{uploadId}. Only DELETE was exported, so a
caller that lost track of a transfer could abort it but could not ask
whether the session was still alive, already finalized, or failed — the
resume story was missing.
Runs on a new files.upload.read operation at minimumRole 'read' rather than
reusing uploadCancel, which is a 'write': asking about a session must not
require permission to destroy it. The GET is a control leg like every other,
so it carries the signed upload token and re-authorizes the caller's present
workspace permission through reauthorizeWorkspaceUploadPurpose instead of
resolving the session on its id alone.
* fix(api): reconcile v2 catalog and workflow-authoring integration
Merging the catalog and workflow-authoring branches surfaced four issues
that neither produced in isolation.
- Route and OpenAPI counters were bumped to the same value on both
branches, so git merged them as one change while the merged tree holds
the sum. Corrects the route ratchet to 1142 and the workflows document
to 29 operations (152 total), then regenerates the OpenAPI documents
and the CLI surface from the reconciled contracts.
- The seven new workflow operations were published in the spec but absent
from the workflow API reference groups, which `check:openapi` rejects.
- `route-policies.ts` reached `WorkflowOperationsNotAppliedError` through
`apply-workflow-operations`, dragging the edit engine — and its diff and
comparison dependencies, which reach a client OAuth hook — into every
route that uses the shared workflow error policies. The class moves to
its own leaf module, mirroring `WorkflowImportError`, and each importer
now takes it from there.
- The operations route test shadowed that class inside its module mock, so
`instanceof` matched a fake and the assertion pinned a message the
production class never emits. It now uses the real class and asserts the
real message.
* feat(v2): extract ZIP archives over the public API
Adds POST /api/v2/files/{fileId}/extract and widens files.extract_archive
from principalKinds ['session'] / workspaceApiKey 'deny' to admit personal
and workspace API keys at the unchanged 'write' role.
The widening is an authorization change, so the justification lives in the
operation's TSDoc: extraction grants no capability an API key lacks, since
every file it writes could be created one at a time through files.create and
files.upload.create, both already 'allow' at the same role. It only collapses
many calls into one. The previous ['session'] restriction read as an artifact
of the UI having been the only caller. Delegated services stay out — no
copilot or executor caller exists and admitting one is a separate decision.
The response is counts plus the destination folderPath, never the extracted
files: a large archive would otherwise materialize thousands of objects into
one body. Callers page GET /api/v2/files?folderPath=... instead. The use case
returns the internal display path and the adapter projects it to a v2 path,
keeping the use case surface-neutral.
* feat(v2): extract file text over the public API
Adds GET /api/v2/files/{fileId}/text. Text extraction previously sat behind
checkInternalAuth on /api/files/parse, a route that also mixes in external-URL
fetching, execution-file upload, and multi-file aggregation, so it could not be
reused. The parse call is lifted into a thin application use case instead.
Runs on the existing files.read_content operation unchanged — it is already
workspaceApiKey 'allow' at the read role, and turning bytes it already
authorizes into text grants no further reach.
`degraded` is a required, non-optional boolean on the response. The legacy doc
and ppt parsers deliberately return best-effort or placeholder content rather
than throwing, so an omittable flag would let a client that never checks it
treat guessed text as extracted text. It is reported honestly rather than
converted into an error, because the parsers' behaviour is deliberate and
characterization-tested.
The read is bounded on its input at 25 MiB before extraction rather than on its
output after, given the parsers' documented DoS history; a caller may lower the
ceiling but never raise it.
* feat(v2): restore archived folders and list the archived set
DELETE /api/v2/files/folders archives recursively, so a recursive delete was
unrecoverable over the API: the archived files stayed visible through
GET /api/v2/files?scope=archived, but nothing could rebuild the folder
structure.
Adds POST /api/v2/files/folders/restore, path-addressed like the rest of the
v2 folder family, and a `scope` selector on the folder list so a caller can
find the archived path to hand it.
`scope` extends the files folder-list query rather than the shared
v2ListFoldersQuerySchema: only workspace files have an archived folder set, so
adding it to the shared schema would give tables, workflows, and knowledge a
parameter they ignore. GET /api/v2/files/folders is a FULL_SET_LIST, not paged,
so no cursor binding changes — list-pagination.test.ts passes unchanged.
Restore resolves the archived folder from its path by scanning the archived
set rather than walking the live tree, which by definition does not contain
the folder being restored. The folder-restored analytics hook now reports the
folder actually restored rather than the requested selector, which carries no
id on a path-addressed surface.
* feat(v2): bulk-download a file selection as a zip
Adds GET /api/v2/files/bulk-download, an adapter over the existing
downloadWorkspaceFileItems use case and its internal binary route.
Path collision: a static segment beside [fileId] permanently shadows a file
whose id equals it, and workspaceFileIdSchema does accept [A-Za-z0-9_-]+.
Rather than invent a new shape, this follows the existing bulk-delete sibling:
the hyphenated form cannot be produced by either minted id shape (UUID v4 or
wf_<shortId>), so the shadowed id is unreachable in practice. Documented on
the contract so the reasoning is not lost.
Folders are addressed by path, matching the rest of the v2 file surface. The
paths resolve against the folder set the selection already loads, so it costs
no extra query, and a path matching no folder is rejected rather than silently
dropped — a misspelled folder must not yield a zip of whatever else was
selected. The empty-selection and folder-count guards now account for
folderPaths, which a path-only selection would otherwise have tripped.
Selections are comma-separated only: v2 rejects a query parameter sent more
than once, so a repeated-parameter form would never reach the schema. Pinned by
a test so the contract cannot advertise a form the boundary rejects.
* feat(v2): expose run output files and optional inline bytes on the runs read
GET /api/v2/workflows/{id}/runs/{runId} now reports the files a run produced,
each with the downloadPath that fetches its bytes, and can inline them as
base64 on request.
Gated by includeOutput, matching `output`'s nullability: a caller that did not
ask for output does not receive a file list it did not request. The async
execute request's rejection of includeFileBase64 is deliberately left alone —
at submit time the run has not happened, so there is nothing to inline; reading
a finished run is the first moment the question means anything.
Inlining is capped per file at the executor's 16 MiB inline ceiling, which a
caller may lower but never raise. A file above it answers 413 naming that
file's downloadPath, so the caller is told exactly how to get the bytes rather
than being left stuck.
The descriptor deliberately omits the storage key — files are addressed by id
and the key is re-derived from the run's recording — and omits an expiry, which
the recording does not carry and which would be fabricated if published.
The route becomes headSafe: false, since inlining reads object storage. The
builder enforces that this requires the use case to expose authorize(), so HEAD
still answers from a real authorization rather than from authentication alone.
* feat(v2): permanently delete an archived file
DELETE /api/v2/files/{fileId} only archives — the OpenAPI says its stored bytes
are never removed — so there was no way to actually destroy a file over the API.
Adds the repository primitive, application use case, operation, and
DELETE /api/v2/files/{fileId}/permanent.
A distinct path rather than a flag on the ordinary delete: a query parameter
that turns a recoverable archive into an irreversible destruction is set by
accident, and the two acts carry different minimum roles, which one route
declaration cannot express. The file must already be archived; a live file
answers 409 naming the archive step, so no single request can turn a live file
into lost bytes.
minimumRole 'admin', which forces workspaceApiKey 'deny' since the workspace-key
ceiling is 'write' — the desired policy anyway: unattended credentials should
not destroy bytes.
Row first, then object. The two legs commit independently, so one can survive a
crash between them: deleting the row first leaves at most an orphaned object for
the storage sweep, while the reverse would leave a live row pointing at bytes
that no longer exist — a file that lists and opens but can never be read. A
failed object delete is therefore reported as objectDeleted: false rather than
thrown, because the request has genuinely succeeded once the row is gone. Both
directions are pinned by failure-injection tests, verified to fail when the
order is reversed.
Audited as a distinct FILE_PERMANENTLY_DELETED action, not a reuse of
FILE_DELETED, which records the recoverable archive step.
* feat(api): v2 log analytics, itemized cost, filters, and sortable query
Adds the aggregate and rich-read halves of the public logs surface, and
fixes three defects the existing reads carry.
Aggregate analytics. `GET /api/v2/logs/stats` returns time-bucketed run
counts, success rate, error count, mean latency, and the window bounds,
per workflow and for the workspace. The first-party route was a raw
handler with inline SQL and inline aggregation, so it is split into a
repository (`lib/logs/stats-queries.ts`), a pure aggregator
(`lib/logs/stats.ts`), and an application use case. That route keeps its
legacy authorization — it answers a caller without workspace access with
a zeroed 200, where v2 conceals the workspace as a 404 — and consumes
only the two surface-neutral halves.
`segmentCount` had no `.int()`, `.min()`, or `.max()`, so `0` divided by
zero and `1e9` allocated two billion-element arrays: both caller-reachable
500s. Bounded on both contracts. `workflows` is capped, with the workspace
totals still computed from every workflow and the cut reported as
`workflowsTruncated`.
Detail reads gain the itemized `cost.items` ledger (`null` and `[]` are
distinct answers and both reachable) and `workflowInput`, restoring a
v1→v2 regression.
The list gains `workflowName` and `status` filters, and `includeJobRuns`,
which unions Chat and Sim-agent job runs into the sequence behind a new
`kind` discriminator — without it a job run is indistinguishable from a
run whose workflow was deleted. A filter no job row can answer drops the
branch outright rather than meaning two things across the union.
`POST /api/v2/logs/query` carries the additional sort columns. `GET /logs`
is untouched: its single `order` param rests on there being exactly one
sortable column, and both escapes from that are ruled out, so the rich
read gets its own endpoint — the split the table surface already ships.
It uses the shared keyset scheme with the two nullable sort columns read
through a sentinel, since a keyset cannot compare against null.
`folderPaths` now covers a folder's whole subtree on the public path, as
it already did everywhere else; it previously omitted every nested run
with no error. The path strings did not change, so a folder-scope version
is stamped into the cursor and in-flight tokens restart rather than
silently skipping rows.
Also fixes `folderName`, which ILIKEd `workflow.name` — a copy of the
clause above it — and so searched workflow names instead of folders.
`buildLogSortCursorCondition`'s `IS NULL` disjunct is documented and
pinned: under `NULLS LAST` the null block is only reachable through it,
so removing it as a duplicate-row fix makes those runs unpageable.
Ratchets: route count 1142 -> 1144; logs OpenAPI operations 2 -> 4; total
operations 152 -> 154.
* feat(api): v2 tables run state, dispatch polling, batch update, bulk, archive
Closes the headless gaps on the v2 tables surface.
- Per-cell run state is now readable through an opt-in `includeRunState` on
`GET /rows`, `POST /query`, and `GET /rows/{rowId}`. The default projection
is byte-identical; a page whose sidecar outgrows its byte budget is a 413
rather than a silent truncation.
- Run dispatches are addressable: `GET /tables/dispatches/{dispatchId}`
publishes the column's full four-state domain so polling a finished run is
not a 500, and `GET /tables/{tableId}/dispatches` lists what is in flight.
- `POST /rows/batch-update` takes one distinct patch per row. Its transaction
moved out of the Copilot-only module into a surface-neutral use case both
surfaces now call.
- `GET .../enrichment/{groupId}` publishes the provider cascade, cost, and
timing behind one enrichment cell.
- `POST /tables/bulk-move` and `/bulk-delete` reach the existing bulk use
cases, which now accept folders by canonical path and resolve them inside
the application layer.
- `DELETE` is recoverable: `scope=archived` on the table list plus
`POST /tables/{tableId}/restore`.
* feat(api): expose knowledge chunks, tag writes, archive/restore on v2
Closes the knowledge cluster's remaining public-surface gaps.
Chunks: list/read/create/update/delete/bulk under
`/api/v2/knowledge/{id}/documents/{documentId}/chunks`. `queryChunks` gains
an `id` tiebreaker on every sort so the list pages on a keyset rather than an
offset — `tokenCount` and `enabled` are both non-unique, so a page boundary
inside a run of equal values used to repeat or drop the tied rows. The
internal offset caller is unchanged; the two positioning schemes share one
read.
Tag definitions: create, update, delete, next-slot, usage, and the
document-scoped save and cleanup. Without them a caller could write a tag
value into a slot with no definition and then had no way to name it, so
tag-filtered retrieval was unbuildable end-to-end. `v2KnowledgeTagSchema`
gains `id`, without which PATCH and DELETE are unaddressable. The
document-scoped DELETE is pinned to `action: 'cleanup'`: the domain's `'all'`
deletes the whole knowledge base's tag vocabulary from a document path.
Archive/restore: `GET /api/v2/knowledge/archived` as a sibling route rather
than a `scope` param — the two reads bind different operations and a v2 route
declares one — plus `POST /api/v2/knowledge/{id}/restore`. `knowledge.restore`
is a new workspace operation carrying `delete`'s policy, since an operation's
inverse must not be harder to reach; the internal session route now delegates
its workspace branch to the shared use case and keeps only the legacy personal
one.
Also: `POST .../documents/from-workspace-files` surfaces `addWorkspaceFiles`,
so a file already in workspace storage no longer has to be re-uploaded
byte-for-byte to be indexed; the `chunkingConfig` write widens to the
first-party five-key schema with its refines and separator bounds, while the
response stays `.catchall` so a legacy JSONB row cannot 500; and
`CONNECTOR_MANAGED_RESOURCE_READ_ONLY` joins `FORBIDDEN_DETAIL_CODES` now that
the bare 403 on connector-managed chunk writes is wire-reachable.
Document upsert is deliberately not included.
* feat(api): add v2 credential rotation and a gate-exempt capabilities endpoint
PATCH /api/v2/credentials/{credentialId} rotates service-account secret
material or renames a credential in place, preserving the credential id so
existing workflow, deployment, paused-run, connector, and webhook references
keep working. Re-posting to POST /api/v2/credentials answers 409, and
delete-and-recreate mints a new id, so rotation previously had no door.
The route is adapter-only: updateWorkspaceCredentialUseCase already owned the
rotation, its audit projection, and credentials.update. It gains one additive
assertedWorkspaceId field for the v2 workspace assertion, and the per-principal
credential-type table that deleteCredentialUseCase already applied is lifted
into requireManageableCredentialType so both operations share it. Without it a
personal API key could rename an env_workspace row and toV2Credential's throw
would surface as a caller-reachable 500.
CredentialProviderOperationError now maps to 503 with Retry-After when the
provider is unreachable, instead of the 400 its OrchestrationError('validation')
base projected. A transient outage rendered as a permanent input error invites a
caller to revoke a working credential.
GET /api/v2/meta reports the calling key's rollout cohort, type, and expiry.
It is the one route declaring the new typed gate: 'exempt' option, because the
rollout gate and the unknown-path catch-all answer byte-identical 404s and a
gated /api/v2/meta could never resolve that ambiguity. Authentication still runs
first, so the only fact disclosed is one about the caller's own credential.
* feat(api): publish deployment lifecycle and workflow-MCP v2 surfaces
Adds the four deployment-lifecycle operations v2 was missing, and the
workflow-as-MCP publishing surface, both as adapters over application use
cases that already existed.
Deployment lifecycle:
- PATCH /api/v2/workflows/{id}/versions/{version} relabels a version.
Deliberately not the internal route's body-shape dispatch between
"rename" and "promote to live".
- POST .../versions/{version}/activate promotes a version. Same use case
as rollback under a different transition, on its own path because the
two mean opposite things to a caller.
- POST .../versions/{version}/revert overwrites the draft. Accepts the
literal `active` alongside a version number.
- PATCH /api/v2/workflows/{id}/deployment toggles unauthenticated public
execution.
`workflows.public_api.update` widens from session-only to session plus
personal API key: it is an admin-role change the same accountable human
may make from a script. Workspace keys stay denied. Its EE refusal now
carries PUBLIC_SHARING_NOT_ALLOWED instead of a bare forbidden.
Workflow MCP servers:
- /api/v2/workflow-mcp-servers list, create, update, delete, plus
publish and unpublish of a workflow as a tool. Named apart from
/api/v2/mcp-servers, which registers the external servers Sim calls.
- The six mcp_servers.workflow_deployments operations widen from
['delegated'] to admit sessions and personal API keys; roles and the
workspace-key denial are unchanged.
- The server list gains keyset pagination, matching its external
sibling, since nothing caps how many a workspace publishes.
- Server, tool, and workflow reads move out of the use case into
lib/mcp/queries.
Route ratchet 1150 -> 1160; OpenAPI operations 161 -> 171.
* feat(api): extract chat deployments and publish the v2 surface
Chat deployment was a shipped module with no public API and two
authorization systems: `lib/workflows/application/chat-deployments.ts`
had deploy/undeploy extracted, but only Copilot used them — the REST
routes reimplemented workflow authorization inline, and `PATCH
/api/chat/manage/[id]` additionally owned password encryption, the
auth-type field-clearing matrix, identifier uniqueness, the
redeploy-gating protocol with two 409s, a raw db.update, and a manual
recordAudit.
New `lib/chat-deployments` domain:
- `chat_deployments.list/read/update/delete`, keyed on the deployment
whose workspace is derived by joining its workflow. Creation stays
`workflows.chat.deploy`, which is keyed on the workflow.
- The PATCH extraction, including the field-clearing matrix and the
asynchronous-cutover invariant the route had hand-mirrored from
`performChatDeploy`.
- One `buildChatDeploymentUrl`, replacing three constructions that had
already drifted onto two different host helpers. There is no chat
subdomain, so nothing publishes a host.
- Repository reads moved out of the use cases into
`lib/chat-deployments/queries`.
Internal routes are now adapters over those use cases. `GET /api/chat`
is deliberately not migrated: it scopes by `chat.userId` while every
other chat operation authorizes by workspace admin, and reconciling the
two is a product decision. `PATCH` keeps its 400 for an identifier
collision through a typed `ChatIdentifierInUseError`; v2 reports the
409 the condition actually is.
v2 surface at `/api/v2/chat-deployments`: list, create, read, update,
delete. Workspace-scoped, keyset-paged, and a stored password is never
readable — reads carry `hasPassword` only, and the session-only reveal
endpoint deliberately has no v2 counterpart.
Also: an email- or SSO-gated chat with an empty allow-list is now
refused in the use case rather than only at the internal boundary, since
it is unenterable; and the doc comment on `processHostedKeyCost`
claiming a `usageLog` write is corrected — no such write exists.
Route ratchet 1160 -> 1165; OpenAPI operations 171 -> 176.
* fix(api): close three review findings, two of them caller-reachable
- Run output files are filtered to keys under the run's own execution
prefix. The recording they came from is not a trustworthy key source:
the start block copies every caller-supplied input field verbatim into
its output and `collectUserFilesById` accepts anything carrying the
`UserFile` shape, so a caller could name any storage key and have the
download and base64 paths — neither of which authorizes per file — serve
it back.
- `getBlock` reads own keys only. `BLOCK_REGISTRY` is an object literal,
so `constructor`, `toString` and friends returned inherited functions
that every consumer then treated as a block, turning a path segment into
a 500. `getToolMetadata` already guarded this way.
- A folder-scoped log page no longer unions in every job run in the
workspace. The guard read `filters.folderIds`, which the public surface
never sets — it carries the folder filter in `folderScope` — so the page
contradicted the contract's promise that job runs are dropped whenever a
filter they cannot answer is set.
Also: the log cursor stamps `includeJobRuns` only when it is on, so its
`.default(false)` no longer puts a constant in every fingerprint and
rejects cursors minted before it existed; and the `folderName` subquery is
scoped to the workspace and to workflow folders instead of scanning the
whole `folder` table.
* fix(api): close two more review findings, one an authorization bypass
- `workflows.operations.apply` no longer admits a workspace API key. The
use case authorizes against three per-user policies — the EE permission
config, block visibility, and credential reachability — and all three
take a human subject. An actorless key has none, and both substitutes
fail open: attributing to the workspace billing owner evaluates the
batch as the least-restricted account in the workspace, and passing no
user makes `getUserPermissionConfig` return `null`, which every caller
reads as unrestricted. Either way a workspace constrained by an
allowlist was edited as though it were not. Personal keys keep the
capability, so headless editing is unaffected for a credential that
names a human.
- `GET /workflows/{id}/state` reads its variables through
`parseWorkflowVariables`, and the stored variable response schema drops
the two assertions the column cannot honour. The column has carried a
JSON string and a legacy array as well as the current record, the
realtime `variable.add` op types `type` as `z.any()`, and the parser
writes `name` through verbatim — so the input bounds on the read turned
a stored workflow into a 500 on the endpoint that opens it. The write
schema keeps them, which is where they can still be honoured.
- `GET /workflows?scope=archived` projects folder paths tolerantly.
Archiving a folder cascades onto the workflows inside it but leaves
their `folderId` dangling — which is why restore has to null it — so the
strict projector threw a bare `Error` and took the whole page down with
no cursor able to step past the row.
* fix(files): bind Start-block file keys to the executing workspace
The Start block derived a file's storage key by parsing the caller's own
`url`, which `isInternalFileUrl` matches on any host and
`extractStorageKey` returns verbatim — so a request body could name any
tenant's bytes. The key is now accepted only when its own layout names
the workspace the execution runs in, and every file is dropped when the
execution carries no workspace.
Also bounds `includeFileBase64` with an aggregate response ceiling and a
worker pool instead of an unbounded `Promise.all`, scopes the bulk
download's authorization resource to the workspace when folder paths are
requested, makes the folder-restore selector mutually exclusive at the
type level, and names the bound in the `maxBytes` validation message.
* fix(api): close v2 log review findings
Cursor scope: `scope` on the workflow and table lists carries
`.default('active')`, so it entered every fingerprint as a constant and
refused every cursor minted before the param existed — with the
"cursor does not match the requested filters" 400, which is actively
misleading for a caller that changed nothing. Both now stamp the
default as absent, so only a caller who asked for `archived` gets a new
sequence.
Dashboard stats: `maxWorkflows` capped the response, not the
allocation. Segment series are now densified after the cut instead of
before, so returning 200 series no longer materializes one
`segmentCount`-length array per workflow in the window. The aggregate
still sums every workflow, now from the sparse per-workflow maps.
Cost keyset: `cost_total` is an unconstrained `numeric`, so its anchor
travelled through `Number()` and was compared back at full precision —
rows differing beyond float64 collapsed onto one anchor. Adds
`decimalKey`, which carries the digit string and binds it `::numeric`.
Run detail: `cost_total` is a backfilled projection, so a run predating
the backfill reported `cost: null` even with a real ledger, making
`items` unreachable for exactly the runs the ledger explains. Falls
back to the ledger total.
Also caps the log folder-path index reads at MAX_FOLDERS_PER_WORKSPACE
like every other reader, publishing the folder-tree 413 on the four log
operations; reverts a dead `status` widening in `v2CommaListSchema`;
drops an unread `executionData` select; corrects the segment-count and
searchLogs prose; and replaces the sort-cursor SQL-text assertions with
a two-page walk over a fixture with a null block.
* fix(api): close knowledge v2 review findings
- widen knowledge.list_archived to the delete/restore policy so a workspace
API key can discover what it may restore
- escape LIKE wildcards on the now-public chunk search
- derive tag slot capacity from TAG_SLOT_CONFIG per field type
- type updateKnowledgeBase's chunkingConfig as ChunkingConfig and project
every declared field explicitly
- attribute a restore to the calling surface instead of a literal 'api'
- gate 'knowledge chunks batch-update' behind --yes, since it can delete
- present the tag-cleanup action from the parsed request rather than
faulting on the domain result after the delete committed
- unbind asserted-scope workspaceId from the nested knowledge cursors,
matching the table-row lists
- add executed-SQL coverage for the chunk keyset
* fix(catalog): close the catalog and registry-boundary review findings
The module-graph ratchet treated an entry with no baseline row as
informational, so the six catalog routes and the projection barrel were
unratcheted while the summary still read "within their module-count
baseline". An unbaselined entry now fails --check, the summary counts only
what was actually compared, and the baseline is re-recorded.
The Copilot block-metadata tool — the reason the shared projection exists,
6,756 modules down to 1,321 — was in no guarded subtree. It is now an entry
source and a catalog boundary root.
Catalog behaviour:
- hostedApiKey is gated on the deployment, so a self-hosted install reports
none instead of promising 127 tools' keys it will never supply
- block detail resolves an unversioned base type to its newest version and
projects through the viewer's visibility, so it can no longer 404 a block
the list contains or name it differently
- offset-cursor ordering compares code units rather than the process locale
- projections copy every array they publish instead of handing out the
registries' own
- an options function returning a thenable throws rather than silently
widening the providers-store substitution across the event loop
- a throwing block projection costs the Copilot tool one block, not all of them
- the trigger-kind log returns to debug: chat/manual/api are entry-point
kinds, not authoring defects
Also sweeps the custom-block detail branch against its response schema,
guards each projection module rather than the dead barrel over them, and
drops a provably dead branch in processHostedKeyCost.
* fix(workflows): close v2 workflow-authoring review findings
- Read a blockless draft back as an empty graph. `PUT /state` of
`{ blocks: {}, edges: [] }` — the contract's own published example —
deletes every block row, and the loader answers `null` for a blockless
workflow, so the following `GET /state` answered 404 while the list
endpoint still showed the workflow. Existence is the workflow row's to
decide; the null is now projected as an empty graph.
- Rewrite the `readWorkflowGraph` authorization test so it can fail. It
called `authorize?.()` and asserted only a negative, so deleting
`authorize` or replacing it with a no-op both passed — the invariant the
head-safe `HEAD` path depends on.
- Route `setWorkflowBlockEnabled` through `replaceWorkflowNormalizedState`,
the same door the other two graph writes use, instead of writing the
normalized tables itself without state preparation or custom-tool
extraction.
- Count applied operations directly. Enablement refusals landed in the same
skipped-item array and were subtracted from the operation count, which
`Math.max(applied, 0)` then masked when it went negative.
- Give a `disabled_ancestor` refusal its own member of the published skip
enum instead of reporting it as `block_locked`.
- Refuse an `atomic` batch whose credential or hosted API key would be
stripped, and carry the dropped inputs in the 409 details.
- Publish the whole lint report — `sources`, `sinks`, `orphanBlocks`,
`emptyOutgoingPorts`, `invalidBranchPorts`, `invalidConnectionTargets`,
`fieldIssues`, and the `kind` discriminator on unresolved references —
rather than only free-text reference prose.
- Stop reporting unresolved lint references as `inputValidationErrors`.
`collectUnresolvedReferences` is read-only, so those values stay
persisted; they were double-reported, and falsely as dropped inputs.
- Replace two unfalsifiable negative-principal tests, which used a
principal kind `Exclude`d from `PrincipalKind`, with a reachable one.
- Nits: drop a stranded TSDoc block; assert the membership predicate in the
selector-validator admin test; make the HEAD test assert a representation;
assert the sanitized graph is what `replaceWorkflowState` writes; add a
route test rejecting `baseGraph` in a v2 body; carry
`principalAuditSource` on restore/duplicate/moveBulk audit; unify the two
`base64MaxBytes` ceilings on `MAX_INLINE_MATERIALIZATION_BYTES`.
* fix(api): close seven v2 review findings, one an authorization bypass
Raise mcp_servers.workflow_deployments.update_server to admin: its body
carries isPublic, and a public server executes with no Sim credential, so a
write member could remove authentication from every workflow it publishes.
create_server already grants the same visibility at admin.
Pin the widened operations in registry tests — the six workflow-MCP ones,
the four workflow widenings, and files.extract_archive.
Reject secret fields on a credential that has no rotatable secret instead of
dropping them behind a 200, classify a non-transient provider 4xx as caller
error rather than a retryable outage, and reconcile a provider outage to 503
with Retry-After on all three surfaces.
Give /v2/meta a declarative principal policy through a new defineOperation
factory, carry the key expiry on the auth context instead of reading the
api_key table from the application layer, and make the impossible principal
branch an invariant error rather than a codeless 403.
Enforce the rollout-gate exemption at definition time, against the one
contract path it is reserved for, and remove the gate parameter from the
exported admission helper so the builder is its only door.
* fix(tables): bound the run-state sidecar, and close six v2 review findings
Enforces the 2 MiB run-state ceiling INSIDE the sidecar drain rather than
over its materialized result, refuses the unbounded query form paired with
it, and normalizes the two stored blobs the v2 surface publishes from bare
`as` casts.
- The run-state budget now travels into `loadExecutionsByRow`, which drains
row ids in bounded chunks and refuses before fetching the next one. The
post-hoc `requireBoundedRunState` walk is gone: it measured a spike that
had already happened, and re-serialized every entry to do it.
- Both row reads that accept `includeRunState` cap the page at
`V2_MAX_RUN_STATE_ROW_LIMIT`, and `POST /tables/{id}/query` additionally
refuses the flag paired with `limit: 0`.
- `runState.status` and the enrichment cascade blob are projected onto the
published shape before presentation; both were caller-reachable 500s on a
well-formed read.
- `sim tables bulk-delete` now gates behind `--yes`, and the CLI sweep that
should have caught it covers destructive non-DELETE forms.
- `POST /tables/{id}/restore` is idempotent (200, no audit) like its
knowledge sibling, and bulk folder selection deduplicates after resolution.
- The batch-update backstop keeps the looser Copilot ceiling and says so in
TSDoc: it is a backstop no surface reaches, because the contracts stop a
v2 caller at 1000 and the Copilot tool stops itself at 5000. Each caller
sees the bound that actually applies to it; neither surface's cap moved.
* fix(chat-deployments): close v2 chat review findings
Fixes the chat-deployments slice of the v2 review, several of which are
regressions the application-operation extraction introduced.
- Stop a `500` on schemaless JSONB: the response now declares a stored
shape without bounds and `toV2ChatDeployment` projects
`customizations`, `outputConfigs`, and `allowedEmails` onto it. The
request schemas keep `.strict()` and their bounds.
- Restore the specific validation message on `POST /api/chat` and
`PATCH /api/chat/manage/[id]`, and the deleted test that pinned it.
- Restore `chat_deployments.read` to workspace `admin`; the detail read
serves the visitor gate.
- Narrow the list projection so `chat_deployments.list` can stay a
`read` operation reachable by a workspace API key: `allowedEmails`,
`hasPassword`, and `customizations` are gone from the list entry and
available only from the admin-gated detail read. Serialized field by
field so a field added to the detail shape cannot reach the list by
default.
- Classify create-path failures: `performChatDeploy` carries an
`errorCode`, so an in-flight deployment is a `409` and an invariant
failure a `500` instead of every refusal being a `400`.
- Delete the callerless `GET /api/chat`, which served the encrypted
password column with no response contract.
- Propagate undeploy infrastructure failures instead of concealing them
as `404`, and return `ChatDeploymentView` from both delete paths.
- Name `CHAT_AUTH_MODE_NOT_PERMITTED` on the create path.
- Guard `getBaseUrl` inside `buildChatDeploymentUrl`, which otherwise
throws on a self-host with no `NEXT_PUBLIC_APP_URL`.
- Correct the published allow-list claim: a replacement `allowedEmails`
is applied after the auth-type clear, so it does survive.
- Assert `workspaceId` on the v2 detail routes and reconcile the
concealment TSDoc with what the error policy actually renders.
- Move `resolveActiveWorkspaceApplicationContext` to the workspaces
domain so chat-deployments no longer imports workflow application code.
* test(credentials): pin the reconciled provider-outage status
The internal route alone answered 502 where the v2 surface, the shared
status helper and `PROVIDER_OUTAGE_CODES`' own TSDoc all say 503. The
test pinned the divergence; it now pins the reconciliation, including the
`Retry-After` a 503 carries. Corrects a stale comment that still named
502 as the value callers see.
* fix(executor): restore cloud-storage Start files, dropped by the key rule
The ownership check accepted a key only when it could be parsed out of an
internal `/api/files/serve/...` URL. But the server-side uploader for run
inputs returns a *presigned cloud* URL whenever object storage is
configured, whose path is the bucket key — so every chat-deployment
attachment, API `files[]` payload and generic-webhook file field resolved
no key, and because normalization is all-or-nothing the entire `files`
input was dropped with no error. It passed locally and under vitest only
because the uploader falls back to an internal URL when no object storage
is configured, which is exactly why no test caught it.
The test is ownership, not provenance: a key is accepted when its own
layout names the executing workspace, whether it arrives directly or is
parsed out of the URL. Neither field has to be trusted, since both are
caller-authored and both are held to the same check. A payload whose key
and URL disagree is refused rather than resolved in the caller's favour —
a genuine uploader writes the two consistently, so only a forged pairing
is turned away.
`context` is now derived from the accepted key rather than read from the
payload or the URL's `?context=`, so an owned key can no longer be
labelled with a bucket its bytes do not live in — the hardening the
previous comment claimed but did not perform.
* fix(api): close four defects the fix pass introduced
- `resolveLatest` built a `RegExp` from the caller's block id and read the
registry with a bare lookup, so the catalog detail route — moved onto it
by the version-alias fix — routed around the `ownBlock` guard added for
exactly this. `GET /api/v2/blocks/%5B` was a `SyntaxError` 500 and
`.../constructor` an inherited function. Matched by string comparison
now, the way `tools/tool-ids.ts` resolves the same convention, and read
through `ownBlock`.
- The run-state byte budget was applied inside `queryRows` rather than at
the callers that publish it, so the first-party table grid — which reads
run state at five times the row limit and publishes no ceiling — turned
a large page into a hard failure, with an error naming a parameter it
does not expose. The budget is now an explicit option the public reads
pass and internal callers omit.
- Three graph-write CLI commands shipped ungated because the sweep meant
to catch them matched only the names already enumerated, so it could
never fail. It now forces every non-`GET` operation into a destructive
or non-destructive list, and the three carry confirmations.
- Unbinding `workspaceId` from the knowledge-documents cursor was right on
the merits and wrong in effect: the value is constant per sequence, so
removing it changed the fingerprint and refused every cursor already in
flight. Restored there; the chunks list is new in the same change and
keeps the cleaner reading.
* fix(api): resolve a detail read to a version the viewer can see
`getLatestBlockForViewer` took the newest version and then hid it, which
inverted the contradiction it was written to close: `slack_v2` and
`table_v2` are preview-gated while their v1 deliberately stays in the
toolbar, so an unrevealed viewer got a `404` on a detail read for a type
`GET /api/v2/blocks` was listing in the same breath. It now walks versions
newest-first and answers with the first one visible to that viewer.
Also:
- The chat password guard ran after `performFullDeploy`, so a request that
could never succeed burned a real workflow deployment version and then
answered 400. Its two sibling gate guards already refuse ahead of the
deploy; this one now does too.
- The Copilot sub-block serializer published the registry's own `options`
and `dependsOn` arrays by reference. Pre-existing, but the catalog
projection this parallels copies every array it publishes precisely
because they are process-global and shared by every request.
* fix(api): restore the locked read-modify-write and the password validator
Two findings verified as real regressions against staging, out of ten
checked — the rest were pre-existing, latent, or false.
`setWorkflowBlockEnabled` read the graph outside the row lock and wrote it
back inside a later transaction. The editor's own save takes that same
lock, so an autosave committing in the window was silently discarded: this
operation writes a whole graph, not a delta. The persistence primitive now
accepts a reader that runs after the lock is taken, and the toggle
re-reads and re-decides there. Its lock predicate is also scoped to the
workspace and to a live row again, so a workflow archived mid-flight is
refused rather than written.
The v2 chat-deployment contracts inlined their own password rule twice
instead of using `chatDeploymentPasswordSchema`, losing the refusal of a
whitespace-only password — which the internal contract rejects precisely
because it strands the deployment behind a password the visitor form will
not submit. Both sites use the canonical validator now.
* fix(api): one folder projection, one dynamic-provider list, honest 413s
- `toV2Folder` existed twice, and the second copy had been written without
the name/path invariant — so a row the list read refuses loudly would
have been served with a mismatched pair by the restore read. One
definition, guard included.
- The catalog projection restated `DYNAMIC_MODEL_PROVIDERS` and had
drifted by one member. Derived from the canonical list instead.
- The tables reads documented a `413` for run state that they cannot emit
— the budget became opt-in, and the row limit is the bound now — so the
claim is removed rather than declared. The workflow run read has the
opposite problem: it genuinely emits one, on a single file *or* the
run's inlined total, and declared neither. Now declared, and the
sentence covers both.
- Reclassifies the operations staging added into the destructive sweep, so
the triage stays exhaustive.
* fix(v2): classify storage and uniqueness failures, drop permanent file delete
- remove the permanent file-delete endpoint; the platform offers no such
action in the UI, and its manager wrote outside a transaction with no
storage accounting
- extract a generated document's text from its compiled artifact rather than
its generation source, matching the download path; a `.pdf` source was a
500 and a `.docx` source returned generator JavaScript as clean content
- report a run file whose object retention has already swept as 404 rather
than 500, on both the inline base64 read and the download stream
- report a knowledge tag that loses at a unique index as 409, naming whether
the slot or the display name is taken
- gate `workflows versions revert` behind a CLI confirm; it overwrites the
draft graph and was classified non-destructive
* feat(v2): report lint from both graph writes and add dry-run previews
- `PUT /workflows/{id}/state` now returns the same `lint` report as
`POST /operations`; an agent authoring a graph from scratch needs the
findings at least as much as one editing incrementally
- extract the report into one shared builder so the two writes cannot drift,
and one shared presenter so the wire shape is identical
- skip the credential/tool reference pass when the caller has no human
subject, rather than resolving it against the workspace billing owner:
that would misreport what the workflow can reach and disclose another
person's grants. `lint.notes` says when it was skipped
- add `?dryRun=true` to both graph writes: validates and lints, persists
nothing, records no audit, notifies nobody. A query param, not a body
field, since the body of a PUT is the resource itself
- CLI: a dry run no longer demands `--yes`; requiring confirmation to preview
a change teaches callers to pass `--yes` reflexively
- CLI: name the graph commands for their verbs — `workflows state get`,
`workflows state replace`, `workflows operations apply` — instead of the
derived `state list` / `state update` / `operations create`
- document when to use `rollback` vs `versions/{version}/activate` on both
* chore(docs): sync generated docs manifest for the new CLI pages
* feat(v2): add the missing workflow-MCP reads and align bulk naming
- add `GET /workflow-mcp-servers/{serverId}` and
`GET /workflow-mcp-servers/{serverId}/tools`. The resource could be
PATCHed and DELETEd but never read, and its tools could be published and
unpublished but never listed — the server list reports tool names only, so
nothing published the `workflowId` that addresses a tool for deletion.
Both mirror `mcp-servers` beside them, and carry that family's
workspace-API-key denial rather than the wider `mcp_servers.read` policy
- rename `POST /tables/bulk-move` to `POST /tables/move`, so tables matches
the shipped `files` resource exactly (`move` + `bulk-delete`)
- name the CLI commands for their operations instead of the derived
`... create`: `tables move`, `workflows move`, `tables bulk-delete`, and
`tables rows update-each` for the per-row batch, which sits beside the
existing filter-based `tables rows batch-update`
`POST /tables/{id}/rows/batch-update` keeps its name: a distinct payload per
resource is precisely AIP-234 BatchUpdate, and `bulk-` would have collided
one word away from the filter form.
* fix(v2): correct documented statuses and a caller-reachable 500
- duplicating a workflow into a locked destination folder answered 500:
`FolderLockedError` is a plain Error carrying `status = 423`, which the v2
error policy does not classify. Converted to OrchestrationError('locked')
at the application boundary, matching the bulk-move path
- restore workflow promised a 413 for an oversized folder tree that its
response list never published; the cap is real, so the status now is too
- move workflows and apply variables documented 409/423 they cannot emit:
every per-item lock and conflict is reported in `failed`, not thrown
- bulk download and delete knowledge tag can both 409 and did not say so;
cleanup tag definitions cannot and did say so
- apply workflow operations denies workspace API keys but never documented it
- the dry-run responses are not byte-identical to a committed write:
`needsRedeployment` describes the pre-write state and persistence warnings
cannot appear. Reworded rather than overclaimed
- read file text and get file upload are head-safe, so the "HEAD skips the
effect" sentence did not apply to them
* fix(v2): guard tag field-type changes and publish the 415 every body route can return
- `PATCH /knowledge/{id}/tags/{tagId}` accepted a `fieldType` incompatible
with the slot the tag already occupies. Slots are enumerated per field
type, so a text tag could be relabelled `number` and every later read
would interpret its values as the wrong type. Create checked this; update
now runs the same two checks
- derive `415` from the contract the way `413` already is: the JSON builder
answers UNSUPPORTED_MEDIA_TYPE for any body under a content type it cannot
read, so all 100 body routes could return a status none of them published
- give version activation its own result component instead of publishing it
as `RollbackResult`; the shipped rollback keeps that name
- correct descriptions that promised behaviour the code does not have: a
`processingStatus` field never returned, a `gmail_send` resolution example
that short-circuits, bucket widths that overflow the window, a bulk tag
save that relocates rather than overwrites, and per-server tool names
actually gathered under a page-wide budget
- drop 409 from three knowledge and upload reads that cannot emit it
* docs(v2): correct the upload transfer contract and 16 other published claims
The upload transfer step was documented as Sim's own data plane on every
deployment: "success is 204" and "a failure is the v2 error envelope". That
holds only when Sim stores objects itself. With object storage configured the
URL is the provider's presigned URL, so S3 and GCS answer 200 and Azure 201,
and a failure is the provider's XML — a client written to the old text reads a
successful cloud upload as a failure. Also states that part ETags do not need
retaining: completion takes no body because Sim lists the parts from the
provider itself.
Other corrections, all to shipped descriptions rather than behaviour:
- DELETE table and bulk-delete files archive rather than erase, and neither
said so; bulk delete also cannot emit the 409 it declared
- complete knowledge upload published a 402 only the create leg can raise
- billing status conceals a foreign workspace id as 404, not the 403 its
TSDoc and description both claimed
- audit entries null a folder's resourceId and strip folder ids from metadata
at every level; neither redaction was documented
- details=full adds the workflow summary to workflow runs only, never to job
runs; GET /logs folderPaths covers a subtree like its two siblings; getLog
now carries the retention sentence
- list secrets returns description too, and the logs and resources documents
described only part of what they serve
* improvement(api): consolidate the v2 surface and close seven defects
Endpoint consolidation:
- Fold POST /logs/query into GET /logs; add sortBy/sortOrder, cap the
comma lists, and move the list onto the shared keyset codec
- Fold GET /knowledge/archived into GET /knowledge?scope=archived,
matching files, tables, and workflows
- Re-home chat deployments as a singleton under the workflow they
belong to; keep the workspace-scoped discovery list
- Move the tag-definition writes off the document path onto
/knowledge/{id}/tags, where they already acted
- Nest the table export and dispatch reads under their parent table
Defects:
- Publish isPublicApi on the deployment read; it was write-only, so a
workflow could be opened to unauthenticated execution unauditably
- Stop publishing raw storage keys and an unusable URL in log files
- Classify a chat-identifier unique violation as 409 rather than 500
- Fall back to the root path instead of throwing when a knowledge
base's folder is archived
- Cap bulk-download at the ceiling it actually enforces
- Normalize variables through one helper on both graph write paths
- Fix a folder-name log filter that matched workflow names
Naming and gaps:
- Rename /files/{id}/extract to /unarchive, /rows/find to /rows/search,
/rows/batch-update to /rows/bulk-update, /columns/run to /dispatches
- Type the last six generic [id] path segments
- Add table folder restore and id-addressed dispatch cancel
* chore(audits): record the v2 catalog routes in the boundary baseline
* fix(api): accept a null chat password and correct three published claims
- performChatDeploy validated `password: null` as a password, so the
replace-shaped chat PUT answered 400 for every mode that owns no
password — public (the default), email, and sso. The declared payload
type has always allowed null, and the stored value is cleared by
authType regardless, so null needs no validation of its own. The route
test could not catch it: it mocks the orchestration module and pinned
the exact null the real guard refused.
- Redirect the two docs slugs this branch retired that were genuinely
published: findTableRows and runTableColumns.
- The table folder restore described an idempotent no-op for an already
active folder; it answers 404. Say so, and say where the path comes
from, since the tables folder list cannot yet report archived folders.
- Name the customizations exception to the chat PUT's replace semantics.
- A cursor-binding case used status=error, which is a level and not a
status, so it failed contract validation and never reached the cursor
check. Use an accepted value and pin the reason, not just the status.
* chore(cli): classify the new v2 chat operation as non-destructive
* feat(cli): expose canonical resource URLs
* fix(api): close three caller-reachable failures found by the final probe
- GET /files/{fileId}/text called parseBuffer unguarded, and parseBuffer
signals every failure as a bare Error that no v2 policy classifies. A
zero-byte upload or a mislabelled archive was an unhandled 500. Empty
bytes now answer empty text — a zero-length file has no text — and
unparseable bytes answer 409, matching the rendered-artifact resolver.
- GET /workflows/{workflowId}/state asserted write-side bounds over
stored data. workflow_blocks.name and .type are bare text() and the
realtime rename op accepts z.string(), so a block renamed past 255
characters made the workflow unreadable, and unrepairable, over v2.
The read shape now takes the same input/stored split the variable
schema already had. Stored subflow conditions are coerced in the
loader beside the existing numeric guards.
- GET /knowledge stamped scope into the cursor fingerprint
unconditionally. scope defaults to active and is new on that list, so
every cursor the deployed build handed out would have been refused
with a message saying the caller changed a filter they never sent.
Its siblings already carry the guard and the comment.
Also: POST /workflow-mcp-servers answers 201 like every other v2 create;
GET /logs/stats reuses the log list's entry ceilings; the execute and
resume routes install the media-type-aware 415 they publish; and a
rationale citing an endpoint that never reached the wire is corrected.
* fix(tables): carry the dispatch terminal timestamps through the stale sweep
Staging's abandoned-dispatch recovery builds its own `DispatchRow`, and
this branch had added `completedAt`/`cancelledAt` to that shape for the
id-addressed dispatch read and cancel. The merge was textually clean and
left the new mapping short two fields.
* fix(workflows): deny workspace API keys on the graph replace
`PUT /workflows/{workflowId}/state` stores blocks and their tool wiring
wholesale, but the policies deciding which of those a member may add —
the EE permission config and block visibility — take a human subject.
A workspace API key has none, and both substitutes fail open: the
billing owner is a different, typically less-constrained person, and
passing no user makes the permission lookup return null, which every
caller reads as unrestricted.
That made the replace a second graph-write door storing what its sibling
`POST /workflows/{workflowId}/operations` refuses, which denies workspace
keys for exactly this reason. Both doors now agree. Personal keys keep
the capability, so headless authoring is unaffected for a credential
that names a human.
* chore(api): drop the enrichment catalog endpoint
GET /api/v2/enrichments listed the code-defined table enrichments. The
per-row enrichment run detail stays; only the catalog read goes.
Removes the route, contract, response and query schemas, the semantic
operation, the use case, the projection module, its registry-boundary
entry, and the CLI command. The "not found" and "blank search" cases it
covered are repointed at the connector-type sibling so the shared
behaviour stays tested rather than deleted with it.
* improvement(api): make the workflow operations endpoint self-describing
Two things stood between this endpoint and a caller who has only the
published spec.
The accepted `params` keys existed only in the edit engine's source. The
spec said "the accepted keys depend on the target block type", so a
caller reading it could create a nameless empty block and nothing more —
while the Copilot tool catalog, over the same engine, has always spelled
out the envelope. That guidance now lives in the contract, shared by the
add, edit, and insert_into_subflow parameter schemas so the two surfaces
cannot describe one engine differently: `inputs` keyed by sub-block id,
`retry`/`triggerMode`/`advancedMode` beside it rather than inside it,
`connections` keyed by source handle, and `removeEdges` for dropping one
edge without restating the rest.
A `block_id` that is not already a UUID is replaced with a minted one,
and the mapping was computed and then dropped. A caller could not
reference the block it had just created except by re-reading the graph
and matching on name. The engine now returns it and the response
publishes it as `mintedBlockIds`, with the in-batch versus cross-request
rule stated in the operation description.
* fix(api): close the pre-merge scan's blocking findings
Docs and public wire, all of it permanent surface once released.
- Two published tag groups, Catalog and Meta, had no sidebar entry in any
locale, so six operations shipped unbrowsable. Added to all six, and a
test now fails when a published tag has no entry.
- deleteWorkflowChatDeployment pointed callers at DELETE on /deployment;
the undeploy verb is on /deploy.
- PUT /state still promised workspace API keys a degraded lint pass after
the operation began rejecting them outright. It also lived in a
single-quoted string, so the shared clause would not have interpolated.
- POST /tables/move took targetFolderPath as nullable-but-required, which
rendered the CLI flag as a required `<json|@file>`: `--to /Archive`
failed to parse and omitting it failed outright, while the docs said
"omit for root". Now optional and a plain string, matching
POST /files/move; the route supplies the null the use case wants.
- Table dispatch status and row run state published `cancelled` beside
imports, exports, and job state publishing `canceled`, and the note
explaining the split was wrong about its own sibling. Both new schemas
now publish `canceled`; the stored column is unchanged and mapped at
the presenter. The shipped `cancelled` count field is left alone.
- applyWorkflowVariables can answer 423 and both workflow-MCP deletes can
answer 409; none declared it. Hand-assembled error lists replaced with
the shared sets.
- /files/{fileId}/unarchive became /unzip. `extract` reads as "extract
text" and `unarchive` reads as the inverse of restore on a resource
where archived means soft-deleted; unzip collides with neither and is
what the implementation calls itself.
* improvement(cli,docs): finish the naming and clear the enrichment leftovers
- Four single-record GETs derived to `list` while returning one thing:
meta, a workflow's chat deployment, log stats, and file text. Renamed to
`meta status`, `workflows chat status`, `logs stats`, `files read`,
matching the `workflows deployment status` correction already in this
branch. None of the old spellings shipped.
- Dropped five `renamedFrom` aliases pointing at spellings that never
existed, each of which built a hidden command and a permanent
deprecation warning for argv nobody could have typed. `tables rows find`
keeps its alias — that one really shipped.
- Removed the enrichment catalog from three prose sites left behind when
the endpoint went: the resources spec description, its Catalog tag, and
the contract and pagination-test comments.
- Documented the six new command groups in the CLI index table. That page
is a guide page, so the docs staleness check cannot flag it.
- Published the `customizations` exception to the chat replace semantics.
It was in the route TSDoc and invisible to every caller reading the
spec, which is where the claim "Replace, not merge" is made.
* improvement(cli): use batch- for the tables bulk delete, matching its siblings
The CLI renames a bulk form only when it would collide with its singular
sibling, and uses AWS's `batch-` prefix when it does — `files
batch-delete`, `tables rows batch-delete`, `knowledge chunks
batch-update`. `tables delete` exists, so `tables bulk-delete` was that
same rename reaching for the other word, and the only `bulk-` command on
the surface. No `bulk-` CLI command has ever shipped, so this costs
nothing now and would be permanent later.
`files bulk-download` keeps its name: there is no `files download` to
collide with, and it is one archive rather than N operations. Its config
block now says why it exists at all, since the command is never built —
the builder skips non-JSON response modes, but the contract sweeps still
read the entry and require the folder-path field to be marked.
* fix(workflows): allow operations on blockless drafts
* feat(workflows): add manual and run-from-block execution
* fix(cli): update workflow run description test
* fix(tests): align fixtures with current contracts
* fix(api): derive chat activity from workflow deployment
---------
Co-authored-by: Theodore Li <theo@sim.ai>
9761 lines
349 KiB
JSON
9761 lines
349 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 update or disconnect.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Credential to update or 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 or disconnect.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"description": "Credential to update or 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."
|
||
}
|
||
}
|
||
],
|
||
"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. 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, replace, or delete.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"pattern": "^[A-Za-z0-9_]+$",
|
||
"description": "Secret to create, replace, or delete."
|
||
}
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"description": "Ownership scope and write-only value for the secret.",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/SetSecretRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "The existing secret value was replaced.",
|
||
"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 create, replace, or delete.",
|
||
"schema": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 255,
|
||
"pattern": "^[A-Za-z0-9_]+$",
|
||
"description": "Secret to create, replace, or 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 facts about the calling API key: whether it is in the v2 rollout cohort, whether it is personal or workspace-scoped, and when it expires. Every other v2 endpoint answers 404 both when the path does not exist and when your credential is not in the rollout cohort; call this endpoint to tell the two apart. It is the one v2 endpoint the rollout gate does not apply to, and it still requires a valid key.",
|
||
"tags": ["Meta"],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Rollout 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": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"maxLength": 65536,
|
||
"description": "Write-only secret value. It is never returned.",
|
||
"writeOnly": true
|
||
},
|
||
"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", "value"],
|
||
"additionalProperties": false,
|
||
"title": "Set secret request",
|
||
"description": "Ownership scope and write-only value for the secret.",
|
||
"examples": [
|
||
{
|
||
"workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
|
||
"scope": "workspace",
|
||
"value": "YOUR_SECRET_VALUE"
|
||
}
|
||
]
|
||
},
|
||
"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 credential is in the v2 rollout cohort. When false, every other v2 endpoint answers 404 for this credential."
|
||
},
|
||
"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": "Rollout 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": "Rollout cohort, 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."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"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
|
||
}
|
||
]
|
||
},
|
||
"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."
|
||
}
|
||
},
|
||
"required": ["data", "nextCursor"],
|
||
"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
|
||
}
|
||
]
|
||
},
|
||
"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. Resolve one with `GET /api/v2/tools/{toolId}`."
|
||
},
|
||
"operationIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Operations this block exposes. Their fields and tools are on `GET /api/v2/blocks/{blockId}`."
|
||
},
|
||
"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. Resolve one with `GET /api/v2/tools/{toolId}`."
|
||
},
|
||
"operationIds": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "Operations this block exposes. Their fields and tools are on `GET /api/v2/blocks/{blockId}`."
|
||
},
|
||
"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"
|
||
}
|