OpenAI Threads API
Create threads that assistants can interact with.
OpenAPI Specification
openapi: 3.0.0
info:
title: 'OpenAI threads'
description: Needs description.
version: 2.0.0
termsOfService: https://openai.com/policies/terms-of-use
contact:
name: OpenAI Support
url: https://help.openai.com/
license:
name: MIT
url: https://github.com/openai/openai-openapi/blob/master/LICENSE
servers:
- url: https://api.openai.com/v1
tags:
- name: Threads
paths:
/threads:
post:
operationId: createThread
tags:
- Threads
summary: OpenAI Create a thread.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateThreadRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ThreadObject'
x-oaiMeta:
name: Create thread
group: threads
beta: true
returns: A [thread](/docs/api-reference/threads) object.
examples:
- title: Empty
request:
curl: |
curl https://api.openai.com/v1/threads \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1" \
-d ''
python: |
from openai import OpenAI
client = OpenAI()
empty_thread = client.beta.threads.create()
print(empty_thread)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const emptyThread = await openai.beta.threads.create();
console.log(emptyThread);
}
main();
response: |
{
"id": "thread_abc123",
"object": "thread",
"created_at": 1699012949,
"metadata": {}
}
- title: Messages
request:
curl: |
curl https://api.openai.com/v1/threads \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1" \
-d '{
"messages": [{
"role": "user",
"content": "Hello, what is AI?",
"file_ids": ["file-abc123"]
}, {
"role": "user",
"content": "How does AI work? Explain it in simple terms."
}]
}'
python: |
from openai import OpenAI
client = OpenAI()
message_thread = client.beta.threads.create(
messages=[
{
"role": "user",
"content": "Hello, what is AI?",
"file_ids": ["file-abc123"],
},
{
"role": "user",
"content": "How does AI work? Explain it in simple terms."
},
]
)
print(message_thread)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const messageThread = await openai.beta.threads.create({
messages: [
{
role: "user",
content: "Hello, what is AI?",
file_ids: ["file-abc123"],
},
{
role: "user",
content: "How does AI work? Explain it in simple terms.",
},
],
});
console.log(messageThread);
}
main();
response: |
{
id: 'thread_abc123',
object: 'thread',
created_at: 1699014083,
metadata: {}
}
/threads/{thread_id}:
get:
operationId: getThread
tags:
- Threads
summary: OpenAI Retrieves a thread.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the thread to retrieve.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ThreadObject'
x-oaiMeta:
name: Retrieve thread
group: threads
beta: true
returns: >-
The [thread](/docs/api-reference/threads/object) object matching the
specified ID.
examples:
request:
curl: |
curl https://api.openai.com/v1/threads/thread_abc123 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1"
python: |
from openai import OpenAI
client = OpenAI()
my_thread = client.beta.threads.retrieve("thread_abc123")
print(my_thread)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const myThread = await openai.beta.threads.retrieve(
"thread_abc123"
);
console.log(myThread);
}
main();
response: |
{
"id": "thread_abc123",
"object": "thread",
"created_at": 1699014083,
"metadata": {}
}
post:
operationId: modifyThread
tags:
- Threads
summary: OpenAI Modifies a thread.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the thread to modify. Only the `metadata` can be modified.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyThreadRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ThreadObject'
x-oaiMeta:
name: Modify thread
group: threads
beta: true
returns: >-
The modified [thread](/docs/api-reference/threads/object) object
matching the specified ID.
examples:
request:
curl: |
curl https://api.openai.com/v1/threads/thread_abc123 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1" \
-d '{
"metadata": {
"modified": "true",
"user": "abc123"
}
}'
python: |
from openai import OpenAI
client = OpenAI()
my_updated_thread = client.beta.threads.update(
"thread_abc123",
metadata={
"modified": "true",
"user": "abc123"
}
)
print(my_updated_thread)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const updatedThread = await openai.beta.threads.update(
"thread_abc123",
{
metadata: { modified: "true", user: "abc123" },
}
);
console.log(updatedThread);
}
main();
response: |
{
"id": "thread_abc123",
"object": "thread",
"created_at": 1699014083,
"metadata": {
"modified": "true",
"user": "abc123"
}
}
delete:
operationId: deleteThread
tags:
- Threads
summary: OpenAI Delete a thread.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the thread to delete.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteThreadResponse'
x-oaiMeta:
name: Delete thread
group: threads
beta: true
returns: Deletion status
examples:
request:
curl: |
curl https://api.openai.com/v1/threads/thread_abc123 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1" \
-X DELETE
python: |
from openai import OpenAI
client = OpenAI()
response = client.beta.threads.delete("thread_abc123")
print(response)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const response = await openai.beta.threads.del("thread_abc123");
console.log(response);
}
main();
response: |
{
"id": "thread_abc123",
"object": "thread.deleted",
"deleted": true
}
/threads/{thread_id}/messages:
get:
operationId: listMessages
tags:
- Threads
summary: OpenAI Returns a list of messages for a given thread.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: >-
The ID of the [thread](/docs/api-reference/threads) the messages
belong to.
- name: limit
in: query
description: >
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
required: false
schema:
type: integer
default: 20
- name: order
in: query
description: >
Sort order by the `created_at` timestamp of the objects. `asc` for
ascending order and `desc` for descending order.
schema:
type: string
default: desc
enum:
- asc
- desc
- name: after
in: query
description: >
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.
schema:
type: string
- name: before
in: query
description: >
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, ending with obj_foo, your
subsequent call can include before=obj_foo in order to fetch the
previous page of the list.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListMessagesResponse'
x-oaiMeta:
name: List messages
group: threads
beta: true
returns: A list of [message](/docs/api-reference/messages) objects.
examples:
request:
curl: |
curl https://api.openai.com/v1/threads/thread_abc123/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1"
python: >
from openai import OpenAI
client = OpenAI()
thread_messages =
client.beta.threads.messages.list("thread_abc123")
print(thread_messages.data)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const threadMessages = await openai.beta.threads.messages.list(
"thread_abc123"
);
console.log(threadMessages.data);
}
main();
response: |
{
"object": "list",
"data": [
{
"id": "msg_abc123",
"object": "thread.message",
"created_at": 1699016383,
"thread_id": "thread_abc123",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "How does AI work? Explain it in simple terms.",
"annotations": []
}
}
],
"file_ids": [],
"assistant_id": null,
"run_id": null,
"metadata": {}
},
{
"id": "msg_abc456",
"object": "thread.message",
"created_at": 1699016383,
"thread_id": "thread_abc123",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "Hello, what is AI?",
"annotations": []
}
}
],
"file_ids": [
"file-abc123"
],
"assistant_id": null,
"run_id": null,
"metadata": {}
}
],
"first_id": "msg_abc123",
"last_id": "msg_abc456",
"has_more": false
}
post:
operationId: createMessage
tags:
- Threads
summary: OpenAI Create a message.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: >-
The ID of the [thread](/docs/api-reference/threads) to create a
message for.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MessageObject'
x-oaiMeta:
name: Create message
group: threads
beta: true
returns: A [message](/docs/api-reference/messages/object) object.
examples:
request:
curl: |
curl https://api.openai.com/v1/threads/thread_abc123/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1" \
-d '{
"role": "user",
"content": "How does AI work? Explain it in simple terms."
}'
python: |
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)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const threadMessages = await openai.beta.threads.messages.create(
"thread_abc123",
{ role: "user", content: "How does AI work? Explain it in simple terms." }
);
console.log(threadMessages);
}
main();
response: |
{
"id": "msg_abc123",
"object": "thread.message",
"created_at": 1699017614,
"thread_id": "thread_abc123",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "How does AI work? Explain it in simple terms.",
"annotations": []
}
}
],
"file_ids": [],
"assistant_id": null,
"run_id": null,
"metadata": {}
}
/threads/{thread_id}/messages/{message_id}:
get:
operationId: getMessage
tags:
- Threads
summary: OpenAI Retrieve a message.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: >-
The ID of the [thread](/docs/api-reference/threads) to which this
message belongs.
- in: path
name: message_id
required: true
schema:
type: string
description: The ID of the message to retrieve.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MessageObject'
x-oaiMeta:
name: Retrieve message
group: threads
beta: true
returns: >-
The [message](/docs/api-reference/threads/messages/object) object
matching the specified ID.
examples:
request:
curl: >
curl
https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123
\
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1"
python: |
from openai import OpenAI
client = OpenAI()
message = client.beta.threads.messages.retrieve(
message_id="msg_abc123",
thread_id="thread_abc123",
)
print(message)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const message = await openai.beta.threads.messages.retrieve(
"thread_abc123",
"msg_abc123"
);
console.log(message);
}
main();
response: |
{
"id": "msg_abc123",
"object": "thread.message",
"created_at": 1699017614,
"thread_id": "thread_abc123",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "How does AI work? Explain it in simple terms.",
"annotations": []
}
}
],
"file_ids": [],
"assistant_id": null,
"run_id": null,
"metadata": {}
}
post:
operationId: modifyMessage
tags:
- Threads
summary: OpenAI Modifies a message.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the thread to which this message belongs.
- in: path
name: message_id
required: true
schema:
type: string
description: The ID of the message to modify.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyMessageRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MessageObject'
x-oaiMeta:
name: Modify message
group: threads
beta: true
returns: >-
The modified [message](/docs/api-reference/threads/messages/object)
object.
examples:
request:
curl: >
curl
https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123
\
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1" \
-d '{
"metadata": {
"modified": "true",
"user": "abc123"
}
}'
python: |
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)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const message = await openai.beta.threads.messages.update(
"thread_abc123",
"msg_abc123",
{
metadata: {
modified: "true",
user: "abc123",
},
}
}'
response: |
{
"id": "msg_abc123",
"object": "thread.message",
"created_at": 1699017614,
"thread_id": "thread_abc123",
"role": "user",
"content": [
{
"type": "text",
"text": {
"value": "How does AI work? Explain it in simple terms.",
"annotations": []
}
}
],
"file_ids": [],
"assistant_id": null,
"run_id": null,
"metadata": {
"modified": "true",
"user": "abc123"
}
}
/threads/runs:
post:
operationId: createThreadAndRun
tags:
- Threads
summary: OpenAI Create a thread and run it in one request.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateThreadAndRunRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RunObject'
x-oaiMeta:
name: Create thread and run
group: threads
beta: true
returns: A [run](/docs/api-reference/runs/object) object.
examples:
request:
curl: |
curl https://api.openai.com/v1/threads/runs \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: assistants=v1" \
-d '{
"assistant_id": "asst_abc123",
"thread": {
"messages": [
{"role": "user", "content": "Explain deep learning to a 5 year old."}
]
}
}'
python: |
from openai import OpenAI
client = OpenAI()
run = client.beta.threads.create_and_run(
assistant_id="asst_abc123",
thread={
"messages": [
{"role": "user", "content": "Explain deep learning to a 5 year old."}
]
}
)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const run = await openai.beta.threads.createAndRun({
assistant_id: "asst_abc123",
thread: {
messages: [
{ role: "user", content: "Explain deep learning to a 5 year old." },
],
},
});
console.log(run);
}
main();
response: |
{
"id": "run_abc123",
"object": "thread.run",
"created_at": 1699076792,
"assistant_id": "asst_abc123",
"thread_id": "thread_abc123",
"status": "queued",
"started_at": null,
"expires_at": 1699077392,
"cancelled_at": null,
"failed_at": null,
"completed_at": null,
"last_error": null,
"model": "gpt-4",
"instructions": "You are a helpful assistant.",
"tools": [],
"file_ids": [],
"metadata": {},
"usage": null
}
/threads/{thread_id}/runs:
get:
operationId: listRuns
tags:
- Threads
summary: OpenAI Returns a list of runs belonging to a thread.
parameters:
- name: thread_id
in: path
required: true
schema:
type: string
description: The ID of the thread the run belongs to.
- name: limit
in: query
description: >
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 20.
required: false
schema:
type: integer
default: 20
- name: order
in: query
description: >
Sort order by the `created_at` timestamp of the objects. `asc` for
ascending order and `desc` for descending order.
schema:
type: string
default: desc
enum:
- asc
- desc
- name: after
in: query
description: >
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.
schema:
type: string
- name: before
in: query
description: >
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, ending with obj_foo, your
subsequent call can include before=obj_foo in order to fetch the
previous page of the list.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListRunsResponse'
x-oaiMeta:
name: List runs
group: threads
beta: true
returns: A list of [run](/docs/api-reference/runs/object) objects.
examples:
request:
curl: |
curl https://api.openai.com/v1/threads/thread_abc123/runs \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: assistants=v1"
python: |
from openai import OpenAI
client = OpenAI()
runs = client.beta.threads.runs.list(
"thread_abc123"
)
print(runs)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const runs = await openai.beta.threads.runs.list(
"thread_abc123"
);
console.log(runs);
}
main();
response: |
{
"object": "list",
"data": [
{
"id": "run_abc123",
"object": "thread.run",
"created_at": 1699075072,
"assistant_id": "asst_abc123",
"thread_id": "thread_abc123",
"status": "completed",
"started_at": 1699075072,
"expires_at": null,
"cancelled_at": null,
"failed_at": null,
"completed_at": 1699075073,
"last_error": null,
"model": "gpt-3.5-turbo",
"instructions": null,
"tools": [
{
"type": "code_interpreter"
}
],
"file_ids": [
"file-abc123",
"file-abc456"
],
"metadata": {},
"usage": {
"prompt_tokens": 123,
"completion_tokens": 456,
"total_tokens": 579
}
},
{
"id": "run_abc456",
"object": "thread.run",
"created_at": 1699063290,
"assistant_id": "asst_abc123",
"thread_id": "thread_abc123",
"status": "completed",
"started_at": 1699063290,
"expires_at": null,
"cancelled_at": null,
"failed_at": null,
"completed_at": 1699063291,
"last_error": null,
"model": "gpt-3.5-turbo",
"instructions": null,
"tools": [
{
"type": "code_interpreter"
}
],
"file_ids": [
"file-abc123",
"file-abc456"
],
"metadata": {},
"usage": {
"prompt_tokens": 123,
"completion_tokens": 456,
"total_tokens": 579
}
}
],
"first_id": "run_abc123",
"last_id": "run_abc456",
"has_more": false
}
post:
operationId: createRun
tags:
- Threads
summary: OpenAI Create a run.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the thread to run.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRunRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RunObject'
x-oaiMeta:
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/threads-openapi-original.yml