> ## Documentation Index > Fetch the complete documentation index at: https://docs.zyeta.io/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```mermaid theme={null} graph TB Client[Client Application] --> Auth[Authentication Layer] Auth --> Gateway[API Gateway] Gateway --> Services[Microservices] subgraph Services AgentService[Agent Service] ToolService[Tool Service] KBService[Knowledge Base Service] ChatService[Chat Service] LLMService[LLM Service] OrgService[Organization Service] AuthService[Auth Service] WSService[WebSocket Service] end Services --> Database[(PostgreSQL Database)] Services --> VectorDB[(Vector Database)] Services --> S3[S3 Storage] Services --> Redis[(Redis Cache)] subgraph External APIs OpenAI[OpenAI API] Anthropic[Anthropic API] Stripe[Stripe API] end LLMService --> OpenAI LLMService --> Anthropic Services --> Stripe style Client fill:#e1f5fe style Auth fill:#f3e5f5 style Gateway fill:#e8f5e8 style Database fill:#fff3e0 style VectorDB fill:#fff3e0 style S3 fill:#fff3e0 style Redis fill:#fff3e0 ``` ## 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](/pages/authentication/overview) for details on how to authenticate your requests. ### Bearer Token Authentication ```bash theme={null} curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \ https://api.definable.ai/v1/agents ``` ### API Key Authentication ```bash theme={null} curl -H "X-API-Key: YOUR_API_KEY" \ https://api.definable.ai/v1/agents ``` ## Authentication Flow ```mermaid theme={null} sequenceDiagram participant C as Client participant A as Auth Service participant D as Database participant S as Services Note over C,S: JWT Authentication Flow C->>A: POST /auth/login (email, password) A->>D: Validate credentials D-->>A: User data A->>A: Generate JWT token A-->>C: JWT token + user info Note over C,S: API Request with JWT C->>S: API Request + Authorization: Bearer JWT S->>A: Validate JWT token A-->>S: Token valid + user context S->>D: Execute request D-->>S: Response data S-->>C: API Response Note over C,S: API Key Authentication Flow C->>S: API Request + X-API-Key: API_KEY S->>A: Validate API key A->>D: Check API key D-->>A: API key valid + permissions A-->>S: Key valid + user context S->>D: Execute request D-->>S: Response data S-->>C: API Response ``` ## Response Format Responses are returned in JSON format. Successful responses typically include: ```json theme={null} { "status": "success", "data": { // Response data here } } ``` Error responses follow a consistent structure: ```json theme={null} { "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: ```json theme={null} { "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 **Core Intelligence** - Create, configure, and deploy AI agents with custom personalities, tools, and capabilities 🎯 **Language Models** - Integrate with GPT-4, Claude, and other cutting-edge models for natural conversation 💬 **Agent Superpowers** - Build and manage custom functions that extend agent capabilities ⚡ **Smart Memory** - Upload, process, and query documents with semantic search capabilities 🔍 ### 💬 Communication APIs **Chat Management** - Handle multi-turn conversations, context, and message history 📝 **Real-time Streaming** - Live communication with agents through WebSocket connections 🔄 ### 👥 Organization & Security **Security Layer** - JWT tokens, API keys, and secure authentication flows 🛡️ **Team Management** - Multi-tenant organization structure and user management 👥 **Access Control** - Fine-grained permissions and role-based access control (RBAC) ⚖️ **User Onboarding** - Invite users and manage team member access 🎫 ### 🔧 Utility APIs **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 ```mermaid theme={null} sequenceDiagram participant C as Client participant AS as Agent Service participant TS as Tool Service participant LLM as LLM Service participant KB as Knowledge Base participant D as Database C->>AS: POST /agents (agent config) AS->>D: Validate & save agent metadata AS->>TS: Fetch configured tools TS-->>AS: Tool specifications AS->>LLM: Validate model availability LLM-->>AS: Model validation AS->>KB: Setup agent knowledge base KB-->>AS: KB ready AS->>D: Save complete agent config D-->>AS: Agent created AS-->>C: Agent ID + metadata Note over C,D: Agent is now ready for deployment ``` ## Conversation Flow ```mermaid theme={null} sequenceDiagram participant C as Client participant CS as Chat Service participant AS as Agent Service participant LLM as LLM Service participant TS as Tool Service participant KB as Knowledge Base participant WS as WebSocket Service C->>CS: POST /conversations (start chat) CS->>D: Create conversation CS-->>C: Conversation ID C->>WS: Connect WebSocket WS-->>C: Connection established C->>CS: POST /messages (user message) CS->>AS: Get agent context AS-->>CS: Agent config + tools CS->>KB: Query knowledge base KB-->>CS: Relevant context CS->>LLM: Generate response alt Tool usage required LLM-->>CS: Tool call request CS->>TS: Execute tool TS-->>CS: Tool result CS->>LLM: Continue with tool result end LLM-->>CS: Final response CS->>D: Save message + response CS->>WS: Stream response WS-->>C: Real-time response CS-->>C: Complete response ``` ## Knowledge Base Processing Flow ```mermaid theme={null} flowchart TD A[Upload Document] --> B{Document Type?} B -->|PDF| C[PDF Processor] B -->|Text| D[Text Processor] B -->|URL| E[Web Scraper] B -->|Image| F[OCR Processor] C --> G[Extract Text] D --> G E --> G F --> G G --> H[Text Chunking] H --> I[Generate Embeddings] I --> J[Store in Vector DB] J --> K[Index Document] K --> L[Document Ready for Search] style A fill:#e3f2fd style L fill:#e8f5e8 style J fill:#fff3e0 ``` ## Code Examples ### Creating an AI Agent ```bash curl theme={null} 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"] }' ``` ```python python theme={null} 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']}") ``` ```typescript typescript theme={null} interface Agent { name: string; description: string; model: string; system_prompt: string; tools: string[]; } const createAgent = async (agent: Agent): Promise => { 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"] }); ``` ```go go theme={null} 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](https://github.com/Neuron-Square/definable-python) - Full-featured Python client * [TypeScript/JavaScript SDK](https://github.com/Neuron-Square/definable-js) - Browser and Node.js support * [Go SDK](https://github.com/Neuron-Square/definable-go) - 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](/pages/development-guides/webhooks) for implementation details.