AimableDocs
DocsAPI ReferenceRelease Notes

Threads

Updated 9 July 2026

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.

bash
curl -X POST 'https://api.aimable.com/api/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):

json
{
  "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.

bash
curl -X POST 'https://api.aimable.com/api/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):

json
{
  "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

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

Response (200 OK):

json
{
  "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:

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

Update a thread’s title:

bash
curl -X PATCH 'https://api.aimable.com/api/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):

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

See Authentication & errors for request authentication and the standard error responses.

Related Endpoints

See also