openapi: 3.0.0
info:
title: OpenAI Assistants API
description: The Assistants API allows you to build AI assistants within your own applications. An Assistant has instructions and can leverage models, tools, and knowledge to respond to user queries. The Assistants API currently supports three types of tools - Code Interpreter, Retrieval, and Function calling. In the future, we plan to release more OpenAI-built tools, and allow you to provide your own tools on our platform.
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
security:
- ApiKeyAuth: []
tags:
- name: Assistants
description: Build Assistants that can call models and use tools.
paths:
/assistants:
get:
operationId: listAssistants
tags:
- Assistants
summary: OpenAI Returns a list of assistants.
parameters:
- 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/ListAssistantsResponse'
x-oaiMeta:
name: List assistants
group: assistants
beta: true
returns: A list of [assistant](/docs/api-reference/assistants/object) objects.
examples:
request:
curl: "curl \"https://api.openai.com/v1/assistants?order=desc&limit=20\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\"\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistants = client.beta.assistants.list(\n order=\"desc\",\n limit=\"20\",\n)\nprint(my_assistants.data)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistants = await openai.beta.assistants.list({\n order: \"desc\",\n limit: \"20\",\n });\n\n console.log(myAssistants.data);\n}\n\nmain();"
response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1698982736,\n \"name\": \"Coding Tutor\",\n \"description\": null,\n \"model\": \"gpt-4\",\n \"instructions\": \"You are a helpful assistant designed to make me better at coding!\",\n \"tools\": [],\n \"file_ids\": [],\n \"metadata\": {}\n },\n {\n \"id\": \"asst_abc456\",\n \"object\": \"assistant\",\n \"created_at\": 1698982718,\n \"name\": \"My Assistant\",\n \"description\": null,\n \"model\": \"gpt-4\",\n \"instructions\": \"You are a helpful assistant designed to make me better at coding!\",\n \"tools\": [],\n \"file_ids\": [],\n \"metadata\": {}\n },\n {\n \"id\": \"asst_abc789\",\n \"object\": \"assistant\",\n \"created_at\": 1698982643,\n \"name\": null,\n \"description\": null,\n \"model\": \"gpt-4\",\n \"instructions\": null,\n \"tools\": [],\n \"file_ids\": [],\n \"metadata\": {}\n }\n ],\n \"first_id\": \"asst_abc123\",\n \"last_id\": \"asst_abc789\",\n \"has_more\": false\n}\n"
post:
operationId: createAssistant
tags:
- Assistants
summary: OpenAI Create an assistant with a model and instructions.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAssistantRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantObject'
x-oaiMeta:
name: Create assistant
group: assistants
beta: true
returns: An [assistant](/docs/api-reference/assistants/object) object.
examples:
- title: Code Interpreter
request:
curl: "curl \"https://api.openai.com/v1/assistants\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"instructions\": \"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n \"name\": \"Math Tutor\",\n \"tools\": [{\"type\": \"code_interpreter\"}],\n \"model\": \"gpt-4\"\n }'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistant = client.beta.assistants.create(\n instructions=\"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n name=\"Math Tutor\",\n tools=[{\"type\": \"code_interpreter\"}],\n model=\"gpt-4\",\n)\nprint(my_assistant)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistant = await openai.beta.assistants.create({\n instructions:\n \"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n name: \"Math Tutor\",\n tools: [{ type: \"code_interpreter\" }],\n model: \"gpt-4\",\n });\n\n console.log(myAssistant);\n}\n\nmain();"
response: "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1698984975,\n \"name\": \"Math Tutor\",\n \"description\": null,\n \"model\": \"gpt-4\",\n \"instructions\": \"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n \"tools\": [\n {\n \"type\": \"code_interpreter\"\n }\n ],\n \"file_ids\": [],\n \"metadata\": {}\n}\n"
- title: Files
request:
curl: "curl https://api.openai.com/v1/assistants \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n \"tools\": [{\"type\": \"retrieval\"}],\n \"model\": \"gpt-4\",\n \"file_ids\": [\"file-abc123\"]\n }'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistant = client.beta.assistants.create(\n instructions=\"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n name=\"HR Helper\",\n tools=[{\"type\": \"retrieval\"}],\n model=\"gpt-4\",\n file_ids=[\"file-abc123\"],\n)\nprint(my_assistant)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistant = await openai.beta.assistants.create({\n instructions:\n \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n name: \"HR Helper\",\n tools: [{ type: \"retrieval\" }],\n model: \"gpt-4\",\n file_ids: [\"file-abc123\"],\n });\n\n console.log(myAssistant);\n}\n\nmain();"
response: "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1699009403,\n \"name\": \"HR Helper\",\n \"description\": null,\n \"model\": \"gpt-4\",\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n \"tools\": [\n {\n \"type\": \"retrieval\"\n }\n ],\n \"file_ids\": [\n \"file-abc123\"\n ],\n \"metadata\": {}\n}\n"
/assistants/{assistant_id}:
get:
operationId: getAssistant
tags:
- Assistants
summary: OpenAI Retrieves an assistant.
parameters:
- in: path
name: assistant_id
required: true
schema:
type: string
description: The ID of the assistant to retrieve.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantObject'
x-oaiMeta:
name: Retrieve assistant
group: assistants
beta: true
returns: The [assistant](/docs/api-reference/assistants/object) object matching the specified ID.
examples:
request:
curl: "curl https://api.openai.com/v1/assistants/asst_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\"\n"
python: 'from openai import OpenAI
client = OpenAI()
my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)
'
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistant = await openai.beta.assistants.retrieve(\n \"asst_abc123\"\n );\n\n console.log(myAssistant);\n}\n\nmain();"
response: "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1699009709,\n \"name\": \"HR Helper\",\n \"description\": null,\n \"model\": \"gpt-4\",\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n \"tools\": [\n {\n \"type\": \"retrieval\"\n }\n ],\n \"file_ids\": [\n \"file-abc123\"\n ],\n \"metadata\": {}\n}\n"
post:
operationId: modifyAssistant
tags:
- Assistants
summary: OpenAI Modifies an assistant.
parameters:
- in: path
name: assistant_id
required: true
schema:
type: string
description: The ID of the assistant to modify.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyAssistantRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantObject'
x-oaiMeta:
name: Modify assistant
group: assistants
beta: true
returns: The modified [assistant](/docs/api-reference/assistants/object) object.
examples:
request:
curl: "curl https://api.openai.com/v1/assistants/asst_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n \"tools\": [{\"type\": \"retrieval\"}],\n \"model\": \"gpt-4\",\n \"file_ids\": [\"file-abc123\", \"file-abc456\"]\n }'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nmy_updated_assistant = client.beta.assistants.update(\n \"asst_abc123\",\n instructions=\"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n name=\"HR Helper\",\n tools=[{\"type\": \"retrieval\"}],\n model=\"gpt-4\",\n file_ids=[\"file-abc123\", \"file-abc456\"],\n)\n\nprint(my_updated_assistant)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myUpdatedAssistant = await openai.beta.assistants.update(\n \"asst_abc123\",\n {\n instructions:\n \"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n name: \"HR Helper\",\n tools: [{ type: \"retrieval\" }],\n model: \"gpt-4\",\n file_ids: [\n \"file-abc123\",\n \"file-abc456\",\n ],\n }\n );\n\n console.log(myUpdatedAssistant);\n}\n\nmain();"
response: "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1699009709,\n \"name\": \"HR Helper\",\n \"description\": null,\n \"model\": \"gpt-4\",\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n \"tools\": [\n {\n \"type\": \"retrieval\"\n }\n ],\n \"file_ids\": [\n \"file-abc123\",\n \"file-abc456\"\n ],\n \"metadata\": {}\n}\n"
delete:
operationId: deleteAssistant
tags:
- Assistants
summary: OpenAI Delete an assistant.
parameters:
- in: path
name: assistant_id
required: true
schema:
type: string
description: The ID of the assistant to delete.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAssistantResponse'
x-oaiMeta:
name: Delete assistant
group: assistants
beta: true
returns: Deletion status
examples:
request:
curl: "curl https://api.openai.com/v1/assistants/asst_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -X DELETE\n"
python: 'from openai import OpenAI
client = OpenAI()
response = client.beta.assistants.delete("asst_abc123")
print(response)
'
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.beta.assistants.del(\"asst_abc123\");\n\n console.log(response);\n}\nmain();"
response: "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant.deleted\",\n \"deleted\": true\n}\n"
/assistants/{assistant_id}/files:
get:
operationId: listAssistantFiles
tags:
- Assistants
summary: OpenAI Returns a list of assistant files.
parameters:
- name: assistant_id
in: path
description: The ID of the assistant the file belongs to.
required: true
schema:
type: string
- 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/ListAssistantFilesResponse'
x-oaiMeta:
name: List assistant files
group: assistants
beta: true
returns: A list of [assistant file](/docs/api-reference/assistants/file-object) objects.
examples:
request:
curl: "curl https://api.openai.com/v1/assistants/asst_abc123/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v1\"\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nassistant_files = client.beta.assistants.files.list(\n assistant_id=\"asst_abc123\"\n)\nprint(assistant_files)\n"
node.js: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nasync function main() {\n const assistantFiles = await openai.beta.assistants.files.list(\n \"asst_abc123\"\n );\n console.log(assistantFiles);\n}\n\nmain();\n"
response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"file-abc123\",\n \"object\": \"assistant.file\",\n \"created_at\": 1699060412,\n \"assistant_id\": \"asst_abc123\"\n },\n {\n \"id\": \"file-abc456\",\n \"object\": \"assistant.file\",\n \"created_at\": 1699060412,\n \"assistant_id\": \"asst_abc123\"\n }\n ],\n \"first_id\": \"file-abc123\",\n \"last_id\": \"file-abc456\",\n \"has_more\": false\n}\n"
post:
operationId: createAssistantFile
tags:
- Assistants
summary: OpenAI Create an assistant file by attaching a [File](/docs/api-reference/files) to an [assistant](/docs/api-reference/assistants).
parameters:
- in: path
name: assistant_id
required: true
schema:
type: string
example: file-abc123
description: 'The ID of the assistant for which to create a File.
'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAssistantFileRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantFileObject'
x-oaiMeta:
name: Create assistant file
group: assistants
beta: true
returns: An [assistant file](/docs/api-reference/assistants/file-object) object.
examples:
request:
curl: "curl https://api.openai.com/v1/assistants/asst_abc123/files \\\n -H 'Authorization: Bearer $OPENAI_API_KEY\"' \\\n -H 'Content-Type: application/json' \\\n -H 'OpenAI-Beta: assistants=v1' \\\n -d '{\n \"file_id\": \"file-abc123\"\n }'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nassistant_file = client.beta.assistants.files.create(\n assistant_id=\"asst_abc123\",\n file_id=\"file-abc123\"\n)\nprint(assistant_file)\n"
node.js: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistantFile = await openai.beta.assistants.files.create(\n \"asst_abc123\",\n {\n file_id: \"file-abc123\"\n }\n );\n console.log(myAssistantFile);\n}\n\nmain();\n"
response: "{\n \"id\": \"file-abc123\",\n \"object\": \"assistant.file\",\n \"created_at\": 1699055364,\n \"assistant_id\": \"asst_abc123\"\n}\n"
/assistants/{assistant_id}/files/{file_id}:
get:
operationId: getAssistantFile
tags:
- Assistants
summary: OpenAI Retrieves an AssistantFile.
parameters:
- in: path
name: assistant_id
required: true
schema:
type: string
description: The ID of the assistant who the file belongs to.
- in: path
name: file_id
required: true
schema:
type: string
description: The ID of the file we're getting.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssistantFileObject'
x-oaiMeta:
name: Retrieve assistant file
group: assistants
beta: true
returns: The [assistant file](/docs/api-reference/assistants/file-object) object matching the specified ID.
examples:
request:
curl: "curl https://api.openai.com/v1/assistants/asst_abc123/files/file-abc123 \\\n -H 'Authorization: Bearer $OPENAI_API_KEY\"' \\\n -H 'Content-Type: application/json' \\\n -H 'OpenAI-Beta: assistants=v1'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nassistant_file = client.beta.assistants.files.retrieve(\n assistant_id=\"asst_abc123\",\n file_id=\"file-abc123\"\n)\nprint(assistant_file)\n"
node.js: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistantFile = await openai.beta.assistants.files.retrieve(\n \"asst_abc123\",\n \"file-abc123\"\n );\n console.log(myAssistantFile);\n}\n\nmain();\n"
response: "{\n \"id\": \"file-abc123\",\n \"object\": \"assistant.file\",\n \"created_at\": 1699055364,\n \"assistant_id\": \"asst_abc123\"\n}\n"
delete:
operationId: deleteAssistantFile
tags:
- Assistants
summary: OpenAI Delete an assistant file.
parameters:
- in: path
name: assistant_id
required: true
schema:
type: string
description: The ID of the assistant that the file belongs to.
- in: path
name: file_id
required: true
schema:
type: string
description: The ID of the file to delete.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAssistantFileResponse'
x-oaiMeta:
name: Delete assistant file
group: assistants
beta: true
returns: Deletion status
examples:
request:
curl: "curl https://api.openai.com/v1/assistants/asst_abc123/files/file-abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -X DELETE\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\ndeleted_assistant_file = client.beta.assistants.files.delete(\n assistant_id=\"asst_abc123\",\n file_id=\"file-abc123\"\n)\nprint(deleted_assistant_file)\n"
node.js: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nasync function main() {\n const deletedAssistantFile = await openai.beta.assistants.files.del(\n \"asst_abc123\",\n \"file-abc123\"\n );\n console.log(deletedAssistantFile);\n}\n\nmain();\n"
response: "{\n id: \"file-abc123\",\n object: \"assistant.file.deleted\",\n deleted: true\n}\n"
/threads:
post:
operationId: createThread
tags:
- Assistants
summary: 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
examples:
- title: Empty
request:
curl: "curl https://api.openai.com/v1/threads \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\" \\\n -d ''\n"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ.get(\"OPENAI_API_KEY\"), # This is the default and can be omitted\n)\nthread = client.beta.threads.create()\nprint(thread.id)"
javascript: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const emptyThread = await openai.beta.threads.create();\n\n console.log(emptyThread);\n}\n\nmain();"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted\n});\n\nconst thread = await client.beta.threads.create();\n\nconsole.log(thread.id);"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tthread, err := client.Beta.Threads.New(context.TODO(), openai.BetaThreadNewParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", thread.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.beta.threads.Thread;\nimport com.openai.models.beta.threads.ThreadCreateParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n Thread thread = client.beta().threads().create();\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
thread = openai.beta.threads.create
puts(thread)'
response: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread\",\n \"created_at\": 1699012949,\n \"metadata\": {},\n \"tool_resources\": {}\n}\n"
- title: Messages
request:
curl: "curl https://api.openai.com/v1/threads \\\n-H \"Content-Type: application/json\" \\\n-H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n-H \"OpenAI-Beta: assistants=v2\" \\\n-d '{\n \"messages\": [{\n \"role\": \"user\",\n \"content\": \"Hello, what is AI?\"\n }, {\n \"role\": \"user\",\n \"content\": \"How does AI work? Explain it in simple terms.\"\n }]\n }'\n"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ.get(\"OPENAI_API_KEY\"), # This is the default and can be omitted\n)\nthread = client.beta.threads.create()\nprint(thread.id)"
javascript: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const messageThread = await openai.beta.threads.create({\n messages: [\n {\n role: \"user\",\n content: \"Hello, what is AI?\"\n },\n {\n role: \"user\",\n content: \"How does AI work? Explain it in simple terms.\",\n },\n ],\n });\n\n console.log(messageThread);\n}\n\nmain();"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted\n});\n\nconst thread = await client.beta.threads.create();\n\nconsole.log(thread.id);"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tthread, err := client.Beta.Threads.New(context.TODO(), openai.BetaThreadNewParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", thread.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.beta.threads.Thread;\nimport com.openai.models.beta.threads.ThreadCreateParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n Thread thread = client.beta().threads().create();\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
thread = openai.beta.threads.create
puts(thread)'
response: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread\",\n \"created_at\": 1699014083,\n \"metadata\": {},\n \"tool_resources\": {}\n}\n"
/threads/runs:
post:
operationId: createThreadAndRun
tags:
- Assistants
summary: 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
examples:
- title: Default
request:
curl: "curl https://api.openai.com/v1/threads/runs \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v2\" \\\n -d '{\n \"assistant_id\": \"asst_abc123\",\n \"thread\": {\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Explain deep learning to a 5 year old.\"}\n ]\n }\n }'\n"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.environ.get(\"OPENAI_API_KEY\"), # This is the default and can be omitted\n)\nfor thread in client.beta.threads.create_and_run(\n assistant_id=\"assistant_id\",\n):\n print(thread)"
javascript: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const run = await openai.beta.threads.createAndRun({\n assistant_id: \"asst_abc123\",\n thread: {\n messages: [\n { role: \"user\", content: \"Explain deep learning to a 5 year old.\" },\n ],\n },\n });\n\n console.log(run);\n}\n\nmain();\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted\n});\n\nconst run = await client.beta.threads.createAndRun({ assistant_id: 'assistant_id' });\n\nconsole.log(run.id);"
go: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go\"\n\t\"github.com/openai/openai-go/option\"\n)\n\nfunc main() {\n\tclient := openai.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\trun, err := client.Beta.Threads.NewAndRun(context.TODO(), openai.BetaThreadNewAndRunParams{\n\t\tAssistantID: \"assistant_id\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", run.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.beta.threads.ThreadCreateAndRunParams;\nimport com.openai.models.beta.threads.runs.Run;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n ThreadCreateAndRunParams params = ThreadCreateAndRunParams.builder()\n .assistantId(\"assistant_id\")\n .build();\n Run run = clien
# --- truncated at 32 KB (244 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-assistants-api-openapi.yml