Chat

Chat API

The Chat API in the Aimable Platform enables developers to integrate AI-powered conversational experiences into their applications by executing chat interactions within a space. A space represents a logical container for conversations, often tied to a specific project, user, or context. This API allows you to send messages, maintain conversation threads, manage file uploads, and control PII (Personally Identifiable Information) handling—all while leveraging advanced AI models and tool integrations.

This domain is ideal for building chatbots, AI assistants, or collaborative tools where contextual, model-driven conversations are required.

Key Concepts

• Space (space_id): A unique identifier (UUID) representing the environment where the chat occurs. All chat operations happen within a space.
• Thread (thread_id): An optional identifier to group related messages into a conversation thread.
• Message: The user input sent to the AI model. This is required for every chat request.
• PII Handling: Headers like X-Pii-Mapping and X-Auto-Pii-Mapping allow fine-grained control over how sensitive data is masked or processed.
• Tools: Optional integrations (e.g., database lookup, code execution) that the model can invoke during the chat.

How to Use the Chat Endpoint

The primary endpoint for chat interactions is:

POST /api-proxy/v1/spaces/{space_id}/chat

You send a message and receive an AI-generated response, optionally maintaining context via threads and tools.

Example Request

curl -X POST "https://api.aimable.ai/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/chat" \
  -H "Authorization: Bearer <your-access-token>" \
  -H "X-API-Key: your-api-key" \
  -H "X-Pii-Mapping: email=mask, ssn=redact" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the top risks in my project based on the uploaded files?",
    "thread_id": "thread_98765",
    "model": {
      "provider": "openai",
      "name": "gpt-4-turbo"
    },
    "uploaded_files": [
      "file-abc123",
      "file-def456"
    ],
    "pii_preview": true,
    "tools": {
      "code_interpreter": true,
      "data_lookup": {
        "dataset_id": "ds_123"
      }
    },
    "metadata": {
      "session_id": "sess_789",
      "user_tier": "premium"
    }
  }'

Example Success Response (200)

{
  "response": "Based on the uploaded documents, key risks include timeline overruns in Phase 2 and budget constraints in Q3...",
  "thread_id": "thread_98765",
  "message_id": "msg_001",
  "metadata": {
    "model_used": "gpt-4-turbo",
    "tokens_used": 248
  },
  "tool_calls": [
    {
      "type": "code_interpreter",
      "input": "Analyze budget.csv for anomalies"
    }
  ]
}

Common Workflows

1. Start a New Conversation

Send the first message without a thread_id to initiate a new conversation:

{
  "message": "Hello, help me plan a project timeline."
}

The response will include a thread_id—save this to continue the conversation.

2. Continue an Existing Chat

Include the thread_id from the previous response to maintain context:

{
  "thread_id": "thread_98765",
  "message": "Can you adjust the timeline for a two-week delay?"
}

3. Upload Files and Chat

Attach file IDs (previously uploaded via another API) to provide context:

{
  "message": "Summarize the findings in the report.",
  "uploaded_files": ["file-abc123"]
}

4. Use Tools with Controlled Access

Enable specific tools like code interpretation or data lookup:

{
  "message": "Plot a chart from the data in the uploaded CSV.",
  "tools": {
    "code_interpreter": true
  }
}

Authentication & Error Handling

Authentication

All requests require authentication via a Bearer token:

Authorization: Bearer <your-access-token>

Optionally, include an API key in the header:

X-API-Key: your-api-key

Error Responses

• 401 Unauthorized: Missing or invalid access token.
• 403 Forbidden: The authenticated user lacks permission to access the space.
• 422 Unprocessable Entity: Invalid request body. Example:

{
  "detail": [
    {
      "loc": ["body", "message"],
      "msg": "Field required",
      "type": "missing",
      "input": {}
    }
  ]
}

Always validate your JSON structure and ensure required fields like message are present.

The Chat API is the core of dynamic, AI-driven interactions in Aimable. By combining threads, file context, and tool use, you can build rich, stateful conversations tailored to your application’s needs.

Related Endpoints

• POST /v1/spaces/{space_id}/chat — Execute Space Chat