# Sidenet API

## Docs

- [Activate a published version](https://docs.sidenet.ai/api-reference/agents/activate-a-published-version.md): Points `active_version_id` at a published version (same agent), then rebuilds + re-registers the active agent. The DB guard rejects pointing at a draft or another agent.
- [Create an agent](https://docs.sidenet.ai/api-reference/agents/create-an-agent.md): Creates an agent. The DB auto-creates its v0 draft (do not create it yourself). Returns the agent + the draft. Requires X-Organization-Id and X-User-Id.
- [Get an agent with active version + draft summary](https://docs.sidenet.ai/api-reference/agents/get-an-agent-with-active-version-+-draft-summary.md): Returns the agent, its active (published) version, and a draft summary including a `dirty` flag (draft config differs from latest published).
- [List published versions (newest first)](https://docs.sidenet.ai/api-reference/agents/list-published-versions-newest-first.md)
- [List the org's agents](https://docs.sidenet.ai/api-reference/agents/list-the-orgs-agents.md): Lists non-deleted agents for the org, newest first.
- [Publish the draft as a new immutable version](https://docs.sidenet.ai/api-reference/agents/publish-the-draft-as-a-new-immutable-version.md): Blocks if the draft config is pristine (== latest published, 422), then INSERTs a new numbered version copying the draft config. Returns the new version.
- [Save the draft config](https://docs.sidenet.ai/api-reference/agents/save-the-draft-config.md): Partial save of the draft agent config columns (prompt, model fields, agentTools, memory, scorers, subagents, etc). Send the `rev` you last read; a stale rev returns 409. `rev` is trigger-owned and must not be sent in the payload. Subagents are `[{ agentId }]`.
- [Soft-delete an agent](https://docs.sidenet.ai/api-reference/agents/soft-delete-an-agent.md): Sets `deleted_at`. Blocked with 409 if another non-deleted agent lists this agent as a subagent, or a copilot references it (pass `?force=true` to override).
- [Composio OAuth callback](https://docs.sidenet.ai/api-reference/composio/composio-oauth-callback.md): Handles OAuth redirects after users connect their accounts via Composio in-app authentication
- [Attach a workflow to a copilot](https://docs.sidenet.ai/api-reference/copilots/attach-a-workflow-to-a-copilot.md): Adds { workflowId } to copilots.workflows (idempotent) and busts the resolution cache.
- [Attach an agent to a copilot](https://docs.sidenet.ai/api-reference/copilots/attach-an-agent-to-a-copilot.md): Adds { agentId } to copilots.agents (idempotent) and busts the resolution cache.
- [Deploy a copilot config to another copilot](https://docs.sidenet.ai/api-reference/copilots/deploy-a-copilot-config-to-another-copilot.md): Copies `agents`, `workflows`, and `sdk_ui` from the source copilot (`:id`) to the target copilot (`target_copilot_id`). Both must belong to the caller's org. Use this to promote dev → staging → prod.
- [Detach a workflow from a copilot](https://docs.sidenet.ai/api-reference/copilots/detach-a-workflow-from-a-copilot.md)
- [Detach an agent from a copilot](https://docs.sidenet.ai/api-reference/copilots/detach-an-agent-from-a-copilot.md)
- [Get a copilot (agents, workflows, sdk_ui, runtime auth providers)](https://docs.sidenet.ai/api-reference/copilots/get-a-copilot-agents-workflows-sdk_ui-runtime-auth-providers.md): Returns the copilot'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 a copilot (agents, workflows, sdk_ui)](https://docs.sidenet.ai/api-reference/copilots/update-a-copilot-agents-workflows-sdk_ui.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. Busts the copilot resolution cache.
- [Rebuild an org's custom tools, MCP providers, and dependent agents](https://docs.sidenet.ai/api-reference/custom/rebuild-an-orgs-custom-tools-mcp-providers-and-dependent-agents.md): Invalidates the org's tool caches, reloads custom tools (from `tools` table) and DB-backed MCP tools (from `tool_providers` where type='mcp'), then rebuilds every agent in the org whose agentTools reference at least one of those tools (active version per agent).
- [Run an offline experiment against an on-demand agent](https://docs.sidenet.ai/api-reference/custom/run-an-offline-experiment-against-an-on-demand-agent.md): Runs a Mastra dataset experiment against an agent built on demand from public.agent_versions. Send `agentId` (agents.id or agent_versions.id), `datasetId`, and optional `scorers` (catalog scorer_type_id values, e.g. "tone", "bias" — code scorers and per-org LLM judges both supported). Set `async: tr…
- [Score one or more traces with a scorer (on-demand)](https://docs.sidenet.ai/api-reference/custom/score-one-or-more-traces-with-a-scorer-on-demand.md): Scores historical traces/spans with a scorer from the catalog (`public.scorer_options`), fire-and-forget. Send `scorerType` = the catalog `scorer_type_id` (e.g. "tone", "bias"). LLM scorers require `X-Organization-Id`. Poll GET /api/scores/scorer/<scorerId> for results.
- [Create a tool provider (optionally with its API tools)](https://docs.sidenet.ai/api-reference/v1/create-a-tool-provider-optionally-with-its-api-tools.md): Creates an api/mcp/sidenet provider for the org. For API providers an optional `tools` array creates tools in the same call. Sensitive credentials go in `auth_secret` (stored in Vault). Reloads the org tools and rebuilds dependent agents.
- [Create an API tool under a provider](https://docs.sidenet.ai/api-reference/v1/create-an-api-tool-under-a-provider.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. Reloads the org tools and rebuilds dependent agents.
- [Delete a tool provider](https://docs.sidenet.ai/api-reference/v1/delete-a-tool-provider.md): Deletes the provider and (cascade) its tools; the Vault secret is cleaned by a DB trigger. Reloads the org tools and rebuilds dependent agents.
- [Delete an API tool](https://docs.sidenet.ai/api-reference/v1/delete-an-api-tool.md): Deletes a single tool (org-scoped via its provider). Reloads the org tools and rebuilds dependent agents.
- [Execute a tool directly](https://docs.sidenet.ai/api-reference/v1/execute-a-tool-directly.md): Execute a specific tool with provided input parameters. Supports org-scoped custom tools.
- [Get a tool provider with all its tools](https://docs.sidenet.ai/api-reference/v1/get-a-tool-provider-with-all-its-tools.md): Full provider info plus every tool (same per-tool shape as GET /v1/tools). `:id` is the UUID for DB providers, or the key/name for static and global-MCP providers. (Composio is handled by the frontend.)
- [Get all available tools](https://docs.sidenet.ai/api-reference/v1/get-all-available-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 }`).
- [Get copilot configuration (DEPRECATED → GET /v1/copilots/:id)](https://docs.sidenet.ai/api-reference/v1/get-copilot-configuration-deprecated-→-get-v1copilots:id.md): DEPRECATED: use GET /v1/copilots/:id instead, which returns the copilot's agents + workflows (with name + description), sdk_ui, and runtime auth providers. Kept for backward compatibility during migration.
- [Get messages for a thread (UIMessage format)](https://docs.sidenet.ai/api-reference/v1/get-messages-for-a-thread-uimessage-format.md): Retrieve messages from a conversation thread in AI SDK v6 UIMessage format, ready for assistant-ui rendering. Requires authentication.
- [List conversation threads](https://docs.sidenet.ai/api-reference/v1/list-conversation-threads.md): Returns a paginated list of conversation threads filtered by the authenticated user's resourceId (orgId_userId). Requires authentication.
- [List tool providers (summary)](https://docs.sidenet.ai/api-reference/v1/list-tool-providers-summary.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. Composio is handled by the frontend. Use GET /v1/tool-providers/:id for full tool details.
- [Rebuild agent cache from database](https://docs.sidenet.ai/api-reference/v1/rebuild-agent-cache-from-database.md): Refresh cached agents with latest configuration from database. Provide either agentId or copilotId (copilotId rebuilds all agents in active deployment).
- [Stream agent response (AI SDK format)](https://docs.sidenet.ai/api-reference/v1/stream-agent-response-ai-sdk-format.md): Build and stream responses from an agent in AI SDK v6 UIMessageStream format. Compatible with assistant-ui and AI SDK useChat. Provide either agentId or copilotId. Requests with the shared TRUSTED_KEY bypass DB API-key lookup; otherwise an API key in the Authorization header is validated.
- [Update a tool provider](https://docs.sidenet.ai/api-reference/v1/update-a-tool-provider.md): Updates provider fields. Send `auth_secret` to rotate Vault credentials. Reloads the org tools and rebuilds dependent agents.
- [Update an API tool](https://docs.sidenet.ai/api-reference/v1/update-an-api-tool.md): Updates a single tool (org-scoped via its provider). Reloads the org tools and rebuilds dependent agents.
- [Vote on a message](https://docs.sidenet.ai/api-reference/v1/vote-on-a-message.md): Rate a message with thumbs up (+1), thumbs down (-1), or neutral (0). Requires authentication.
- [Activate a published version](https://docs.sidenet.ai/api-reference/workflows/activate-a-published-version.md): Points `active_version_id` at a published version (same workflow). Rebuilds + re-registers the active workflow under its stable id. The DB guard rejects pointing at a draft or another workflow — surfaced as 4xx.
- [Create a workflow](https://docs.sidenet.ai/api-reference/workflows/create-a-workflow.md): Creates a workflow. The DB auto-creates its v0 draft (do not create it yourself). Returns the workflow + the empty draft. Requires X-Organization-Id and X-User-Id.
- [Get a workflow with active version + draft summary](https://docs.sidenet.ai/api-reference/workflows/get-a-workflow-with-active-version-+-draft-summary.md): Returns the workflow, its active (published) version, and a draft summary including a `dirty` flag (draft differs from latest published).
- [JSON Schema for the workflow definition](https://docs.sidenet.ai/api-reference/workflows/json-schema-for-the-workflow-definition.md): Returns the JSON Schema for the `definition` jsonb (steps + flow graph), derived from the backend Zod schema. Use it for client-side validation and to generate editor property panels. Static — independent of org.
- [List published versions (newest first)](https://docs.sidenet.ai/api-reference/workflows/list-published-versions-newest-first.md)
- [List the org's workflows](https://docs.sidenet.ai/api-reference/workflows/list-the-orgs-workflows.md): Lists non-deleted workflows for the org, newest first.
- [Publish the draft as a new immutable version](https://docs.sidenet.ai/api-reference/workflows/publish-the-draft-as-a-new-immutable-version.md): Strict gate: blocks if the draft is pristine (== latest published, 422), runs full semantic validation + a trial build, then INSERTs a new numbered version copying the draft. Returns the new version with computed `changed_fields`.
- [Run a workflow](https://docs.sidenet.ai/api-reference/workflows/run-a-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 chatter group whose Requesty key bills the agent steps (like /v1/chat), and `runtimeAuth` supplies per-req…
- [Save the draft (lenient, structural-only)](https://docs.sidenet.ai/api-reference/workflows/save-the-draft-lenient-structural-only.md): Partial save of the draft definition/schemas. Runs STRUCTURAL (Zod) validation only — WIP graphs are allowed. Send the `rev` you last read; a stale rev returns 409. `rev` is trigger-owned and must not be sent in the payload. `output_schema` is optional and NOT enforced at run time — leave it unset u…
- [Soft-delete a workflow](https://docs.sidenet.ai/api-reference/workflows/soft-delete-a-workflow.md): Sets `deleted_at`. Blocked with 409 if another non-deleted workflow in the org references this one via a workflow-step (pass `?force=true` to override).
- [Authentication](https://docs.sidenet.ai/authentication.md): How to authenticate requests and scope them to an organization.
- [What is SideNet?](https://docs.sidenet.ai/introduction.md): Overview of Side
- [Config Updates](https://docs.sidenet.ai/sdk/api/configuration-updates.md): Update SDK behaviour and styled config at runtime.
- [Defaults & Constants](https://docs.sidenet.ai/sdk/api/defaults-events.md): Exported constants and event handling.
- [General](https://docs.sidenet.ai/sdk/api/lifecycle.md): Initialize, destroy, and control sidebar visibility.
- [Runtime Authentication](https://docs.sidenet.ai/sdk/api/runtime-auth.md): Pass user credentials to use for the tools assigned to the agents
- [Text Copy](https://docs.sidenet.ai/sdk/greeting-suggestions.md): Customize the empty-state greeting, placeholder, and suggestion cards.
- [Installation](https://docs.sidenet.ai/sdk/installation.md): Install the Sidenet AI SDK via npm or CDN.
- [Overview](https://docs.sidenet.ai/sdk/overview.md): Embeddable AI chat sidebar for any web application.
- [Get Started](https://docs.sidenet.ai/sdk/quickstart.md): Initialize and use the SDK in minutes.
- [React - Advanced](https://docs.sidenet.ai/sdk/react-hook.md): Access runtime config in React apps.
- [Design and Theme](https://docs.sidenet.ai/sdk/theming.md): Light/dark mode and design tokens.
- [Typescript](https://docs.sidenet.ai/sdk/typescript.md): All exported types.

## OpenAPI Specs

- [openapi](https://docs.sidenet.ai/api-reference/openapi.json)