Skip to main content

API Reference

Welcome to the Autessa API reference documentation. This guide covers all client-facing APIs that you can use to integrate Autessa into your applications.

Base URL​

All API requests are made to:

https://api.autessa.com

For WebSocket connections:

wss://api.autessa.com

Authentication​

Autessa uses API keys for authentication. You'll need to generate an API key from the builder platform.

Generate API Key →

HTTP REST APIs​

For REST API requests, pass your API key in the Authorization header:

Authorization: your_api_key_here

Important: Do NOT prefix with "Bearer" - just pass the API key directly.

curl https://api.autessa.com/clients/agents/execute \
  -H "Authorization: your_api_key_here" \
  -H "Content-Type: application/json"

WebSocket APIs​

For WebSocket connections, pass your API key as a query parameter:

wss://api.autessa.com/ws/clients/agents/execute?authorization=your_api_key_here
websocat "wss://api.autessa.com/ws/clients/agents/execute?authorization=your_api_key_here&resourceId=123"

Resource ID Requirement​

All API requests to agents, tools, and AutessaDB require a resourceId query parameter. This ID is used to identify which resource you're interacting with and to track your API usage.

Finding Your Resource ID​

  1. Navigate to your resource in the Autessa Builder
  2. Click on the "Details" tab
  3. Copy the "ID" field - this is your resourceId

Usage​

# For Agents
https://api.autessa.com/clients/agents/execute?resourceId=123

# For Tools
https://api.autessa.com/clients/tool/execute?resourceId=456

# For AutessaDB
https://api.autessa.com/clients/autessadb/insert?resourceId=789

Common Response Format​

All API responses follow a consistent structure:

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages. Empty if the request succeeded.

  • Name
    sessionToken
    Type
    string
    Description

    Optional session token for authenticated requests.

  • Name
    ...data
    Type
    object
    Description

    Response-specific data fields.

{
  "errors": [],
  "conversationId": "conv_abc123",
  "output": [
    {
      "outputType": "TEXT",
      "content": "Hello! How can I help you?"
    }
  ]
}

Error Handling​

HTTP Status Codes​

  • Name
    200
    Description

    Success - Request completed successfully

  • Name
    401
    Description

    Unauthorized - Invalid or missing API key

  • Name
    429
    Description

    Rate Limit Exceeded - Includes Retry-After header

  • Name
    500
    Description

    Internal Server Error - Something went wrong on our end

Error Response Structure​

When errors occur, they are returned in the errors array:

{
  "errors": [
    "Resource with ID 123 not found",
    "Permission denied: READ access required"
  ]
}

Rate Limiting​

API requests are rate-limited to ensure fair usage. Rate limit information is included in response headers:

  • Name
    X-RateLimit-Limit-Minute
    Type
    integer
    Description

    Maximum requests allowed per minute

  • Name
    X-RateLimit-Remaining-Minute
    Type
    integer
    Description

    Remaining requests in the current minute

  • Name
    X-RateLimit-Limit-Day
    Type
    integer
    Description

    Maximum requests allowed per day

  • Name
    X-RateLimit-Remaining-Day
    Type
    integer
    Description

    Remaining requests for the current day

When you exceed the rate limit, you'll receive a 429 status code with a Retry-After header indicating how long to wait before retrying.

Versioning​

By default, all API requests use the PUBLISHED version of your resource. You can override this using the version parameter in your requests.

  • Name
    versionState
    Type
    enum
    Description

    The version state: PUBLISHED, DRAFT, or ARCHIVED. Default is PUBLISHED.

  • Name
    versionNumber
    Type
    integer
    Description

    Specific version number to use (optional).

{
  "agentId": 123,
  "input": [...],
  "version": {
    "versionState": "DRAFT"
  }
}

Available APIs​

Agent API​

The Agent API allows you to create conversations, execute agents, and manage multi-turn interactions with AI agents.

Key Features:

  • Multi-turn conversations with context
  • Multimodal input (text and audio)
  • Real-time streaming via WebSockets
  • Voice mode with automatic transcription
  • Audio output generation

View the Agent API documentation →

Tool API​

The Tool API enables you to execute custom tools that you've built in the Autessa platform.

Key Features:

  • Synchronous and streaming execution
  • Environment variables and private variables
  • Real-time debugging output
  • Version control

View the Tool API documentation →

AutessaDB API​

The AutessaDB API provides a complete database solution with semantic search capabilities.

Key Features:

  • CRUD operations (Create, Read, Update, Delete)
  • Semantic vector search
  • Batch operations
  • Join queries across tables
  • File upload support
  • Automatic vectorization

View the AutessaDB API documentation →

AutessaDB Drive API​

Browse, upload, search, read, and share the files and folders in an AutessaDB Drive.

Key Features:

  • Folder listing, glob find, and folder trees
  • Exact-text grep and ranked search (meaning-based when enabled) with page and line locators
  • Direct-to-storage uploads, including multipart for large files
  • Versions, trash, and restore
  • Sharing with people, teams, your company, or a link

View the Drive API documentation →

AutessaDB Analytics API​

Run read-only SQL over columnar analytics tables with millions to billions of rows.

Key Features:

  • Table descriptions with a semantic layer for agents
  • Queries as jobs, with paged results and downloads
  • Scan estimates before you run
  • File loads and small-batch appends

View the Analytics API documentation →

WebSocket Features​

All WebSocket connections support:

Heartbeat Mechanism​

  • Automatic ping/pong handling to keep connections alive
  • 30-minute idle timeout
  • Graceful disconnection handling

Connection Lifecycle​

  1. Connect - Establish WebSocket connection with authentication
  2. Receive Status - Server sends initial connection status
  3. Send Messages - Client sends requests to the server
  4. Receive Responses - Server streams back responses
  5. Disconnect - Clean connection close

Best Practices​

Security​

  • Never expose your API keys in client-side code
  • Use environment variables to store API keys
  • Rotate keys regularly
  • Use separate keys for development and production

Performance​

  • Use WebSockets for real-time, multi-turn interactions
  • Use REST APIs for single-shot requests
  • Implement exponential backoff for retries
  • Cache responses when appropriate

Error Handling​

  • Always check the errors array in responses
  • Implement proper error handling for network failures
  • Handle rate limit errors with retry logic
  • Log errors for debugging

Conversations​

  • Close conversations when done to trigger logging and evaluation
  • Conversations auto-close after 12 hours of inactivity
  • Use conversation IDs to maintain context across requests
  • Don't create unnecessary conversations for single-turn interactions

Support​

Need help? Here are some resources:

Autessa Builder → · Join our Discord →

For technical questions or bug reports, please contact our support team at support@autessa.com.