API Overview

Overview of the Definable.ai API endpoints and functionality

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

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:

• 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.