Skip to main content
Welcome to the Devic Public API. This API allows you to integrate Devic’s AI capabilities directly into your own applications and services: create and run agents, orchestrate assistants, measure costs, and evaluate performance using LLM-powered evaluations. The Devic API is ideal for backend automation, SaaS integrations and systems that need to operate AI workflows programmatically.

​
What you can do with the API

Manage agents programmatically

Create, update, delete agents and run executions, pause or resume them, complete runs, and trigger evaluations.

Power conversational assistants

Send messages to assistants, retrieve chat histories and integrate them directly inside your product.

Configure tool servers

Create and manage tool servers with their tools, authentication, and test tool calls programmatically.

Organise work in projects

Group agents, assistants, documents and costs into projects and track their usage and spend.

Build a knowledge base (RAG)

Create and version documents, organise them in folders, and attach them to agents or assistants so they are indexed for retrieval.

Upload files

Upload files and attach them to assistant or agent messages with shareable download URLs.

Monitor quality with evaluations

Score outputs, audit behaviour and receive structured feedback using Devic’s evaluation engine.

FinOps and cost visibility

Retrieve daily, monthly and aggregated cost data for each agent.

Connect third-party apps

Browse the catalogue, connect an account, build a tool server from it and choose which of its tools your agents get.

React to app events

Subscribe an agent or assistant to an event from a connected app, and read what each delivery did.

Serve your own customers

Tenants and subtenants, their consumption against plan limits, and the apps each end user connects for themselves.

Prove who is calling

Mint short-lived tenant sessions from your backend, so an embedded widget carries no API key.

Read and edit memory

The standing core-memory block an assistant is given for a tenant, readable and editable.

Transcribe audio

Speech-to-text, so a voice message becomes a message like any other.

Health checks

Verify API availability using a dedicated health endpoint.

​
API surface at a glance

The Devic API is divided into the following groups:

​
Agents

  • Create, list, update and delete agents
  • Create and list agent threads
  • Pause, resume or complete executions
  • Trigger evaluations
  • Retrieve evaluation results
  • Retrieve daily, monthly and summary costs

​
Assistants

  • List available assistants
  • Send messages
  • Retrieve chat histories
  • Filter conversations across assistants

​
Tool Servers

  • Create, list, update and delete tool servers
  • Manage tool definitions within servers
  • Configure authentication (JWT, OAuth2, Basic, Custom Headers)
  • Test tool calls programmatically
  • Clone tool servers

​
Projects

  • Create, list, update and archive projects
  • Inspect project stats, threads and conversations
  • Retrieve daily and monthly project costs

​
Knowledge

  • Create, version, update and delete documents
  • Organise documents into folders
  • Attach documents or folders to agents or assistants for RAG indexing
  • Inspect document usage, versions and link graph

​
Memory

  • Read the core-memory block of an assistant for a tenant
  • Add, supersede and delete entries

​
MCP Gateway

  • Manage visibility profiles
  • Grant per-user access and per-user tool visibility

​
Integrations

  • Browse connectable apps and their event types
  • Connect an account and build a tool server from it
  • Choose and test the tools an integration exposes

​
Triggers

  • Subscribe an agent or assistant to an app event
  • Configure the message template and rate limits
  • Read recent deliveries

​
Tenants

  • List tenants and subtenants, and their stats and costs
  • Read consumption against plan limits
  • Change a tenant’s plan and reset its counters

​
Tenant Sessions

  • Issue a short-lived token that proves which end user is calling

​
Tenant Integrations

  • The apps an assistant offers its end users
  • Connect and disconnect an end user’s own accounts

​
Skills

  • List the skills catalogue and its tags
  • Scaffold a folder-skill

​
Speech to Text

  • Transcribe audio and retrieve a transcript

​
Files

  • Upload files and receive shareable download URLs
  • Attach uploaded files to assistant or agent messages

​
Documentation

  • List available docs
  • Retrieve rendered HTML or markdown

​
Health

  • Basic availability checks

View OpenAPI specification

Download the OpenAPI specification used to generate this API reference.

​
Environments and base URLs

Devic offers separate environments for development and production.

​
Production

https://api.devic.ai

​
Staging

https://staging-api.devic.ai Example full endpoint: GET https://api.devic.ai/v1/agents/{agentId}/threads

​
Authentication

