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:

Code	Description
200	OK - The request was successful
201	Created - A new resource was successfully created
400	Bad Request - The request was invalid
401	Unauthorized - Authentication failed or not provided
403	Forbidden - The authenticated user doesn’t have permission
404	Not Found - The requested resource doesn’t exist
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limit exceeded
500	Internal 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"]
  }'

import requests

url = "https://api.definable.ai/v1/agents"
headers = {
    "Authorization": "Bearer YOUR_JWT_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "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"]
}

response = requests.post(url, headers=headers, json=data)
agent = response.json()
print(f"Created agent: {agent['data']['id']}")

interface Agent {
  name: string;
  description: string;
  model: string;
  system_prompt: string;
  tools: string[];
}

const createAgent = async (agent: Agent): Promise<any> => {
  const response = await fetch('https://api.definable.ai/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(agent),
  });
  
  return await response.json();
};

const newAgent = await createAgent({
  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"]
});

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type Agent struct {
    Name         string   `json:"name"`
    Description  string   `json:"description"`
    Model        string   `json:"model"`
    SystemPrompt string   `json:"system_prompt"`
    Tools        []string `json:"tools"`
}

func createAgent(agent Agent) error {
    url := "https://api.definable.ai/v1/agents"
    
    jsonData, err := json.Marshal(agent)
    if err != nil {
        return err
    }
    
    req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    if err != nil {
        return err
    }
    
    req.Header.Set("Authorization", "Bearer YOUR_JWT_TOKEN")
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    
    fmt.Println("Agent created successfully!")
    return nil
}

func main() {
    agent := Agent{
        Name:         "Customer Support Agent",
        Description:  "AI agent for handling customer inquiries",
        Model:        "gpt-4",
        SystemPrompt: "You are a helpful customer support assistant.",
        Tools:        []string{"web_search", "knowledge_base"},
    }
    
    createAgent(agent)
}

Client Libraries

Official client libraries for the Definable.ai API:

Python SDK - Full-featured Python client
TypeScript/JavaScript SDK - Browser and Node.js support
Go SDK - Lightweight Go client

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.

​Definable.ai API Reference

​API Architecture Overview

​Base URL

​Authentication

​Bearer Token Authentication

​API Key Authentication

​Authentication Flow

​Response Format

​HTTP Status Codes

​Rate Limiting

​Pagination

​🚀 API Endpoints

​🤖 AI & Intelligence APIs