shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

devic-api

Devic AI Platform API reference for assistants, agents, and tool servers. Use when working with Devic API endpoints, creating integrations, or building applications that interact with the Devic platform.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Devic API

Devic is an AI platform that enables developers to build, deploy, and manage AI-powered assistants and autonomous agents. The platform provides a comprehensive REST API for programmatic access to all platform features.

Base URL

https://api.devic.ai

Authentication

All API requests require authentication using a JWT Bearer token. API keys follow the pattern. Generate your API key from the Devic dashboard on https://app.devic.ai/api-keys:

devic-{random_string}

Example: devic-wengpqengqp1234abcd

Request Header

Include the API key in the Authorization header:

Authorization: Bearer devic-your-api-key-here

Example Request

curl -X GET "https://api.devic.ai/api/v1/assistants" \
  -H "Authorization: Bearer devic-your-api-key-here" \
  -H "Content-Type: application/json"

Response Format

All API responses follow a standardized format:

Success Response

{
  "success": true,
  "data": { ... },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Error Response

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Architecture Overview

Understanding how the core entities relate to each other is essential for building integrations with the Devic platform.

Entity Relationships

┌─────────────────────────────────────────────────────────────────┐
│                         Tool Server                             │
│  (External API integration with tool definitions)               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ referenced by
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Tools Group                               │
│  (Logical grouping of tools - built-in or from tool server)     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ availableToolsGroupsUids
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              Assistant Specialization                           │
│  (Configuration: presets, tools, model, provider, etc.)         │
└─────────────────────────────────────────────────────────────────┘
                    /                   \
                   /                     \
                  ▼                       ▼
┌──────────────────────┐     ┌──────────────────────────────────┐
│     Assistant        │     │            Agent                  │
│  (Chat interface)    │     │  (Autonomous execution threads)   │
└──────────────────────┘     └──────────────────────────────────┘
         │                              │           │
         ▼                              ▼           │ hand_off_subagent
┌──────────────────────┐     ┌──────────────────────┴───────────┐
│   Chat Histories     │     │          Threads                  │
│  (Conversations)     │     │  (Execution sessions with tasks)  │
└──────────────────────┘     │                                   │
                              │  ┌─────────────────────────────┐ │
                              │  │  Subthreads                  │ │
                              │  │  (Child executions from      │ │
                              │  │   subagent handoffs)         │ │
                              │  └─────────────────────────────┘ │
                              └──────────────────────────────────┘

Key Concepts

Assistant Specialization: The core configuration object that defines how an AI assistant or agent behaves. It includes:

  • presets - System prompt instructions
  • availableToolsGroupsUids - Array of tool group identifiers that determine available tools
  • enabledTools - Optional subset of explicitly enabled tool identifiers
  • model / provider - Default LLM configuration
  • memoryDocuments - Persistent context documents

Agents: Autonomous executors that use an embedded assistantSpecialization configuration. When you create an agent, you configure its specialization which determines:

  • What tools it can use (via availableToolsGroupsUids)
  • How it behaves (via presets)
  • What LLM powers it (via model/provider)

Tool Servers: External API integrations that define tools. A tool server:

  1. Is created via the Tool Servers API
  2. Gets assigned to a Tools Group
  3. The group's UID is added to an assistant/agent's availableToolsGroupsUids
  4. The tools become available for that assistant/agent to use

Workflow Example

To give an agent access to a custom CRM API:

  1. Create Tool Server with your CRM endpoint definitions
  2. Create/Configure a Tools Group that references the tool server (done via Devic dashboard)
  3. Update the Agent's assistantSpecialization to include the tools group UID in availableToolsGroupsUids
  4. The agent can now call CRM tools during execution

API Sections

The Devic API is organized into three main sections:

1. Assistants API

Manage AI assistants that can process messages and maintain conversation history.

  • Create, update, and delete assistant specializations
  • List and retrieve assistant specializations
  • Send messages to assistants
  • Manage chat histories

Base path: /api/v1/assistants

For detailed documentation, see assistants.md.

2. Agents API

Manage autonomous agents that can execute multi-step tasks with tool access.

  • Create and manage agent execution threads
  • Handle approval workflows
  • Pause, resume, and complete agent executions
  • Evaluate agent performance
  • Track agent costs

Base path: /api/v1/agents

For detailed documentation, see agents.md.

3. Tool Servers API

Configure external tool integrations that agents and assistants can use.

  • Create and manage tool servers
  • Define tool specifications
  • Test tool configurations
  • Clone tool servers

Base path: /api/v1/tool-servers

For detailed documentation, see tool-servers.md.

4. Files API

Upload files and get shareable download URLs. Used for attaching files to assistant messages.

  • Upload files via multipart/form-data
  • Get download URLs for uploaded files

Base path: /api/v1/files

For detailed documentation, see files.md.

5. Feedback API

Collect user feedback on AI responses from both assistants and agents.

  • Submit feedback (positive/negative) on chat messages
  • Submit feedback on agent thread messages
  • Retrieve feedback history for chats and threads
  • Support for structured feedback data (ratings, categories, etc.)

Base paths:

  • Chat feedback: /api/v1/assistants/:identifier/chats/:chatUid/feedback
  • Thread feedback: /api/v1/agents/threads/:threadId/feedback

For detailed documentation, see feedback.md.

6. Whisper API (Speech-to-Text)

Transcribe audio to text using OpenAI Whisper with Devic's own OpenAI key.

  • Transcribe an audio binary (multipart) or a download URL
  • Optional language hint, message and chat linkage
  • Returns a transcriptId to attach to the resulting assistant message

Base path: /api/v1/whisper

For detailed documentation, see whisper.md.

7. Tenants API

Manage the tenants and subtenants of your account for multi-tenant products, read aggregated cost/usage, and enforce usage limits (token/cost caps) with reusable tiers (plans).

  • Auto-register tenants/subtenants by passing tenantId/subtenantId on messages and threads
  • List/update/delete tenants and subtenants
  • Read per-tenant cost time series and live chat/thread stats
  • Read usage limits, current consumption and durable history (read-only, devic-ui preset)
  • Reset counters and change tier from billing/checkout webhooks (full keys only)
  • Usage limits block execution with HTTP 429 TENANT_LIMIT_EXCEEDED

Base paths: /api/v1/tenants · /api/v1/tenant-usage · /api/v1/tenant-admin

For detailed documentation, see tenants.md.

8. Built-in Tools Reference

List of all built-in tool groups with their UIDs, ready to use in availableToolsGroupsUids.

For detailed documentation, see built-in-tools.md.

Pagination

List endpoints support pagination with the following query parameters:

| Parameter | Type | Default | Max | Description | |-----------|------|---------|-----|-------------| | offset | number | 0 | - | Number of items to skip | | limit | number | 10 | 100 | Maximum items to return |

Paginated responses include metadata:

{
  "data": [...],
  "total": 50,
  "offset": 0,
  "limit": 10,
  "hasMore": true
}

Rate Limits

API rate limits are applied per API key. Contact support for rate limit details specific to your plan.

Common HTTP Status Codes

| Code | Description | |------|-------------| | 200 | Success | | 201 | Created | | 400 | Bad Request - Invalid input data | | 401 | Unauthorized - Invalid or missing API key | | 404 | Not Found - Resource does not exist | | 429 | Too Many Requests - Rate limit, or tenant usage limit (TENANT_LIMIT_EXCEEDED, see tenants.md) | | 500 | Internal Server Error |

Quick Start Examples

Create an assistant

curl -X POST "https://api.devic.ai/api/v1/assistants" \
  -H "Authorization: Bearer devic-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Assistant",
    "description": "A helpful assistant",
    "model": "gpt-4.1-mini",
    "provider": "openai"
  }'

Send a message to an assistant

curl -X POST "https://api.devic.ai/api/v1/assistants/default/messages" \
  -H "Authorization: Bearer devic-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, how can you help me?",
    "chatUid": "optional-chat-id"
  }'

Create an agent thread

curl -X POST "https://api.devic.ai/api/v1/agents/{agentId}/threads" \
  -H "Authorization: Bearer devic-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze the sales data and create a report"
  }'

List tool servers

curl -X GET "https://api.devic.ai/api/v1/tool-servers?limit=10" \
  -H "Authorization: Bearer devic-your-api-key"