mirror of
https://github.com/simstudioai/sim.git
synced 2026-08-30 17:05:18 +08:00
Waleed
9b9f4ee596
* fix(v2-api): close two secret disclosures and align docs with signatures
Two P0 disclosures, five correctness bugs, and the standardization and
guard work that came out of auditing them.
**Secret disclosure — workflow version state.** `GET /api/v2/workflows/{id}/
versions/{version}` served the deployed graph unsanitized, so a read-role
workspace API key received plaintext block-password values and OAuth
credential ids. The sibling export route has always sanitized. Every other v2
response is protected structurally because the builder re-parses it, but this
field is `z.custom<WorkflowState>()` — a predicate that validates nothing —
which is why it survived earlier audits. Sanitization now lives in the use
case, secure by default, with a named `includeCredentialValues` opt-in that
only the session-authed deploy-preview route sets.
**Secret disclosure — MCP headers.** The internal list and update routes
returned custom `Authorization` headers verbatim to any read-role member;
headers are stored unencrypted. Values are now gated on write permission and
projected through one shared helper. The settings UI genuinely prefills from
them, so blanking outright would wipe headers on unrelated edits — write-only
headers plus encryption at rest are the follow-up.
Correctness:
- v2 execute ignored `X-Sim-Via`, resetting the call chain on every hop and
defeating the recursion guard. Wired on both the keyed and anonymous paths.
- v2 knowledge search accepted `searchMode` and dropped it, silently serving
vector-only results for a hybrid request, and allowed 50MB bodies where
internal caps at 2MiB.
- v2 run cancel never released the plan concurrency slot and half-cancelled
group runs; a group conflict now returns 409 instead of reporting success.
- v2 table row writes stamped no secret provenance, so the next internal read
reported the whole page incomplete. `secretProvenance` is now required on
the primitives, making the next omission a compile error.
- Folder conflicts and malformed paths returned 500; they are 409/404/400 now.
`FolderPathError` splits from `FolderHierarchyError` so a corrupt stored
tree stays a 500 and stays in 5xx alerting.
Standardization and documentation:
- `PUT /files/{id}/share` -> PATCH. The resource is not round-trippable
(`hasPassword`, never the password), so merge-on-omission is the only
implementable semantics.
- ~40 spec truthfulness fixes: a 410 the API cannot emit, eight 423s with no
lock guard, ~30 reachable-but-undocumented 404/400/413s, and six inverted
field claims. Eleven operations that always reject a workspace key now say
so — four of them answer 404, so a workspace key was told the resource did
not exist.
- `NAME_PATTERN` lost its `/i` through `z.toJSONSchema`, publishing 15
patterns that reject names the runtime accepts. Every generated client
rejected any capitalized table or column name, and two of the spec's own
examples failed the spec's own schema.
Guards, so these classes cannot recur:
- `check:route-verbs` (new) cross-checks all 212 builder routes' exported verb
and path against their contract. The builders only compare at runtime, so a
half-done rename previously passed CI and 500'd in production.
- Example validation now runs against the published JSON Schema with formats
on, covering 225 nodes instead of 100 — this is what caught the regex bug.
- The list-pagination sweep is union-aware and fails loudly on a schema it
cannot introspect, rather than counting it compliant.
* refactor(v2-api)!: flatten the single-resource response envelope
BREAKING: 31 endpoints that returned `{ data: { <resource>: T } }` now return
`{ data: T }`.
This corrects drift, not a design decision. PR #5273 added skills, custom
tools, MCP servers, secrets, and knowledge nested while adding workflows,
files, and logs flat — and in the same commit wrote the `v2/shared.ts`
docblock declaring `single resource: { data: T }` is the standard. The nested
half appears to have been modelled on the v2 tables surface (#6067), which
landed twelve days earlier. Lists were already `{ data: T[], nextCursor }`, so
flat single-resource is what actually matches them; nesting made every client
destructure a layer that carries nothing.
Doing it now because the cost only grows: `v2-api` is still dark-launched, so
today this breaks no one. After GA it needs a deprecation window.
Payloads that carry real information were deliberately left alone — this was a
classification exercise, not a mechanical sweep. Unchanged: delete
acknowledgements (`{ id, deleted }`, `{ path, deleted, deletedItems }`), the
knowledge search envelope (which echoes query, knowledgeBaseIds, topK and
totalResults alongside hits), upload payloads carrying signed tokens and
transfer instructions, bulk-operation counts, `{ row, operation }` upserts,
named acknowledgement scalars (`{ dispatchId }`, `{ cancelled }`), and
`{ columns: [...] }` — a collection, where a bare `{ data: T[] }` would be
indistinguishable from the list envelope but without `nextCursor`.
Also flattened the two file-share responses, which were not in the original
survey: leaving them would have put one resource in two shapes on one path.
`GET /files/{id}/share` now returns `{ "data": null }` when a file has never
been shared.
No consumer is affected. Both SDKs touch exactly two v2 endpoints — execute
and run status — and both were already flat. No docs MDX, client hook, or
internal caller reads a changed response; Copilot table tools call the
application use cases directly rather than the HTTP surface.
The shared `v2FolderSchema` is untouched: every folder flatten was achievable
at the response site, which is itself evidence flat was the intended shape.
* fix(v2-api): close a third secret disclosure and make concealment coherent
**Secret disclosure — run snapshot.** `GET /api/v2/logs/{runId}` returned
`workflowState` straight from `workflowExecutionSnapshots.stateData`, which is
the workflow graph: `blocks[].subBlocks[].value` holds `password: true` field
values and `oauth-input` credential ids. Nothing on that path sanitized it, and
the field was typed `z.unknown()`, so the builder's response parse stripped
nothing. A read-role workspace API key could read plaintext credentials.
This is the third instance of one pattern, and the pattern is the finding: the
builder protects every response by re-parsing it, so the only fields that can
leak are the ones typed `z.unknown()` or `z.custom()`. Both prior disclosures
sat behind exactly such a field. The snapshot is now sanitized in the use case
and the field is typed object-or-null. An inventory of every remaining
`z.unknown()` in the v2 contracts is in the PR description; two carry data with
no projection behind them and are named there as follow-ups.
**Concealment was bypassable.** `createV2ResourceConcealmentPolicy` rewrites
resource-authorization failures to 404 so a caller cannot probe for existence.
Workflows and files applied it on every verb; tables and knowledge applied it
only on reads. A caller could therefore probe with PATCH, read the 403, and
learn the resource exists — the read-side concealment bought nothing. Nine
mutation sites now conceal, plus the three table-column verbs, which were
inconsistent with their own sibling sub-resources.
`lib/logs/api/route-policies.ts` was a second, divergent implementation that
sniffed `response.status === 403` and so also swallowed workspace-policy
denials the canonical helper deliberately preserves. It now uses the helper. A
third such sniff survives in the upload-control helper and is noted as a
follow-up.
Also:
- `DELETE /tables/{tableId}/rows/{rowId}` returned the bulk `{deletedCount,
deletedRowIds}` shape while nine sibling single-resource deletes return
`{id, deleted}`. It now matches them.
- Nine operations can 404 on an unknown folder path and did not document it;
`createWorkflow` could 413 on an oversized folder tree and did not; getting a
run can 409 when trace data was truncated and did not.
- `queryTableRows` documented a 413 it cannot emit and `resumeWorkflowRun` a
423 with no lock guard anywhere in its path — the same un-producible-status
class already cleared for 410 elsewhere.
- Execute's 409 description covered only the run-id case after the
recursion-guard fix added a second cause, and named a code the route does not
emit: the wire carries `error.code: CONFLICT` with the specific cause in
`error.details.code`. `x-sim-via` is now a declared request header.
- Deploy and rollback published examples that were impossible: `isDeployed:
true` beside `activeDeployment: null`, where the route computes the former
from the latter.
- `afterRowId`/`beforeRowId` were published on row insert and silently dropped
by the route, so a positional insert became a tail append.
- A generated document whose script fails permanently answered "still being
generated, try again" forever; the underlying cause is now preserved.
* docs(v2-api): correct eleven false or misleading spec claims
Structural parity between contracts and specs is CI-enforced; semantic truth is
not. These are claims the spec made that the code does not honour.
Outright false:
- `DELETE /files/{fileId}` said it deletes "the stored bytes". It archives:
the row is retained with a deletion timestamp and the bytes are never
removed. Restore exists, but only on the internal API, so the description now
says so rather than implying v2 offers it.
- Execute documented `409 EXECUTION_ID_CONFLICT` in three places. The wire
carries `error.code: CONFLICT` with `error.details.code: RUN_ID_CONFLICT`;
only v1 ever emitted the documented string.
- The files spec claimed every endpoint uses the canonical envelopes while
`GET /files/{fileId}` returns octet-stream.
- The shared timestamp rule justified itself with a rendering claim that is
false — 29 bare-form sites publish `format: date-time` identically. The real
difference is runtime validation, so the rule now says that. It was softened
rather than enforced: responses are re-parsed, so adding `.datetime()` to a
field whose producer can emit a non-ISO string turns a working read into a
500, and that could not be proven for all 29 without a much larger audit.
Misleading:
- The billing ledger silently defaults to a 30-day window, so a client
paginating to `nextCursor: null` believes it has the whole ledger.
- Deleting a connector-backed knowledge document does not delete its chunks —
the row survives as excluded and the embeddings remain.
- `listTables` said "all tables"; it is keyset-paged with a default limit.
- `GET /files/{id}/share` omitted the `data: null` never-shared case its own
schema and example already declare.
- The share PATCH matrix omitted two hard 400s, so following it literally
against a never-shared file fails.
- Five knowledge operations render a canonical folder path back and can 413 on
an oversized tree without carrying the sentence that says so.
Also: the upload-control helper was a third implementation of concealment by
sniffing `response.status === 403`, which masks workspace-policy denials the
canonical helper deliberately preserves. It now uses the shared policy, so
those denials keep their 403. And the shared docblock's search-field
enumeration was presented as exhaustive while omitting two lists, and its
error-envelope claim omitted the two upload data-plane routes that emit a bare
`{error: string}` — both now carry the carve-out the CI allowlist already had.
* test(v2-api): align upload concealment test with cross-tenant-only semantics
#6557 narrowed `createV2ResourceConcealmentPolicy` to conceal only the three
cross-tenant authorization classes, deliberately letting a same-workspace
policy denial keep its 403 so the caller learns why. My test predated that and
asserted a workspace-key denial was concealed as 404.
Split into two cases that pin the distinction rather than paper over it: a
cross-tenant reach conceals, a workspace-key policy denial does not.
* fix(v2-api): accept the redacting log status and envelope the knowledge-search 413
The v2 log presenters parsed status against a five-value enum, but the
execution logger persists a sixth, redacting, while a finished run's output
is scrubbed. Any such row failed the response parse; on the list route one
row 500'd the whole page. The enum is now derived from
PersistedWorkflowExecutionStatus with a compile-time exhaustiveness
assertion, so a future status is a type error rather than a production 500.
POST /api/v2/knowledge/search declared maxBodyBytes without
payloadTooLargeResponse, so its 413 returned a bare string instead of the v2
error envelope. It now matches the sibling deploy/rollback routes.
* fix(uploads): restore archive extraction folder parity
Archive extraction into workspace files/ was rewritten onto the authorized
application-operation boundary, and three behavioral regressions came with
that move. Together they broke every archive containing a subdirectory, and
100% of copilot extract() calls (materialize-file always passes
rootFolderSegments: [baseName], and its catch only handles ArchiveError).
1. Non-canonical folder path. The extractor joined the folder segments with
"/" and passed the result as `path` to createWorkspaceFileFolderOperation.
That path reaches requireNonRootFolderPath -> parseFolderPath, which
requires a leading "/" and byte-for-byte canonical per-segment encoding,
so "bundle/data" threw FolderPathError before anything was written — and
a folder name containing a space or a reserved character would still have
thrown after merely prefixing a slash.
2. exactName: true. createWorkspaceFileFromBuffer was told to demand the
exact leaf name, which sets maxAttempts = 1 and raises FileConflictError
when the name already exists. The extractor's rollback then deleted every
file written so far, so one colliding name destroyed the whole
extraction. Reachable today for flat archives through the unzip action of
POST /api/tools/file/manage. Restored to auto-suffixing via
allocateUniqueWorkspaceFileName.
3. Wrong folder primitive. createWorkspaceFileFolderAtPath creates exactly
one leaf, conflicts on an existing path, and requires the parent to exist
already. The extractor never creates intermediates and caches by full
path, so the first nested entry asked for a folder whose parent was never
created. The correct semantics are ensureWorkspaceFileFolderPath: walk
every segment, reuse what exists, create only what is missing.
Rather than bypass the operation boundary by calling the manager primitive
directly, this adds ensureWorkspaceFileFolderPathOperation — an authorized
application use case under files.folders.create that expresses "ensure this
whole chain exists" — and routes the extractor through it with raw decoded
segments, so no path string is built and no encoding can be malformed.
archive.test.ts previously mocked the folder operation and asserted the
broken shape (path: 'bundle'), which is why this shipped. The suite now
fakes the workspace-file store in memory while enforcing the real rules:
folder paths run through the production parseFolderPath family, the
create-one-leaf operation conflicts and requires a parent, and exactName
governs conflict vs auto-suffix. Nested, reuse, encoded-name, and collision
cases are covered and each fails against the pre-fix code.
* chore(files): tidy archive extraction cleanup
* fix(uploads): roll back folders archive extraction created
Extraction now materializes folders before uploading files, but the failure
path only deleted the extracted files — every folder the call created was left
behind. That is not cosmetic: `materialize_file` guards re-extraction by looking
up the root folder path and refusing when it has any child, so a half-extracted
nested archive turned every retry into "already extracted — delete that folder
first" until a human cleaned up the tree by hand.
The rollback must delete only folders this call actually inserted, never one it
reused: extracting into an existing path is normal (a sibling entry, an earlier
successful extraction), and deleting a pre-existing folder would destroy
unrelated user data. `ensureWorkspaceFileFolderPath` already distinguishes the
two while walking the segment chain, so it (and its application operation) now
reports `createdFolderIds` alongside the leaf id. The extractor accumulates
those ids in creation order and, on failure, deletes them in reverse — parents
are recorded before their children, so reverse order is deepest-first and a
parent is never removed out from under a child. Folder cleanup is best-effort
like the existing file cleanup, so a cleanup failure never masks the original
error.
* fix(billing): withhold the payer credit pool from v2 status readers
`GET /api/v2/billing/status` resolved the workspace's payer and projected
that payer's pooled allowances — credits used, credit limit, credits
remaining, and the payer entity's storage usage and quota — to any caller
holding only `read` on the workspace, including a personal API key. The
payer pool is shared across every workspace that payer funds, and the
platform already treats it as privileged: the workspace credit-availability
surface computes `canViewPayerPool` from `canManageWorkspaceBilling` and
substitutes member-scoped or null figures for everyone else. The new
versioned endpoint had no equivalent gate.
`credits` and `storage` are now projected only to a caller who may manage
the resolved payer's billing: the billed account holder of a personally
hosted workspace, an admin of the hosting organization, or a workspace API
key, which only a workspace admin can provision. The endpoint stays at
`read` so a plain member keeps the plan, period, and standing the workspace
UI already shows them, and an exceeded pooled limit still reports as
`limit_exceeded` without disclosing the numbers behind it. Both fields are
nullable on the wire and in the regenerated OpenAPI spec.
The decision lives in the application use case, resolved from canonical
workspace state, not in the route: billing authority is payer identity and
organization role, which the workspace permission ladder cannot express —
a plain workspace `admin` is deliberately not enough.
* chore(api): remove the unused public API route builder and dead endpoint labels
`withPublicApiRouteHandler` and 27 `ApiEndpoint` union members landed together
in #5273, but the v2 surface shipped on `defineV2JsonRoute` + `v2RateLimits`
instead. The builder had no production caller — only its own test — and the v2
rate limiter never reads an `ApiEndpoint` label, so those members were never
emitted to telemetry by symbol or by string literal.
Remaining members are exactly the labels a v1 route passes to `checkRateLimit`
or `authenticateRequest`. Drops the now-unreachable `hasZodUsage` branch from
the API validation audit; no ratchet metric moves (route total stays 1093).
* fix(billing): deny the payer pool to actor-less workspace API keys
The first pass gated `credits` and `storage` on billing authority for
personal API keys but let a `workspace_api_key` principal through
unconditionally, which left the excluded role a way back in. Any workspace
`admin` may mint a workspace API key, and a workspace `admin` is
deliberately not a billing manager, so an admin who reads `null` as
themselves could mint a key and read the full pool with it. On an
organization-hosted workspace that pool is the organization's, spanning
workspaces the admin has no standing in.
Billing authority is payer identity or an organization admin role — a
property of a person. A workspace API key is deliberately actor-less, so it
can never satisfy it and now reads both fields as `null`. Attributing the
key to its creator was rejected: it would launder the same workspace-admin
role, it breaks when the creator's authority is revoked while the key lives
on, and substituting a key's owner for the acting principal is what the
application operation boundary forbids. The reasoning sits in TSDoc at the
decision point.
The key keeps the plan, period, and standing it needs to monitor a
workspace, including `limit_exceeded` and `billing_blocked`. No in-repo
caller reads `credits` or `storage` from this endpoint. The payer storage
pool is now read only once disclosure is authorized, so a caller who may
not see it no longer triggers the query at all.
* fix(folders): bound the workflow folderId-branch path index reads
`createWorkflow` and `updateWorkflow` each resolve a folder two ways inside one
function. The folderPath branch goes through `resolveWorkflowFolderPath`, which
loads the path index with `maxRows: MAX_FOLDERS_PER_WORKSPACE`; the folderId
branch loaded it with no bound at all, issuing a `SELECT` over every active
folder row in the workspace. In `updateWorkflow` the unbounded read and the
bounded fallback sit thirty lines apart in the same function.
Passes the cap at both sites, matching the read sites that already opt in.
Exceeding it throws `FolderCollectionLimitExceededError` rather than truncating,
because a partial path index resolves real folder paths to `undefined` and
re-roots resources at the workspace root.
`maxRows` deliberately stays opt-in rather than becoming the default. Folder
creation does not refuse at the same ceiling on every path — `POST /api/folders`
goes through the `createFolder` name/parentId variant, which passes no
`maxFolderRows`, so the count guard in `executeCreateFolderAtPath` never runs
and a workspace can already hold more than `MAX_FOLDERS_PER_WORKSPACE` folders.
Defaulting the bound would make every path-index consumer throw for a state the
product allows to exist. Reconciling reader and writer is a separate change with
a user-facing limit, not a chore.
* chore(billing): tidy payer-pool concealment cleanup
* fix(api): reject an undecodable offset cursor on v2 table rows
GET /api/v2/tables/{tableId}/rows coerced an undecodable pagination cursor to
offset 0 and re-served page one. A client paging forward reads that as a fresh
first page and can loop over it forever. Every sibling v2 cursor list — logs,
files, workflows, workflow runs, workflow versions, workspace members, tables,
knowledge documents — already rejects with a validation error instead.
Extracts the offset-cursor decode both offset-paginated v2 routes had inlined
into `decodeOffsetCursor`, next to the existing `decodeSortedCursor`, so the
reject-don't-restart rule has one home.
* fix(api): restore v1 table error-response parity and stop internal message leak
The v1 table routes were rewritten to consume `lib/table/orchestration`
results, and two response behaviors drifted from what the live API returned.
Information disclosure: an unclassified failure's `outcome.error` carries
whatever text the fault happened to have. Drizzle wraps a throw raised inside
a transaction in an error whose own message is the failed statement and its
bound parameters, so `DELETE /api/v1/tables/{tableId}` and
`DELETE /api/v1/tables/{tableId}/rows/{rowId}` returned that verbatim in the
500 body to any API-key holder. Previously these returned a fixed generic
string.
Lost `lock` field: the 423 body used to be `{ error, lock }`. The delete,
row-delete, and column-update routes (v1 and internal) dropped the lock kind
the orchestration result already computes, leaving clients unable to tell
which lock to clear.
Both are fixed at one altitude: `orchestrationOutcomeErrorResponse` in
`app/api/table/utils.ts` is now the only way a table route projects an
orchestration failure onto the wire. It renders the route's fallback for an
unclassified failure and the real message for a classified one (validation,
not-found, conflict, locked keep their specific text), and carries `lock` on a
423. A future route cannot reintroduce either bug by hand-spelling the body.
Duplicate table names on `POST /api/v1/tables` keep answering 409 rather than
reverting to the previous 400. 409 is the correct semantic, and every other v1
duplicate-name surface (knowledge, files, workflow import) already answers 409;
the tables 400 was the outlier. v1 tables appears in no published OpenAPI
document and no in-repo client branches on the status, so the compatibility
cost is limited to a caller matching 400 specifically for a name collision.
* fix(skills): only reject a built-in name collision on an actual rename
The built-in-name guard ran on every update that carried a `name`, without
comparing it to the skill's current persisted name. Skills created before the
guard existed can legitimately carry a built-in's name (they simply shadowed
the built-in at read time), and the skill modal always submits the full object
including the unchanged name — so every save of such a skill returned 400 with
"The skill name ... is reserved by a built-in skill", with no way to fix it
short of renaming.
Move the guard in `updateSkill` to after the canonical row is loaded and run it
only when the submitted name differs from the current one. Creating a skill
with a built-in name, and renaming an existing skill into one, are still
rejected. The check stays in the shared orchestration primitive because that is
the only layer both the internal `/api/skills` adapter (via `performUpdateSkill`)
and `updateSkillUseCase` (v2 + Copilot) pass through, and it is where the
current name is in hand.
* chore(tables): tidy v1 error projection cleanup
* chore(skills): tidy collision guard cleanup
3933 lines
134 KiB
JSON
3933 lines
134 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, and write-only secrets.",
|
|
"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": "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": "List OAuth and service-account connections without secret material."
|
|
},
|
|
{
|
|
"name": "Secrets",
|
|
"description": "Set and manage write-only workspace and personal secret values."
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"apiKey": []
|
|
}
|
|
],
|
|
"paths": {
|
|
"/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,
|
|
"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,
|
|
"description": "Workspace to retrieve."
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Maximum members to return. Defaults to 50 and cannot exceed 100.",
|
|
"schema": {
|
|
"default": 50,
|
|
"description": "Maximum members to return. Defaults to 50 and cannot exceed 100.",
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 100
|
|
}
|
|
},
|
|
{
|
|
"name": "cursor",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Opaque cursor returned by the preceding page.",
|
|
"schema": {
|
|
"description": "Opaque cursor returned by the preceding page.",
|
|
"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 bounded workspace set uses the standard cursor envelope with `nextCursor` always null; there is no second page to fetch.",
|
|
"tags": ["MCP Servers"],
|
|
"parameters": [
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "Workspace that owns the MCP server.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"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.",
|
|
"schema": {
|
|
"default": "createdAt",
|
|
"description": "Field used to sort the result.",
|
|
"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"]
|
|
}
|
|
}
|
|
],
|
|
"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 determines server identity, must be absolute HTTP or HTTPS, and cannot contain environment-variable references. Header values and OAuth client secrets are write-only. `transport`, `timeout`, `retries`, and `enabled` are applied server-side when omitted; the effective values are in the response.",
|
|
"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"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
},
|
|
"500": {
|
|
"$ref": "#/components/responses/InternalError"
|
|
},
|
|
"503": {
|
|
"$ref": "#/components/responses/ServiceUnavailable"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v2/mcp-servers/{id}": {
|
|
"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": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "MCP server to retrieve, update, or delete.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "MCP server to retrieve, update, or delete."
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "Workspace that owns the MCP server.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"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. The URL is immutable because it determines server identity; delete and recreate the server to change endpoints. Two fields do not follow the omitted-fields-are-retained rule. `headers` is replaced wholesale rather than merged: sending it drops every stored header it does not repeat, and the only way to keep a header is to resend it. Changing `oauthClientId`, or sending `oauthClientSecret` as null or a new value, revokes the stored OAuth grant and forces reauthorization; switching away from OAuth authentication revokes it too.",
|
|
"tags": ["MCP Servers"],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "MCP server to retrieve, update, or delete.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "MCP server to retrieve, update, or delete."
|
|
}
|
|
}
|
|
],
|
|
"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"
|
|
},
|
|
"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": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "MCP server to retrieve, update, or delete.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "MCP server to retrieve, update, or delete."
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "Workspace that owns the MCP server.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"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/skills": {
|
|
"get": {
|
|
"operationId": "listSkills",
|
|
"summary": "List Skills",
|
|
"description": "List workspace and built-in skills. Built-ins are marked read-only. The list omits skill bodies and uses the standard cursor envelope with `nextCursor` always null, so there is no second page to fetch; 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,
|
|
"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.",
|
|
"schema": {
|
|
"default": "createdAt",
|
|
"description": "Field used to sort the result.",
|
|
"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"]
|
|
}
|
|
}
|
|
],
|
|
"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. Note that a workspace API key may create a skill but may not later update or delete it.",
|
|
"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"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
},
|
|
"500": {
|
|
"$ref": "#/components/responses/InternalError"
|
|
},
|
|
"503": {
|
|
"$ref": "#/components/responses/ServiceUnavailable"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v2/skills/{id}": {
|
|
"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": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Skill to retrieve, update, or delete. Built-in skills use their name as the id.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Skill to retrieve, update, or delete. Built-in skills use their name as the id."
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "Workspace that owns the skill.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"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 cannot call this operation and is rejected with `403`; use a personal API key.",
|
|
"tags": ["Skills"],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Skill to retrieve, update, or delete. Built-in skills use their name as the id.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Skill to retrieve, update, or delete. Built-in skills use their name as the id."
|
|
}
|
|
}
|
|
],
|
|
"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"
|
|
},
|
|
"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 cannot call this operation and is rejected with `403`; use a personal API key.",
|
|
"tags": ["Skills"],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Skill to retrieve, update, or delete. Built-in skills use their name as the id.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Skill to retrieve, update, or delete. Built-in skills use their name as the id."
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "Workspace that owns the skill.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"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/custom-tools": {
|
|
"get": {
|
|
"operationId": "listCustomTools",
|
|
"summary": "List Custom Tools",
|
|
"description": "List code-backed custom tools defined in a workspace. Legacy personal tools are excluded. The bounded workspace set uses the standard cursor envelope with `nextCursor` always null; there is no second page to fetch.",
|
|
"tags": ["Custom Tools"],
|
|
"parameters": [
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "Workspace that owns the custom tool.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"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"]
|
|
}
|
|
}
|
|
],
|
|
"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"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
},
|
|
"500": {
|
|
"$ref": "#/components/responses/InternalError"
|
|
},
|
|
"503": {
|
|
"$ref": "#/components/responses/ServiceUnavailable"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v2/custom-tools/{id}": {
|
|
"get": {
|
|
"operationId": "getCustomTool",
|
|
"summary": "Get Custom Tool",
|
|
"description": "Fetch one custom tool by identifier, scoped to its workspace.",
|
|
"tags": ["Custom Tools"],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Custom tool to retrieve, update, or delete.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Custom tool to retrieve, update, or delete."
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "Workspace that owns the custom tool.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"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": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Custom tool to retrieve, update, or delete.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Custom tool to retrieve, update, or delete."
|
|
}
|
|
}
|
|
],
|
|
"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"
|
|
},
|
|
"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": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Custom tool to retrieve, update, or delete.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Custom tool to retrieve, update, or delete."
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "Workspace that owns the custom tool.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"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. Credential mutations and single-resource reads are intentionally not exposed. The bounded set uses the standard cursor envelope with `nextCursor` always null; there is no second page to fetch.",
|
|
"tags": ["Credentials"],
|
|
"parameters": [
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "Workspace whose credentials should be listed.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"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"]
|
|
}
|
|
}
|
|
],
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v2/secrets": {
|
|
"get": {
|
|
"operationId": "listSecrets",
|
|
"summary": "List Secrets",
|
|
"description": "List workspace and caller-owned personal secret metadata. Only names, scope, role, and timestamps are returned; secret values are never read or returned. The bounded set uses the standard cursor envelope with `nextCursor` always null; there is no second page to fetch. A workspace API key cannot call this operation and 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,
|
|
"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.",
|
|
"schema": {
|
|
"default": "name",
|
|
"description": "Field used to sort the result.",
|
|
"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"]
|
|
}
|
|
}
|
|
],
|
|
"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 cannot call this operation and 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"
|
|
},
|
|
"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 cannot call this operation and 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 in which the secret is available.",
|
|
"schema": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "Workspace in which the secret is available."
|
|
}
|
|
},
|
|
{
|
|
"name": "scope",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "Whether the secret belongs to the workspace or the caller.",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": ["workspace", "personal"],
|
|
"description": "Whether the secret belongs to the workspace or the caller."
|
|
}
|
|
}
|
|
],
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"apiKey": {
|
|
"type": "apiKey",
|
|
"in": "header",
|
|
"name": "X-API-Key",
|
|
"description": "Your Sim API key, personal or workspace-scoped. Generate one from the Sim dashboard under Settings > API Keys. A workspace API key is not accepted everywhere: operations that act on behalf of a specific human — administrative reads, secret access, and irreversible or governance-affecting writes — always reject it, whatever role the key carries. Each such operation says so in its own description, and the rejection surfaces as `403` unless the operation conceals unauthorized resources, in which case it is reported as `404`. Use a personal API key for those."
|
|
}
|
|
},
|
|
"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 a rate-limited request.",
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"maximum": 9007199254740991,
|
|
"title": "Retry after",
|
|
"description": "Seconds to wait before retrying a rate-limited request."
|
|
}
|
|
},
|
|
"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.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Unauthorized": {
|
|
"description": "The API key is missing or invalid.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"UsageLimitExceeded": {
|
|
"description": "The workspace has exceeded its usage or billing limits.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Forbidden": {
|
|
"description": "The caller lacks access to the resource.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"NotFound": {
|
|
"description": "The requested resource was not found.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Conflict": {
|
|
"description": "The request conflicts with current resource state.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"RunIdConflict": {
|
|
"description": "The run cannot be started. Two causes share this status, distinguished by `error.details.code`: `RUN_ID_CONFLICT` when the supplied `X-Run-Id` is already associated with a different request, and `CALL_CHAIN_DEPTH_EXCEEDED` when the incoming `X-Sim-Via` chain has already reached the maximum workflow-to-workflow call depth.",
|
|
"headers": {
|
|
"X-Run-Id": {
|
|
"$ref": "#/components/headers/X-Run-Id"
|
|
}
|
|
},
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Gone": {
|
|
"description": "The requested generated resource has expired.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"PayloadTooLarge": {
|
|
"description": "The request, or a resource collection it must materialize, exceeds the allowed size. Besides an oversized request body, this covers a generated artifact that renders past the download ceiling and a workspace folder tree too large to load in full.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"UnsupportedMediaType": {
|
|
"description": "The request uses an unsupported media type.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Locked": {
|
|
"description": "The resource is locked and cannot be modified.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ClientClosedRequest": {
|
|
"description": "The client closed the connection before the response was produced.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"InternalError": {
|
|
"description": "An unexpected server error occurred.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ServiceUnavailable": {
|
|
"description": "A required service is temporarily unavailable.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/V2Error"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": "Optional structured error details."
|
|
}
|
|
},
|
|
"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,
|
|
"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."
|
|
},
|
|
"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 for an explicitly granted member whose own organization differs from the workspace's; false for the workspace owner and for a member sharing the workspace organization. Inherited organization-administrator access is always reported as false, so this is not a signal that access came from outside the explicit member list."
|
|
},
|
|
"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, or null when no more items remain. Always null on a full-set list, which returns its whole result set in one response."
|
|
}
|
|
},
|
|
"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.",
|
|
"type": "string",
|
|
"enum": ["connected", "disconnected", "error"]
|
|
},
|
|
"lastError": {
|
|
"description": "Message from the most recent failed connection, or null when absent.",
|
|
"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.",
|
|
"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, or null when no more items remain. Always null on a full-set list, which returns its whole result set in one response."
|
|
}
|
|
},
|
|
"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": "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
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"CreateMcpServerRequest": {
|
|
"type": "object",
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"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."
|
|
},
|
|
"authType": {
|
|
"description": "Authentication method. Sim detects it from the server when omitted.",
|
|
"type": "string",
|
|
"enum": ["none", "headers", "oauth"]
|
|
},
|
|
"headers": {
|
|
"description": "Write-only request headers sent to the server.",
|
|
"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.",
|
|
"anyOf": [
|
|
{
|
|
"type": "string",
|
|
"maxLength": 512
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
},
|
|
"oauthClientSecret": {
|
|
"description": "Write-only pre-registered OAuth client secret.",
|
|
"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,
|
|
"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. Sim detects it from the server when omitted.",
|
|
"type": "string",
|
|
"enum": ["none", "headers", "oauth"]
|
|
},
|
|
"headers": {
|
|
"description": "Write-only request headers sent to the server.",
|
|
"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.",
|
|
"anyOf": [
|
|
{
|
|
"type": "string",
|
|
"maxLength": 512
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
},
|
|
"oauthClientSecret": {
|
|
"description": "Write-only pre-registered OAuth client secret.",
|
|
"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
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"V2SkillSummary": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique skill identifier. Built-in skills use their name as the id."
|
|
},
|
|
"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, or null when no more items remain. Always null on a full-set list, which returns its whole result set in one response."
|
|
}
|
|
},
|
|
"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. Built-in skills use their name as the id."
|
|
},
|
|
"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,
|
|
"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,
|
|
"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
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"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, or null when no more items remain. Always null on a full-set list, which returns its whole result set in one response."
|
|
}
|
|
},
|
|
"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,
|
|
"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,
|
|
"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, or null when no more items remain. Always null on a full-set list, which returns its whole result set in one response."
|
|
}
|
|
},
|
|
"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
|
|
}
|
|
]
|
|
},
|
|
"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 the caller."
|
|
},
|
|
"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", "role", "createdAt", "updatedAt"],
|
|
"additionalProperties": false,
|
|
"title": "Secret metadata",
|
|
"description": "Public secret metadata without the stored secret value."
|
|
},
|
|
"ListSecretsResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/V2Secret"
|
|
},
|
|
"description": "Items in the current page."
|
|
},
|
|
"nextCursor": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Opaque cursor for the next page, or null when no more items remain. Always null on a full-set list, which returns its whole result set in one response."
|
|
}
|
|
},
|
|
"required": ["data", "nextCursor"],
|
|
"additionalProperties": false,
|
|
"title": "List secrets response",
|
|
"description": "Secret metadata visible to the caller without stored values.",
|
|
"examples": [
|
|
{
|
|
"data": [
|
|
{
|
|
"name": "STRIPE_API_KEY",
|
|
"scope": "workspace",
|
|
"role": "admin",
|
|
"createdAt": "2026-06-01T09:14:00.000Z",
|
|
"updatedAt": "2026-06-20T14:02:11.000Z"
|
|
}
|
|
],
|
|
"nextCursor": null
|
|
}
|
|
]
|
|
},
|
|
"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",
|
|
"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,
|
|
"description": "Workspace in which the secret is available."
|
|
},
|
|
"scope": {
|
|
"type": "string",
|
|
"enum": ["workspace", "personal"],
|
|
"description": "Whether the secret belongs to the workspace or the caller."
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"maxLength": 65536,
|
|
"description": "Write-only secret value. It is never returned.",
|
|
"writeOnly": true
|
|
}
|
|
},
|
|
"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 the caller."
|
|
},
|
|
"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
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"x-generated-by": "scripts/generate-openapi.ts"
|
|
}
|