> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Overview, authentication and usage patterns for the Devic public API.

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

<Columns cols={2}>
  <Card title="Manage agents programmatically" icon="robot">
    Create, update, delete agents and run executions, pause or resume them, complete runs, and trigger evaluations.
  </Card>

  <Card title="Power conversational assistants" icon="comments">
    Send messages to assistants, retrieve chat histories and integrate them directly inside your product.
  </Card>

  <Card title="Configure tool servers" icon="wrench">
    Create and manage tool servers with their tools, authentication, and test tool calls programmatically.
  </Card>

  <Card title="Monitor quality with evaluations" icon="scale-balanced">
    Score outputs, audit behaviour and receive structured feedback using Devic's evaluation engine.
  </Card>

  <Card title="FinOps and cost visibility" icon="chart-line">
    Retrieve daily, monthly and aggregated cost data for each agent.
  </Card>

  <Card title="Health checks" icon="heartbeat">
    Verify API availability using a dedicated health endpoint.
  </Card>
</Columns>

***

## 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

### **Documentation**

* List available docs
* Retrieve rendered HTML or markdown

### **Health**

* Basic availability checks

<Card title="View OpenAPI specification" icon="layers" href="/openapi.json">
  Download the OpenAPI specification used to generate this API reference.
</Card>

***

## Environments and base URLs

Devic offers separate environments for development and production.

### Production

[https://api.devic.ai](https://api.devic.ai)

### Staging

[https://staging-api.devic.ai](https://staging-api.devic.ai)

Example full endpoint:

GET [https://api.devic.ai/v1/agents/\{agentId}/threads](https://api.devic.ai/v1/agents/\{agentId}/threads)

***

## Authentication

All Devic API requests require a **Bearer token**.

Include your token in every request using the `Authorization` header:

Header format:

Authorization: Bearer YOUR\_API\_TOKEN

Example request:

GET [https://api.devic.ai/v1/agents/\{agentId}/threads](https://api.devic.ai/v1/agents/\{agentId}/threads)
Authorization: Bearer YOUR\_API\_TOKEN
Content-Type: application/json

Invalid or missing tokens return `401 Unauthorized`.

***

## 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/{agentId}
   DELETE /v1/agents/{agentId}

<Card title="Start with agents" icon="robot" href="/api-reference/endpoint/post-api-v1-agents">
  Create your first agent programmatically.
</Card>

***

### 2. Running an agent

1. **Create a thread**

   POST /v1/agents/{agentId}/threads

2. **Monitor or control the execution**

   GET /v1/agents/threads/{threadId}
   POST /v1/agents/threads/{threadId}/pause
   POST /v1/agents/threads/{threadId}/resume
   POST /v1/agents/threads/{threadId}/complete

3. **Trigger or fetch evaluations**

   POST /v1/agents/threads/{threadId}/evaluate
   GET /v1/agents/threads/{threadId}/evaluations

4. **Inspect costs**

   GET /v1/agents/agents/{agentId}/costs/daily
   GET /v1/agents/agents/{agentId}/costs/monthly
   GET /v1/agents/agents/{agentId}/costs/summary

<Card title="Run agent threads" icon="play" href="/api-reference/endpoint/post-api-v1-agents-agentid-threads">
  Create execution threads for your agents.
</Card>

***

### 3. Conversational assistants

1. **List assistants**

   GET /v1/assistants

2. **Send messages**

   POST /v1/assistants/{identifier}/messages

3. **Retrieve chat history**

   GET /v1/assistants/{identifier}/chats/{chatUid}
   GET /v1/assistants/{identifier}/chats
   POST /v1/assistants/chats

<Card title="Start with assistants" icon="comments" href="/api-reference/endpoint/post-api-v1-assistants-identifier-messages">
  Learn how to send your first message to an assistant.
</Card>

***

### 4. 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/{toolServerId}

3. **Manage tools in a server**

   GET /v1/tool-servers/{toolServerId}/tools
   POST /v1/tool-servers/{toolServerId}/tools
   PATCH /v1/tool-servers/{toolServerId}/tools/{toolName}
   DELETE /v1/tool-servers/{toolServerId}/tools/{toolName}

4. **Test tool calls**

   POST /v1/tool-servers/{toolServerId}/tools/{toolName}/test

5. **Clone a tool server**

   POST /v1/tool-servers/{toolServerId}/clone

<Card title="Start with tool servers" icon="wrench" href="/api-reference/endpoint/post-api-v1-tool-servers">
  Create and configure tool servers programmatically.
</Card>

***

## Error handling

Most endpoints return structured error objects.

<pre>
  {`{
    "error": "ERROR_CODE",
    "message": "Human readable description",
    "details": { }
    }`}
</pre>

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

<Columns cols={3}>
  <Card title="Explore agents endpoints" icon="robot" href="/api-reference/endpoint/get-api-v1-agents">
    Create, manage and run AI agents programmatically.
  </Card>

  <Card title="Explore assistants endpoints" icon="comments" href="/api-reference/endpoint/get-api-v1-assistants">
    Build conversational AI experiences powered by Devic.
  </Card>

  <Card title="Explore tool servers" icon="wrench" href="/api-reference/endpoint/get-api-v1-tool-servers">
    Configure and manage tool servers and their tools.
  </Card>
</Columns>