# Sidenet API

- [Authentication](https://sidenet.ai/docs/authentication.md): How to authenticate requests and scope them to an organization.
- [MCP server](https://sidenet.ai/docs/mcp-server.md): Connect Claude, Cursor, or any MCP client to your Sidenet organization.
- [Prompt blocks & variables](https://sidenet.ai/docs/prompt-blocks.md): Compose an agent's system prompt from reusable, versioned blocks with runtime variables and display conditions.
- [Overview](https://sidenet.ai/docs/api-reference/overview.md): Sidenet REST API reference
- [Mint session token](https://sidenet.ai/docs/api-reference/authentication/mint-session-token.md): Exchanges your organization API key for a short-lived access token scoped to one end user, safe to hand to a browser.
- [Refresh session token](https://sidenet.ai/docs/api-reference/authentication/refresh-session-token.md): Rotates a session. Safe to call directly from the browser — it takes no API key and no identity fields.
- [List runtime auth providers](https://sidenet.ai/docs/api-reference/authentication/list-runtime-auth-providers.md): Lists the organization's tool providers and, for each, the credential fields a `tools_auth` entry should carry — the map sent to POST /v1/token or `PATCH /v1/users/{userId}`. Key entries by `providerId`; provider names can change, ids do not.
- [List users](https://sidenet.ai/docs/api-reference/users-&-groups/list-users.md): Lists the organization's end users, newest first. `id` fetches exactly one; `group_id` narrows to a group's members. `credential_providers` names the providers each user has stored credentials for — ids only, never the credentials themselves.
- [Create user](https://sidenet.ai/docs/api-reference/users-&-groups/create-user.md): Creates an end user ahead of use, so their group, display name and tool credentials are in place before their first session or scheduled workflow.
- [Update user](https://sidenet.ai/docs/api-reference/users-&-groups/update-user.md): Updates an end user without minting a new session token: their display name, their per-provider tool credentials, and/or their group.
- [List groups](https://sidenet.ai/docs/api-reference/users-&-groups/list-groups.md): Lists the organization's groups, newest first. `id` fetches exactly one; `user_id` fetches the group that user belongs to. When either filter is given, the (single) result also carries `month_spend` and `limit_remaining`; the plain listing reports the cap only.
- [Create group](https://sidenet.ai/docs/api-reference/users-&-groups/create-group.md): Creates a group ahead of use, so its monthly spend cap is in place before the first user or session references it.
- [Update group](https://sidenet.ai/docs/api-reference/users-&-groups/update-group.md): Updates a group: its display name and/or its monthly spend cap.
- [Stream chat](https://sidenet.ai/docs/api-reference/chat/stream-chat.md): Build and stream responses from an agent or network of agents. Provide either agentId or copilotId (the id of a network).
- [Run agent](https://sidenet.ai/docs/api-reference/chat/run-agent.md): Runs the agent's active published version against `messages`. Send `agentVersionId` to run a specific version (a draft, or an older published one) instead. Returns the finished turn as JSON: `text` is the answer, `toolCalls` what the agent called on the way, `data` the custom parts. This is the same…
- [Run network](https://sidenet.ai/docs/api-reference/chat/run-network.md): Runs the network against `messages`. When the network has more than one agent, routing picks which one answers (send `use_routing: false` to take the default agent instead); the `data-handoff` entry in `data` says which one it was. Returns the finished turn as JSON: `text` is the answer, `toolCalls`…
- [Resume stream](https://sidenet.ai/docs/api-reference/chat/resume-stream.md): Replays the buffered UIMessage chunks of the thread's in-flight chat turn from the start, then continues streaming live. Returns 204 when there is nothing to resume.
- [Cancel stream](https://sidenet.ai/docs/api-reference/chat/cancel-stream.md): Aborts the thread's in-flight chat run (explicit stop). Returns cancelled: false when no run is active.
- [List threads](https://sidenet.ai/docs/api-reference/chat/list-threads.md): Returns a paginated list of conversation threads for the authenticated user. Requires authentication.
- [List messages](https://sidenet.ai/docs/api-reference/chat/list-messages.md): Retrieve messages from a conversation thread
- [Vote on message](https://sidenet.ai/docs/api-reference/chat/vote-on-message.md): Rate a message with thumbs up (+1), thumbs down (-1), or neutral (0). Requires authentication.
- [Mark thread read](https://sidenet.ai/docs/api-reference/chat/mark-thread-read.md): Marks a thread as read for its owner (clears the unread badge), or unread again with `{ "unread": true }`. Call it with the owning user's session token. 403 otherwise.
- [List agents](https://sidenet.ai/docs/api-reference/agents/list-agents.md): Lists non-deleted agents for the org, newest first.
- [Create agent](https://sidenet.ai/docs/api-reference/agents/create-agent.md): Creates an agent. Its v0 draft is created automatically (do not create it yourself). Returns the agent + the draft.
- [Get agent](https://sidenet.ai/docs/api-reference/agents/get-agent.md): Returns the agent and exactly ONE of its versions. Which one is up to `version`; by default it is the active (published) version, falling back to the draft when nothing has been activated yet. The `agent` object always reports `activeVersionNumber`, `latestPublishedVersionNumber` and `draftDirty`, s…
- [Save agent draft](https://sidenet.ai/docs/api-reference/agents/save-agent-draft.md): Partial save of the draft agent config (instructions, model fields, agentTools, workflows, memory, scorers, subagents, etc). Only the fields you send are written. Subagents are `[{ agentId }]`. The model fields are `model_slug`, `policy_slug`, `model_options` and `model_settings`; the older `request…
- [Preview agent prompt](https://sidenet.ai/docs/api-reference/agents/preview-agent-prompt.md): Resolves the agent's prompt blocks and renders them with the supplied `variables`, returning the final prompt plus a per-block breakdown: whether each block was included (and why not), what it rendered to, and which of its `{{variables}}` had no value. `version` selects which instructions to render…
- [Publish agent](https://sidenet.ai/docs/api-reference/agents/publish-agent.md): Blocks if the draft config is pristine (== latest published, 422), then creates a new numbered version copying the draft config. Returns the new version.
- [Activate agent version](https://sidenet.ai/docs/api-reference/agents/activate-agent-version.md): Makes the given published version the active one (same agent). Activating a draft or a version of another agent is rejected.
- [List agent versions](https://sidenet.ai/docs/api-reference/agents/list-agent-versions.md): Lists the agent's published versions, newest first.
- [Delete agent](https://sidenet.ai/docs/api-reference/agents/delete-agent.md): Soft-deletes the agent. Blocked with 409 if another agent lists this agent as a subagent, or a network references it (pass `?force=true` to override).
- [List prompt blocks](https://sidenet.ai/docs/api-reference/prompt-blocks/list-prompt-blocks.md): Lists non-deleted prompt blocks for the org, newest first.
- [Create prompt block](https://sidenet.ai/docs/api-reference/prompt-blocks/create-prompt-block.md): Creates a reusable prompt block. Its v0 draft is created automatically (do not create it yourself). Returns the block + the empty draft.
- [Get prompt block](https://sidenet.ai/docs/api-reference/prompt-blocks/get-prompt-block.md): Returns the block and exactly ONE of its versions. Which one is up to `version`; by default it is the active (published) version that agents pin to, falling back to the draft when nothing has been activated yet. The `block` object always reports `activeVersionNumber`, `latestPublishedVersionNumber`…
- [Save block draft](https://sidenet.ai/docs/api-reference/prompt-blocks/save-block-draft.md): Partial save of the block draft (`content`, `rules`) plus the block-level `name` / `description`. Editing a draft does not affect any published agent version — those are pinned until they are republished.
- [Publish prompt block](https://sidenet.ai/docs/api-reference/prompt-blocks/publish-prompt-block.md): Blocks if the draft is pristine (== latest published, 422), then creates a new numbered version. Publishing does NOT change what any agent renders: agents pin a block version when they publish. Activate the new version and then use /rollout to move agents onto it.
- [Activate block version](https://sidenet.ai/docs/api-reference/prompt-blocks/activate-block-version.md): Makes the given published version the block's active one. This is what agent DRAFTS and previews resolve to; published agent versions keep their pin until they are republished (see /rollout).
- [List block versions](https://sidenet.ai/docs/api-reference/prompt-blocks/list-block-versions.md): Lists the block's published versions, newest first.
- [List block references](https://sidenet.ai/docs/api-reference/prompt-blocks/list-block-references.md): Returns each agent in the org whose draft or active version references this block, where the reference appears (`draft` / `active` / `archived`), which block version the agent's ACTIVE version is pinned to, and whether that is behind the block's current active version.
- [Roll out block version](https://sidenet.ai/docs/api-reference/prompt-blocks/roll-out-block-version.md): For every agent whose ACTIVE version pins an older version of this block, publishes a new agent version (re-pinning the block) and activates it. An agent is SKIPPED, with a reason, when its draft differs from its active version — publishing ships the whole draft, and a prompt rollout must never quie…
- [Preview block content](https://sidenet.ai/docs/api-reference/prompt-blocks/preview-block-content.md): Renders `content` with the supplied `variables` and evaluates `rules` against them, so the editor can show the result while typing. Returns the rendered text, the variable names found in the template, which of them had no value, whether the display condition includes the block, and any variables dro…
- [Delete prompt block](https://sidenet.ai/docs/api-reference/prompt-blocks/delete-prompt-block.md): Soft-deletes the block. Blocked with 409 (carrying `referencedBy`) when an agent draft or active version still references it; pass `?force=true` to override. Version rows are never deleted — agent versions published against this block stay pinned to them and keep rendering.
- [List workflows](https://sidenet.ai/docs/api-reference/workflows/list-workflows.md): Lists non-deleted workflows for the org, newest first. By default only org (Studio-authored) workflows; `?owner=chatter` lists the ones end users built through a builder agent (optionally narrowed to one user with `&userId=`), `?owner=all` both.
- [Create workflow](https://sidenet.ai/docs/api-reference/workflows/create-workflow.md): Creates a workflow. Its v0 draft is created automatically (do not create it yourself). Returns the workflow + the empty draft.
- [Get workflow](https://sidenet.ai/docs/api-reference/workflows/get-workflow.md): Returns the workflow and exactly ONE of its versions. Which one is up to `version`; by default it is the active (published) version that runs, falling back to the draft when nothing has been activated yet. The `workflow` object always reports `activeVersionNumber`, `latestPublishedVersionNumber` and…
- [Save workflow draft](https://sidenet.ai/docs/api-reference/workflows/save-workflow-draft.md): Partial save of the draft definition/schemas. Runs structural validation only — work-in-progress graphs are allowed. `output_schema` is optional and NOT enforced at run time — leave it unset unless you need a declared boundary contract; the actual output shape is whatever the last flow position retu…
- [Publish workflow](https://sidenet.ai/docs/api-reference/workflows/publish-workflow.md): Strict gate: blocks if the draft is pristine (== latest published, 422), runs full semantic validation + a trial build, then creates a new numbered version copying the draft. Returns the new version with computed `changed_fields`.
- [Activate workflow version](https://sidenet.ai/docs/api-reference/workflows/activate-workflow-version.md): Makes the given published version the active one (same workflow). Activating a draft or a version of another workflow is rejected with a 4xx.
- [List workflow versions](https://sidenet.ai/docs/api-reference/workflows/list-workflow-versions.md): Lists the workflow's published versions, newest first.
- [Run workflow](https://sidenet.ai/docs/api-reference/workflows/run-workflow.md): Runs a workflow version. `?version=active` (default), `draft`, or `v{n}`. Body: `{ input, groupId?, groupName?, runtimeAuth? }` — `input` is the workflow input, `groupId`/`groupName` select the group the run is attributed to (like /v1/chat), and `runtimeAuth` supplies per-request credentials for too…
- [Get workflow schema](https://sidenet.ai/docs/api-reference/workflows/get-workflow-schema.md): Returns the JSON Schema for the workflow `definition` (steps + flow graph). Use it for client-side validation and to generate editor property panels. Static — independent of org.
- [Delete workflow](https://sidenet.ai/docs/api-reference/workflows/delete-workflow.md): Soft-deletes the workflow. Blocked with 409 if another workflow in the org references this one via a workflow-step, or an agent lists it in its `workflows` (pass `?force=true` to override). The 409 body carries `referencedBy` (workflow ids) and `referencedByAgents`.
- [List workflow schedules](https://sidenet.ai/docs/api-reference/workflows/list-workflow-schedules.md): Lists the org's workflow schedules (newest first). Filter with `workflowId`, `status`, `owner` (org | chatter) and `userId` (the user a schedule runs as). A session token only sees its own user's schedules.
- [Create workflow schedule](https://sidenet.ai/docs/api-reference/workflows/create-workflow-schedule.md): Schedules a workflow (its active version) to run unattended as `user_id`. Timing is a structured `recurrence` (`once | hourly | daily | weekdays | weekly` + date/time/minute/weekday) or a raw `cron`, in `timezone`. `notify: "thread"` (default) files each run's result as a new conversation for that u…
- [Preview schedule timing](https://sidenet.ai/docs/api-reference/workflows/preview-schedule-timing.md): The next run times of a recurrence (or cron) in a timezone, without creating anything. Query: frequency, date, time, minute, weekday, cron, timezone, starts_at, ends_at, count.
- [Get workflow schedule](https://sidenet.ai/docs/api-reference/workflows/get-workflow-schedule.md): One schedule. A session token only sees its own user's schedules (404 otherwise).
- [Update workflow schedule](https://sidenet.ai/docs/api-reference/workflows/update-workflow-schedule.md): Patch timing (recurrence | cron, timezone, starts_at, ends_at — next run recomputed from now), input, notify / thread_title, name, copilot_id, group, metadata.
- [Delete workflow schedule](https://sidenet.ai/docs/api-reference/workflows/delete-workflow-schedule.md): Soft-deletes the schedule; it never fires again. Runs already logged stay.
- [Pause workflow schedule](https://sidenet.ai/docs/api-reference/workflows/pause-workflow-schedule.md): Stops firing until resumed.
- [Resume workflow schedule](https://sidenet.ai/docs/api-reference/workflows/resume-workflow-schedule.md): Resumes firing; the next run is computed from now (nothing fires retroactively). Also re-enables a schedule disabled after repeated failures.
- [Run workflow schedule now](https://sidenet.ai/docs/api-reference/workflows/run-workflow-schedule-now.md): Fires the schedule immediately (out of band — the next regular run is unchanged): runs the workflow as its user with the schedule's input and credentials, files the result thread when notify=thread. Returns the run row.
- [List schedule runs](https://sidenet.ai/docs/api-reference/workflows/list-schedule-runs.md): The run history of one schedule, newest first.
- [List workflow runs](https://sidenet.ai/docs/api-reference/workflows/list-workflow-runs.md): The org's workflow run log (every trigger: schedule, run_now, manual, test), newest first. Filter with workflowId, scheduleId, trigger, status, userId. A session token only sees runs executed as its own user.
- [Get workflow run](https://sidenet.ai/docs/api-reference/workflows/get-workflow-run.md): One run of the log, incl. its (trimmed) output and result text.
- [Get network](https://sidenet.ai/docs/api-reference/networks/get-network.md): Returns the network's attached agents and workflows enriched with their name + description, plus sdk_ui and the org’s runtime auth providers. Each runtimeAuthProviders entry carries providerId, providerName, authType, authFields (the credential keys to send in the chat runtimeAuth map) and optionalF…
- [Update network](https://sidenet.ai/docs/api-reference/networks/update-network.md): Replaces whichever of `agents` ([{agentId}]), `workflows` ([{workflowId}]), or `sdk_ui` is provided. Validates that every referenced agent/workflow belongs to the caller's org. Dev networks only: a staging or prod network returns 409 — edit its dev network and promote it with POST /v1/copilots/{id}/…
- [Attach agent](https://sidenet.ai/docs/api-reference/networks/attach-agent.md): Attaches the agent to the network (idempotent). Dev networks only: a staging or prod network returns 409 — attach on its dev network and promote with POST /v1/copilots/{id}/deploy.
- [Detach agent](https://sidenet.ai/docs/api-reference/networks/detach-agent.md): Dev networks only: a staging or prod network returns 409 — detach on its dev network and promote with POST /v1/copilots/{id}/deploy.
- [Attach workflow](https://sidenet.ai/docs/api-reference/networks/attach-workflow.md): Attaches the workflow to the network (idempotent). Dev networks only: a staging or prod network returns 409 — attach on its dev network and promote with POST /v1/copilots/{id}/deploy.
- [Detach workflow](https://sidenet.ai/docs/api-reference/networks/detach-workflow.md): Dev networks only: a staging or prod network returns 409 — detach on its dev network and promote with POST /v1/copilots/{id}/deploy.
- [Deploy network](https://sidenet.ai/docs/api-reference/networks/deploy-network.md): Copies `agents`, `workflows`, and `sdk_ui` from the source network (`:id`) to the target network (`target_copilot_id`). Both must belong to the caller's org. Use this to promote dev → staging → prod.
- [List tools](https://sidenet.ai/docs/api-reference/tools/list-tools.md): Returns all available tools (static, MCP, and custom) grouped by provider. Each tool carries a `toolRef` — the stable reference object to store in a workflow tool step. Copy it verbatim; do not derive it from the grouping (global MCP tools group under `mcp` but use `{ source: "static", key }`).
- [Execute tool](https://sidenet.ai/docs/api-reference/tools/execute-tool.md): Execute a specific tool with provided input parameters. Supports org-scoped custom tools.
- [Create tool](https://sidenet.ai/docs/api-reference/tools/create-tool.md): Adds a tool to an existing API provider (must belong to the org and be type=api). MCP tools are auto-discovered and cannot be created here. Names are unique per provider: path punctuation (`/`, `{}`) is stripped, and a name already used in the provider is disambiguated with the method and, if needed…
- [Update tool](https://sidenet.ai/docs/api-reference/tools/update-tool.md): Updates a single tool (org-scoped via its provider). A `name` is normalised like on create — path punctuation (`/`, `{}`) stripped, and a name already used by ANOTHER tool in the provider disambiguated with the method and, if needed, a counter — so the saved name in the response may differ from the…
- [Delete tool](https://sidenet.ai/docs/api-reference/tools/delete-tool.md): Deletes a single tool (org-scoped via its provider). Reloads the org tools and rebuilds dependent agents.
- [List tool providers](https://sidenet.ai/docs/api-reference/tool-providers/list-tool-providers.md): Summary of each tool provider for the org (api/mcp/sidenet, static, global MCP): provider fields plus tool_count, auth_type, and the unique agent ids whose ACTIVE version uses the provider. Use GET /v1/tool-providers/:id for full tool details.
- [Create tool provider](https://sidenet.ai/docs/api-reference/tool-providers/create-tool-provider.md): Creates an api/mcp/sidenet provider for the org. For API providers an optional `tools` array creates tools in the same call; tool names must be unique per provider, so path punctuation (`/`, `{}`) is stripped and repeated names (the same OpenAPI summary on two operations) are disambiguated with the…
- [Get tool provider](https://sidenet.ai/docs/api-reference/tool-providers/get-tool-provider.md): Full provider info plus every tool (same per-tool shape as GET /v1/tools). `:id` is the provider's UUID, or the key/name for static and global MCP providers.
- [Update tool provider](https://sidenet.ai/docs/api-reference/tool-providers/update-tool-provider.md): Updates provider fields. Send `auth_secret` to rotate stored credentials. Reloads the org tools and rebuilds dependent agents.
- [Save provider tools](https://sidenet.ai/docs/api-reference/tool-providers/save-provider-tools.md): Creates and updates a provider's tools in a single call. An entry with an `id` updates that tool, an entry without one creates it (nothing is deleted — use DELETE /v1/tools/:id). Names are made unique across the whole provider, so the saved name may differ from the one sent; the response lists every…
- [Delete tool provider](https://sidenet.ai/docs/api-reference/tool-providers/delete-tool-provider.md): Deletes the provider and all of its tools; stored credentials are removed. Reloads the org tools and rebuilds dependent agents.
- [Score traces](https://sidenet.ai/docs/api-reference/experiments/score-traces.md): Scores historical traces/spans with a scorer from the catalog, fire-and-forget. Send `scorerType` (e.g. "tone", "bias"). Poll GET /api/scores/scorer/<scorerId> for results.
- [Run experiment](https://sidenet.ai/docs/api-reference/experiments/run-experiment.md): Runs a dataset experiment against an agent. Send `agentId` (agent id or agent version id), `datasetId`, and optional `scorers` (scorer types from the catalog, e.g. "tone", "bias" — code scorers and LLM judges both supported). Set `async: true` for fire-and-forget (returns an experimentId to poll GET…
- [Rebuild agents](https://sidenet.ai/docs/api-reference/system/rebuild-agents.md): Refresh agents with their latest configuration. Provide either agentId or copilotId (copilotId rebuilds all agents in the active deployment).
- [Rebuild org tools](https://sidenet.ai/docs/api-reference/system/rebuild-org-tools.md): Reloads the organization's custom tools and rebuilds every agent that uses them.
- [Overview](https://sidenet.ai/docs/sdk/overview.md): Embeddable AI chat sidebar for any web application.
- [Installation](https://sidenet.ai/docs/sdk/installation.md): Install the Sidenet AI SDK via npm or CDN.
- [Authentication](https://sidenet.ai/docs/sdk/authentication.md): Mint a session token on your backend, then hand it to the SDK.
- [Get Started](https://sidenet.ai/docs/sdk/quickstart.md): Initialize and use the SDK in minutes.
- [General](https://sidenet.ai/docs/sdk/api/lifecycle.md): Initialize, destroy, and control sidebar visibility.
- [Config Updates](https://sidenet.ai/docs/sdk/api/configuration-updates.md): Update SDK behaviour and styled config at runtime.
- [Tool Credentials](https://sidenet.ai/docs/sdk/api/tool-credentials.md): Give the agent's tools per-user credentials, bound server-side to the session.
- [Prompt Variables](https://sidenet.ai/docs/sdk/api/prompt-variables.md): Fill the placeholders an agent's prompt blocks declare, and discover which ones exist.
- [Defaults & Constants](https://sidenet.ai/docs/sdk/api/defaults-events.md): Exported constants and event handling.
- [Design and Theme](https://sidenet.ai/docs/sdk/theming.md): Light/dark mode and design tokens.
- [Text Copy](https://sidenet.ai/docs/sdk/greeting-suggestions.md): Customize the empty-state greeting, placeholder, and suggestion cards.
- [React - Advanced](https://sidenet.ai/docs/sdk/react-hook.md): Access runtime config in React apps.
- [Typescript](https://sidenet.ai/docs/sdk/typescript.md): All exported types.

## OpenAPI Specs

- [openapi](/docs/api-reference/openapi.json)