Thread API

Threads serve as conversation containers that store Messages exchanged between a user and an Assistant, maintaining context and continuity across interactions.

This page provides API schemas for the following methods:

Create a Thread	https://api.aimlapi.com/threads
Retrieve information about a specific Thread by its ID	https://api.aimlapi.com/threads/{threadId}
Modify a specific Thread by its ID	https://api.aimlapi.com/threads/{threadId}
Delete a specific Thread by its ID	https://api.aimlapi.com/threads/{threadId}

After each API schema, you'll find a short example demonstrating how to correctly call the described method in code using the OpenAI SDK.

Note that the method names in the API schema and the SDK often differ. Accordingly, when calling these methods via the REST API, you should use the names from the API schema, while for calls through the OpenAI SDK, use the names from the examples.

API Schemas

Create a Thread

post

Authorizations

Body

messagesobject[]Optional

A list of messages to start the thread with

metadataobjectOptional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

tool_resourcesobjectOptional

A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

Responses

application/json

objectOptional

post

HTTPcURLJavaScriptPython

POST /threads HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer <YOUR_AIMLAPI_KEY>
Content-Type: application/json
Accept: */*
Content-Length: 432

{
  "messages": [
    {
      "role": "user",
      "content": "text",
      "attachments": [
        {
          "file_id": "text",
          "tools": [
            {
              "type": "code_interpreter"
            }
          ]
        }
      ],
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "tool_resources": {
    "code_interpreter": {
      "file_ids": []
    },
    "file_search": {
      "vector_store_ids": [
        "text"
      ],
      "vector_stores": [
        {
          "chunking_strategy": {
            "type": "auto"
          },
          "file_ids": [
            "text"
          ],
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ]
    }
  }
}

default

{
  "id": "text",
  "created_at": 1,
  "metadata": null,
  "object": "thread",
  "tool_resources": {
    "code_interpreter": {
      "file_ids": [
        "text"
      ]
    },
    "file_search": {
      "vector_store_ids": [
        "text"
      ]
    }
  }
}

Python + OpenAI SDK Example:

from openai import OpenAI
client = OpenAI()

thread = client.beta.threads.create(
  messages=[
    {
      "role": "user",
      "content": "Create 3 data visualizations based on the trends in this file.",
      "attachments": [
        {
          "file_id": file.id,
          "tools": [{"type": "code_interpreter"}]
        }
      ]
    }
  ]
)        

---

Retrieve information about a specific Thread by its ID

get

Authorizations

Path parameters

threadIdstringRequired

Responses

application/json

objectOptional

get

HTTPcURLJavaScriptPython

GET /threads/{threadId} HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer <YOUR_AIMLAPI_KEY>
Accept: */*

default

{
  "id": "text",
  "created_at": 1,
  "metadata": null,
  "object": "thread",
  "tool_resources": {
    "code_interpreter": {
      "file_ids": [
        "text"
      ]
    },
    "file_search": {
      "vector_store_ids": [
        "text"
      ]
    }
  }
}

Python + OpenAI SDK Example:

from openai import OpenAI
client = OpenAI()

my_thread = client.beta.threads.retrieve("thread_abc123")
print(my_thread)

---

Modify a specific Thread by its ID

post

Authorizations

Path parameters

threadIdstringRequired

Body

metadataobjectOptional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

tool_resourcesobjectOptional

A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

Responses

application/json

objectOptional

post

HTTPcURLJavaScriptPython

POST /threads/{threadId} HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer <YOUR_AIMLAPI_KEY>
Content-Type: application/json
Accept: */*
Content-Length: 139

{
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "tool_resources": {
    "code_interpreter": {
      "file_ids": []
    },
    "file_search": {
      "vector_store_ids": []
    }
  }
}

default

{
  "id": "text",
  "created_at": 1,
  "metadata": null,
  "object": "thread",
  "tool_resources": {
    "code_interpreter": {
      "file_ids": [
        "text"
      ]
    },
    "file_search": {
      "vector_store_ids": [
        "text"
      ]
    }
  }
}

Python + OpenAI SDK Example:

from openai import OpenAI
client = OpenAI()

my_updated_thread = client.beta.threads.update(
  "thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123"
  }
)
print(my_updated_thread)

---

Delete a specific Thread by its ID

delete

Authorizations

Path parameters

threadIdstringRequired

Responses

application/json

objectOptional

delete

HTTPcURLJavaScriptPython

DELETE /threads/{threadId} HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer <YOUR_AIMLAPI_KEY>
Accept: */*

default

{
  "id": "text",
  "object": "thread.deleted",
  "deleted": true
}

Python + OpenAI SDK Example:

from openai import OpenAI
client = OpenAI()

response = client.beta.threads.delete("thread_abc123")
print(response)