Convoship Docs
Back to Studio

API reference

Studio API surface — auth, assistants, agents, workflows, imports, and public runtime.

The Studio API is FastAPI at /v1 on api.convoship.org (or your self-hosted URL). Browser apps call it via Next.js /api proxies with session cookies. Automation uses the same routes with Bearer tokens where supported.

Authentication

  • POST /v1/auth/signup, login, refresh, logout — JWT access + httpOnly refresh cookies.
  • MFA — TOTP enroll/verify on user account.
  • Workspace context — X-Workspace-Id or membership from session.
  • Public embed — Authorization: Bearer cdp_* on /v1/public/runtime/*.

Assistants (scripted)

GET/POST           /v1/agents
GET/PATCH/DELETE    /v1/agents/{agent_id}
GET/POST            /v1/agents/{agent_id}/intents
GET/POST            /v1/agents/{agent_id}/flow/...
POST                /v1/agents/{agent_id}/flow/repair-node
POST                /v1/imports/drawio, /v1/imports/source, ...
GET                 /v1/agents/{agent_id}/analytics
POST                /v1/agents/{agent_id}/deployments

AI Agents (agentic)

GET/POST            /v1/ai-agents
GET/PATCH/DELETE     /v1/ai-agents/{slug}
POST                 /v1/ai-agents/{slug}/derive-tasks
POST                 /v1/ai-agents/{slug}/playground[?stream=true]
POST                 /v1/ai-agents/{slug}/publish
POST                 /v1/ai-agents/{slug}/rotate-public-token
GET                  /v1/ai-agents/{slug}/embed
GET                  /v1/ai-agents/{slug}/versions
GET                  /v1/ai-agents/{slug}/versions/{vid}/eval-runs
POST                 /v1/ai-agents/{slug}/rollback/{vid}
GET                  /v1/ai-agents/{slug}/audit-events
GET/POST/PATCH/DELETE /v1/ai-agents/{slug}/tasks|tools|memory
POST                 /v1/ai-agents/{slug}/tools/{tid}/test
GET/POST/PATCH/DELETE /v1/ai-agents/{slug}/knowledge|guardrails|evals
POST                 /v1/ai-agents/{slug}/evals/{eid}/run
GET                  /v1/ai-agents/{slug}/conversations[/{convo_slug}]
GET                  /v1/ai-agents/{slug}/analytics?days=N
GET/POST/PATCH/DELETE /v1/ai-agent-drafts[/{id}]
GET/PATCH            /v1/workspaces/agent-ops
GET/PATCH            /v1/workspaces/agent-llm
POST                 /v1/public/ai-agents/{public_token}/turn[?stream=true]

Workflows & chains

Capabilities: workflow.read (viewer), workflow.write (editor), workflow.publish (developer), runtime.simulate (editor). See Workflows overview for ingress signing and publish rules.

# Chains
GET/POST/PATCH/DELETE  /v1/workflow-chains[/{slug}]
POST                   /v1/workflow-chains/{slug}/run
POST                   /v1/workflow-chains/{slug}/ingress
GET                    /v1/workflow-chains/{slug}/runs[/{run_id}]
POST                   /v1/workflow-chains/{slug}/runs/{run_id}/resume
POST                   /v1/public/workflow-chains/{workspace_slug}/{chain_slug}/ingress

# Graph workflows
GET/POST/PATCH/DELETE  /v1/workflows[/{id}]
PUT                    /v1/workflows/{id}/graph
POST                   /v1/workflows/{id}/validate-publish
POST                   /v1/workflows/{id}/publish
GET                    /v1/workflows/{id}/versions
POST                   /v1/workflows/{id}/versions/{version_id}/restore

# Simulator / history
POST                   /v1/runtime/workflows/{id}/sessions
POST                   /v1/runtime/workflows/sessions/{id}/turns
GET                    /v1/runtime/workflows/{id}/sessions?limit=&offset=

Workspace

  • GET /v1/workspaces/usage — plan and usage analytics (no hard caps).
  • GET/POST /v1/workspace-tools — shared HTTP tools.
  • GET/POST /v1/secrets — encrypted credential vault.
  • GET /v1/audit — workspace audit log.
  • POST /v1/leads — public demo and contact-sales forms (rate-limited).
  • GET /v1/workspaces/billing/status — workspace plan (enterprise).

Runtime (authenticated + public)

  • POST /v1/runtime/sessions — start assistant session (cookie auth).
  • POST /v1/runtime/sessions/{id}/turns — process user message.
  • POST /v1/runtime/workflows/{id}/sessions — start workflow simulator (runtime.simulate).
  • POST /v1/runtime/workflows/sessions/{id}/turns — workflow simulator turn.
  • GET /v1/runtime/workflows/{id}/sessions — paginated workflow history (workflow.read).
  • POST /v1/public/runtime/sessions — embed token auth.
  • GET /v1/runtime/llm-config — resolved agent LLM provider for UI badge.

Channels & voice

  • Channel connections — Twilio WhatsApp/SMS/Voice, Zendesk, Genesys, ServiceNow, webhooks.
  • POST /v1/public/channels/voice_gateway/{connection_id} — BYO voice gateway.
  • Voice streaming — Deepgram STT + ElevenLabs TTS on connections.

OpenAPI

Interactive schema: {API_URL}/docs when running studio-api locally. Production may restrict /docs — use repository apps/studio-api OpenAPI export or route modules under app/api/routes/.