​
Definable.ai API Reference

The Definable.ai API is organized around REST principles, using standard HTTP verbs, returning JSON responses, and using standard HTTP status codes to indicate errors. Our API enables you to create, manage, and deploy AI agents and tools programmatically.

​
API Architecture Overview

​
Base URL

All API requests should be made to the following base URL: 
https://api.definable.ai
For local development, the base URL is: 
http://localhost:8000

​
Authentication

All API endpoints require authentication using either JWT tokens or API keys. See the Authentication Guide for details on how to authenticate your requests.

​
Bearer Token Authentication

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.definable.ai/v1/agents

​
API Key Authentication

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.definable.ai/v1/agents

​
Authentication Flow

​
Response Format

Responses are returned in JSON format. Successful responses typically include: 
{
  "status": "success",
  "data": {
    // Response data here
  }
}
Error responses follow a consistent structure: 
{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {} // Optional additional details
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request:
CodeDescription
200OK - The request was successful
201Created - A new resource was successfully created
400Bad Request - The request was invalid
401Unauthorized - Authentication failed or not provided
403Forbidden - The authenticated user doesn’t have permission
404Not Found - The requested resource doesn’t exist
422Unprocessable Entity - Validation error
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong on the server

​
Rate Limiting

API requests are subject to rate limiting to ensure stability and fair usage. The current limits are:
  • 100 requests per minute per IP address
  • 1000 requests per hour per authenticated user
Rate limit headers are included in all API responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1620000000

​
Pagination

For endpoints that return lists of items, the API uses cursor-based pagination. Parameters:
  • limit: Number of items to return (default: 20, max: 100)
  • cursor: Cursor for pagination (obtained from previous responses)
Paginated responses include: 
{
  "status": "success",
  "data": [
    // Items here
  ],
  "pagination": {
    "next_cursor": "next_page_cursor",
    "has_more": true
  }
}

​
🚀 API Endpoints

The Definable.ai API is organized into logical categories for easy navigation:

​
🤖 AI & Intelligence APIs

🤖 Agents API

Core Intelligence - Create, configure, and deploy AI agents with custom personalities, tools, and capabilities 🎯

🧠 LLM Services

Language Models - Integrate with GPT-4, Claude, and other cutting-edge models for natural conversation 💬

🛠️ Tools API

Agent Superpowers - Build and manage custom functions that extend agent capabilities ⚡

📚 Knowledge Base API

Smart Memory - Upload, process, and query documents with semantic search capabilities 🔍

​
💬 Communication APIs

💬 Conversations API

Chat Management - Handle multi-turn conversations, context, and message history 📝

⚡ WebSocket API

Real-time Streaming - Live communication with agents through WebSocket connections 🔄

​
👥 Organization & Security

🔐 Authentication API

Security Layer - JWT tokens, API keys, and secure authentication flows 🛡️

🏢 Organizations API

Team Management - Multi-tenant organization structure and user management 👥

👤 Roles & Permissions

Access Control - Fine-grained permissions and role-based access control (RBAC) ⚖️

📧 Invitations API

User Onboarding - Invite users and manage team member access 🎫

​
🔧 Utility APIs

📁 File Upload API

Asset Management - Secure file uploads, processing, and storage for documents, images, and media 📎

​
OpenAPI Specification

The complete OpenAPI specification for the Definable.ai API is available at: 
https://api.definable.ai/openapi.json
You can also explore the API interactively using Swagger UI: 
https://api.definable.ai/docs

​
Agent Creation Flow

​
Conversation Flow

​
Knowledge Base Processing Flow

​
Code Examples

​
Creating an AI Agent

curl -X POST "https://api.definable.ai/v1/agents" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "AI agent for handling customer inquiries",
    "model": "gpt-4",
    "system_prompt": "You are a helpful customer support assistant.",
    "tools": ["web_search", "knowledge_base"]
  }'

​
Client Libraries

Official client libraries for the Definable.ai API:

​
Webhooks

Definable.ai supports webhooks for real-time notifications about events in your account, including:
  • Agent deployment status changes
  • Conversation updates
  • Billing events
  • Knowledge base processing completion
See the Webhooks Guide for implementation details.