Message API

Messages are individual pieces of communication within a Thread, sent either by the user or the Assistant, helping to maintain the flow and context of the conversation.

This page provides API schemas for the following methods:

https://api.aimlapi.com/threads/{threadId}/messages

https://api.aimlapi.com/threads/{threadId}/messages

https://api.aimlapi.com/threads/{threadId}/messages/{messageId}

https://api.aimlapi.com/threads/{threadId}/messages/{messageId}

https://api.aimlapi.com/threads/{threadId}/messages/{messageId}

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

API Schemas

Create a Message

post
Authorizations
Path parameters
threadIdstringRequired
Body
rolestring · enumRequired

The role of the entity that is creating the Message

Possible values:
contentany ofRequired
stringOptional

The text contents of the Message

or
Responses
default
application/json
post
POST /threads/{threadId}/messages HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer <YOUR_AIMLAPI_KEY>
Content-Type: application/json
Accept: */*
Content-Length: 151

{
  "role": "user",
  "content": "text",
  "attachments": [
    {
      "file_id": "text",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
default
{
  "role": "user",
  "content": "text",
  "attachments": [
    {
      "file_id": "text",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "id": "text",
  "object": "thread.message",
  "status": "completed",
  "created_at": 1,
  "completed_at": 1,
  "incomplete_at": 1,
  "incomplete_details": {
    "reason": "text"
  },
  "assistant_id": "text",
  "thread_id": "text",
  "run_id": "text"
}

Python + OpenAI SDK Example:

from openai import OpenAI
client = OpenAI()

thread_message = client.beta.threads.messages.create(
  "thread_abc123",
  role="user",
  content="How does AI work? Explain it in simple terms.",
)
print(thread_message)


Retrieve a list of Messages from a specific Thread along with their properties

get
Authorizations
Path parameters
threadIdstringRequired
Query parameters
limitintegerOptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

orderstringOptional

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

beforestringOptional

A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

afterstringOptional

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

run_idstringOptional

Filter Messages by the Run ID that generated them.

Responses
default
application/json
get
GET /threads/{threadId}/messages HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer <YOUR_AIMLAPI_KEY>
Accept: */*
default
{
  "object": "list",
  "data": [
    {
      "role": "user",
      "content": "text",
      "attachments": [
        {
          "file_id": "text",
          "tools": [
            {
              "type": "code_interpreter"
            }
          ]
        }
      ],
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "id": "text",
      "object": "thread.message",
      "status": "completed",
      "created_at": 1,
      "completed_at": 1,
      "incomplete_at": 1,
      "incomplete_details": {
        "reason": "text"
      },
      "assistant_id": "text",
      "thread_id": "text",
      "run_id": "text"
    }
  ],
  "first_id": "text",
  "last_id": "text",
  "has_more": true
}

Python + OpenAI SDK Example:

from openai import OpenAI
client = OpenAI()

thread_messages = client.beta.threads.messages.list("thread_abc123")
print(thread_messages.data)


Retrieve information about a specific Message by its ID

get
Authorizations
Path parameters
threadIdstringRequired
messageIdstringRequired
Responses
default
application/json
get
GET /threads/{threadId}/messages/{messageId} HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer <YOUR_AIMLAPI_KEY>
Accept: */*
default
{
  "role": "user",
  "content": "text",
  "attachments": [
    {
      "file_id": "text",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "id": "text",
  "object": "thread.message",
  "status": "completed",
  "created_at": 1,
  "completed_at": 1,
  "incomplete_at": 1,
  "incomplete_details": {
    "reason": "text"
  },
  "assistant_id": "text",
  "thread_id": "text",
  "run_id": "text"
}

Python + OpenAI SDK Example:

from openai import OpenAI
client = OpenAI()

message = client.beta.threads.messages.retrieve(
  message_id="msg_abc123",
  thread_id="thread_abc123",
)
print(message)


Modify a specific message by its ID

post
Authorizations
Path parameters
threadIdstringRequired
messageIdstringRequired
Body
Responses
default
application/json
post
POST /threads/{threadId}/messages/{messageId} HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer <YOUR_AIMLAPI_KEY>
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}
default
{
  "role": "user",
  "content": "text",
  "attachments": [
    {
      "file_id": "text",
      "tools": [
        {
          "type": "code_interpreter"
        }
      ]
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "id": "text",
  "object": "thread.message",
  "status": "completed",
  "created_at": 1,
  "completed_at": 1,
  "incomplete_at": 1,
  "incomplete_details": {
    "reason": "text"
  },
  "assistant_id": "text",
  "thread_id": "text",
  "run_id": "text"
}

Python + OpenAI SDK Example:

from openai import OpenAI
client = OpenAI()

message = client.beta.threads.messages.update(
  message_id="msg_abc12",
  thread_id="thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123",
  },
)
print(message)


Delete a specific message by its ID

delete
Authorizations
Path parameters
threadIdstringRequired
messageIdstringRequired
Responses
default
application/json
delete
DELETE /threads/{threadId}/messages/{messageId} HTTP/1.1
Host: api.aimlapi.com
Authorization: Bearer <YOUR_AIMLAPI_KEY>
Accept: */*
default
{
  "id": "text",
  "object": "thread.message.deleted",
  "deleted": true
}

Python + OpenAI SDK Example:

from openai import OpenAI
client = OpenAI()

deleted_message = client.beta.threads.messages.delete(
  message_id="msg_abc12",
  thread_id="thread_abc123",
)
print(deleted_message)

Last updated

Was this helpful?