Every request carries its credential in the Authorization header, as a Bearer token:
Missing, invalid or expired credentials return 401 Unauthorized. Three kinds of credential go in that header. Your API key, created in the Devic console. This is what a backend uses. Short keys — the ones that start with devic- — are sent the same way, and can be restricted to a list of domains or endpoints, which is what makes them usable from a page. A tenant-session token, for an embedded front end, so no API key reaches the browser. Your backend mints one with POST /api/v1/tenant-sessions and hands it to the widget; it proves which tenant is calling and only reaches the endpoints a session is allowed to. An API key configured as signed can do nothing but mint sessions — every other call has to arrive as one, which is what lets the key sit in a page without a visitor being able to claim a tenant that is not theirs. An OAuth access token, for an integration acting on a customer’s behalf. What it may reach is decided by the scopes it was granted.

​
Typical workflows

​
1. Managing agents

  1. Create an agent POST /v1/agents
  2. List all agents GET /v1/agents
  3. Update or delete an agent PATCH /v1/agents/ DELETE /v1/agents/

Start with agents

Create your first agent programmatically.

​
2. Running an agent

  1. Create a thread POST /v1/agents//threads
  2. Monitor or control the execution GET /v1/agents/threads/ POST /v1/agents/threads//pause POST /v1/agents/threads//resume POST /v1/agents/threads//complete
  3. Trigger or fetch evaluations POST /v1/agents/threads//evaluate GET /v1/agents/threads//evaluations
  4. Inspect costs GET /v1/agents/agents//costs/daily GET /v1/agents/agents//costs/monthly GET /v1/agents/agents//costs/summary

Run agent threads

Create execution threads for your agents.

​
3. Conversational assistants

  1. List assistants GET /v1/assistants
  2. Send messages POST /v1/assistants//messages
  3. Retrieve chat history GET /v1/assistants//chats/ GET /v1/assistants//chats POST /v1/assistants/chats

Start with assistants

Learn how to send your first message to an assistant.

​
4. Uploading files

  1. Upload a file POST /v1/files/upload
  2. Use the download URL in a message POST /v1/assistants//messages (include the downloadUrl in the files array)

Upload files

Upload files and attach them to messages.

​
5. Building a knowledge base (RAG)

  1. Create a document (its content is indexed automatically) POST /v1/documents
  2. Attach it to an agent or assistant so it is used for retrieval POST /v1/documents//attach (body: { "targetType": "agent" | "assistant", "targetId": "..." })
  3. Organise and manage documents GET /v1/documents PATCH /v1/documents/ DELETE /v1/documents/
  4. Group documents in folders and attach them in bulk POST /v1/document-folders POST /v1/document-folders//attach
POST /v1/documents indexes markdown content. To attach a binary file (PDF, DOCX…) to a single message instead of the knowledge base, upload it with POST /v1/files/upload and include the returned downloadUrl in the message files array.

Create your first document

Add indexed knowledge to your agents and assistants.

​
6. Managing tool servers

  1. Create a tool server with tools POST /v1/tool-servers
  2. List and get tool servers GET /v1/tool-servers GET /v1/tool-servers/
  3. Manage tools in a server GET /v1/tool-servers//tools POST /v1/tool-servers//tools PATCH /v1/tool-servers//tools/ DELETE /v1/tool-servers//tools/
  4. Test tool calls POST /v1/tool-servers//tools//test
  5. Clone a tool server POST /v1/tool-servers//clone

Start with tool servers

Create and configure tool servers programmatically.

​
7. Connecting an app and reacting to its events

  1. Find the app and see what it needs GET /v1/integrations?search=gmail GET /v1/integrations/gmail/auth
  2. Connect an account (open authorizationUrl when one is returned) POST /v1/integrations/gmail/connect GET /v1/integrations/gmail/connection-status
  3. Build the tool server and choose its tools POST /v1/integrations/gmail/servers PATCH /v1/integrations/servers//tools
  4. Start an agent from one of its events GET /v1/integrations/gmail/triggers POST /v1/triggers GET /v1/triggers//events

Connect an app

Browse the catalogue of connectable applications.

​
8. Serving your own customers

  1. Issue a session for the end user — from your server, never from the browser POST /api/v1/tenant-sessions
  2. Let the widget use it, then read that user’s own view GET /v1/tenant-usage/ GET /v1/tenant-integrations?assistantId=…
  3. Move them between plans from your checkout POST /v1/tenant-admin//tier

Issue a tenant session

The credential an embedded widget should carry.

​
Error handling

Most endpoints return structured error objects. Common status codes:
  • 400 — Invalid input
  • 401 — Missing or invalid token
  • 404 — Resource not found
  • 429 — Rate limit exceeded
  • 500 — Internal server error

​
Next steps

Explore agents endpoints

Create, manage and run AI agents programmatically.

Explore assistants endpoints

Build conversational AI experiences powered by Devic.

Explore tool servers

Configure and manage tool servers and their tools.