AimableDocs
DocsAPI Reference

Threads

Threads API

The Threads API in the Aimable Platform enables structured, persistent conversations—ideal for chat applications, AI assistant interactions, or collaborative workflows. A thread represents a single conversation, containing a sequence of messages between participants. Threads are scoped to a space and can be created, updated, archived, and queried along with their message history.

This API is essential for building conversational interfaces where context persistence, message threading, and auditability matter.

Key Concepts

  • Thread: A container for a conversation. Has metadata like title, status, and timestamps.
  • Message: A single entry in a thread with content, role (e.g., "user", "assistant"), and optional metadata.
  • Space: Logical grouping (via space_id) that isolates threads and messages.
  • Idempotency-Key: Optional header to ensure safe retries when creating messages.

All endpoints require authentication via X-API-Key or a Bearer token (not shown in examples; include either as needed).

Common Workflows

1. Start a New Conversation

Use Create First Message to simultaneously create a new thread and its first message.

curl -X POST 'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/threads/messages' \
  -H 'X-API-Key: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "What's the weather like today?",
    "role": "user",
    "project_id": "proj-abc123",
    "title": {
      "en": "Weather Inquiry"
    },
    "metadata": {
      "source": "web"
    }
  }'

Response (201 Created):

{
  "data": {
    "id": "msg-9f6a-4a1c-8e22",
    "thread_id": "thread-7b5e-4f1a-9c2d",
    "content": "What's the weather like today?",
    "role": "user",
    "created_at": "2023-10-05T14:48:00.000Z"
  }
}

The response includes the new message and implicitly creates a thread. Use the returned thread_id for follow-up actions.

2. Add a Reply to an Existing Thread

Use Create Message to append to a thread.

curl -X POST 'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/threads/thread-7b5e-4f1a-9c2d/messages' \
  -H 'X-API-Key: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "It's sunny and 75°F.",
    "role": "assistant",
    "parent_message_id": "msg-9f6a-4a1c-8e22",
    "metadata": {
      "model": "gpt-4"
    }
  }'

Response (201 Created):

{
  "data": {
    "id": "msg-2a3b-5c4d-9f1e",
    "thread_id": "thread-7b5e-4f1a-9c2d",
    "content": "It's sunny and 75°F.",
    "role": "assistant",
    "created_at": "2023-10-05T15:00:00.000Z"
  }
}

3. Retrieve All Messages in a Thread

curl 'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/threads/thread-7b5e-4f1a-9c2d/messages' \
  -H 'X-API-Key: your_api_key'

Response (200 OK):

{
  "data": [
    {
      "id": "msg-9f6a-4a1c-8e22",
      "content": "What's the weather like today?",
      "role": "user",
      "created_at": "2023-10-05T14:48:00.000Z"
    },
    {
      "id": "msg-2a3b-5c4d-9f1e",
      "content": "It's sunny and 75°F.",
      "role": "assistant",
      "created_at": "2023-10-05T15:00:00.000Z"
    }
  ],
  "meta": {
    "has_more": false
  }
}

4. List and Manage Threads

Get all threads in a space:

curl 'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/threads' \
  -H 'X-API-Key: your_api_key'

Update a thread’s title:

curl -X PATCH 'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/threads/thread-7b5e-4f1a-9c2d' \
  -H 'X-API-Key: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": {
      "en": "Updated: Weather and Forecast"
    }
  }'

Archive a thread (soft delete):

curl -X DELETE 'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/threads/thread-7b5e-4f1a-9c2d' \
  -H 'X-API-Key: your_api_key'

Authentication & Error Handling

  • All endpoints require authentication. Use either:
    • X-API-Key: <your_key>
    • Authorization: Bearer <token>
  • Common errors:
    • 401: Missing or invalid credentials
    • 403: Insufficient permissions
    • 422: Invalid input (check detail.loc and detail.msg)

Example error:

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

Use these patterns to build reliable, stateful conversations with full control over thread lifecycle and message history.

Related Endpoints