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.
openapi: 3.0.0
info:
title: OpenAI Assistants
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
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" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1"
python: |
from openai import OpenAI
client = OpenAI()
my_assistants = client.beta.assistants.list(
order="desc",
limit="20",
)
print(my_assistants.data)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const myAssistants = await openai.beta.assistants.list({
order: "desc",
limit: "20",
});
console.log(myAssistants.data);
}
main();
response: |
{
"object": "list",
"data": [
{
"id": "asst_abc123",
"object": "assistant",
"created_at": 1698982736,
"name": "Coding Tutor",
"description": null,
"model": "gpt-4",
"instructions": "You are a helpful assistant designed to make me better at coding!",
"tools": [],
"file_ids": [],
"metadata": {}
},
{
"id": "asst_abc456",
"object": "assistant",
"created_at": 1698982718,
"name": "My Assistant",
"description": null,
"model": "gpt-4",
"instructions": "You are a helpful assistant designed to make me better at coding!",
"tools": [],
"file_ids": [],
"metadata": {}
},
{
"id": "asst_abc789",
"object": "assistant",
"created_at": 1698982643,
"name": null,
"description": null,
"model": "gpt-4",
"instructions": null,
"tools": [],
"file_ids": [],
"metadata": {}
}
],
"first_id": "asst_abc123",
"last_id": "asst_abc789",
"has_more": false
}
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" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1" \
-d '{
"instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
"name": "Math Tutor",
"tools": [{"type": "code_interpreter"}],
"model": "gpt-4"
}'
python: |
from openai import OpenAI
client = OpenAI()
my_assistant = client.beta.assistants.create(
instructions="You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
name="Math Tutor",
tools=[{"type": "code_interpreter"}],
model="gpt-4",
)
print(my_assistant)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const myAssistant = await openai.beta.assistants.create({
instructions:
"You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
name: "Math Tutor",
tools: [{ type: "code_interpreter" }],
model: "gpt-4",
});
console.log(myAssistant);
}
main();
response: |
{
"id": "asst_abc123",
"object": "assistant",
"created_at": 1698984975,
"name": "Math Tutor",
"description": null,
"model": "gpt-4",
"instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
"tools": [
{
"type": "code_interpreter"
}
],
"file_ids": [],
"metadata": {}
}
- title: Files
request:
curl: |
curl https://api.openai.com/v1/assistants \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1" \
-d '{
"instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
"tools": [{"type": "retrieval"}],
"model": "gpt-4",
"file_ids": ["file-abc123"]
}'
python: |
from openai import OpenAI
client = OpenAI()
my_assistant = client.beta.assistants.create(
instructions="You are an HR bot, and you have access to files to answer employee questions about company policies.",
name="HR Helper",
tools=[{"type": "retrieval"}],
model="gpt-4",
file_ids=["file-abc123"],
)
print(my_assistant)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const myAssistant = await openai.beta.assistants.create({
instructions:
"You are an HR bot, and you have access to files to answer employee questions about company policies.",
name: "HR Helper",
tools: [{ type: "retrieval" }],
model: "gpt-4",
file_ids: ["file-abc123"],
});
console.log(myAssistant);
}
main();
response: |
{
"id": "asst_abc123",
"object": "assistant",
"created_at": 1699009403,
"name": "HR Helper",
"description": null,
"model": "gpt-4",
"instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
"tools": [
{
"type": "retrieval"
}
],
"file_ids": [
"file-abc123"
],
"metadata": {}
}
/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 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1"
python: |
from openai import OpenAI
client = OpenAI()
my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const myAssistant = await openai.beta.assistants.retrieve(
"asst_abc123"
);
console.log(myAssistant);
}
main();
response: |
{
"id": "asst_abc123",
"object": "assistant",
"created_at": 1699009709,
"name": "HR Helper",
"description": null,
"model": "gpt-4",
"instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
"tools": [
{
"type": "retrieval"
}
],
"file_ids": [
"file-abc123"
],
"metadata": {}
}
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 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: assistants=v1" \
-d '{
"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.",
"tools": [{"type": "retrieval"}],
"model": "gpt-4",
"file_ids": ["file-abc123", "file-abc456"]
}'
python: |
from openai import OpenAI
client = OpenAI()
my_updated_assistant = client.beta.assistants.update(
"asst_abc123",
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.",
name="HR Helper",
tools=[{"type": "retrieval"}],
model="gpt-4",
file_ids=["file-abc123", "file-abc456"],
)
print(my_updated_assistant)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const myUpdatedAssistant = await openai.beta.assistants.update(
"asst_abc123",
{
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.",
name: "HR Helper",
tools: [{ type: "retrieval" }],
model: "gpt-4",
file_ids: [
"file-abc123",
"file-abc456",
],
}
);
console.log(myUpdatedAssistant);
}
main();
response: |
{
"id": "asst_abc123",
"object": "assistant",
"created_at": 1699009709,
"name": "HR Helper",
"description": null,
"model": "gpt-4",
"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.",
"tools": [
{
"type": "retrieval"
}
],
"file_ids": [
"file-abc123",
"file-abc456"
],
"metadata": {}
}
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 \
-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.assistants.delete("asst_abc123")
print(response)
node.js: |-
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const response = await openai.beta.assistants.del("asst_abc123");
console.log(response);
}
main();
response: |
{
"id": "asst_abc123",
"object": "assistant.deleted",
"deleted": true
}
/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 \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: assistants=v1"
python: |
from openai import OpenAI
client = OpenAI()
assistant_files = client.beta.assistants.files.list(
assistant_id="asst_abc123"
)
print(assistant_files)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const assistantFiles = await openai.beta.assistants.files.list(
"asst_abc123"
);
console.log(assistantFiles);
}
main();
response: |
{
"object": "list",
"data": [
{
"id": "file-abc123",
"object": "assistant.file",
"created_at": 1699060412,
"assistant_id": "asst_abc123"
},
{
"id": "file-abc456",
"object": "assistant.file",
"created_at": 1699060412,
"assistant_id": "asst_abc123"
}
],
"first_id": "file-abc123",
"last_id": "file-abc456",
"has_more": false
}
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 \
-H 'Authorization: Bearer $OPENAI_API_KEY"' \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: assistants=v1' \
-d '{
"file_id": "file-abc123"
}'
python: |
from openai import OpenAI
client = OpenAI()
assistant_file = client.beta.assistants.files.create(
assistant_id="asst_abc123",
file_id="file-abc123"
)
print(assistant_file)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const myAssistantFile = await openai.beta.assistants.files.create(
"asst_abc123",
{
file_id: "file-abc123"
}
);
console.log(myAssistantFile);
}
main();
response: |
{
"id": "file-abc123",
"object": "assistant.file",
"created_at": 1699055364,
"assistant_id": "asst_abc123"
}
/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
\
-H 'Authorization: Bearer $OPENAI_API_KEY"' \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: assistants=v1'
python: |
from openai import OpenAI
client = OpenAI()
assistant_file = client.beta.assistants.files.retrieve(
assistant_id="asst_abc123",
file_id="file-abc123"
)
print(assistant_file)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const myAssistantFile = await openai.beta.assistants.files.retrieve(
"asst_abc123",
"file-abc123"
);
console.log(myAssistantFile);
}
main();
response: |
{
"id": "file-abc123",
"object": "assistant.file",
"created_at": 1699055364,
"assistant_id": "asst_abc123"
}
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
\
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: assistants=v1" \
-X DELETE
python: |
from openai import OpenAI
client = OpenAI()
deleted_assistant_file = client.beta.assistants.files.delete(
assistant_id="asst_abc123",
file_id="file-abc123"
)
print(deleted_assistant_file)
node.js: |
import OpenAI from "openai";
const openai = new OpenAI();
async function main() {
const deletedAssistantFile = await openai.beta.assistants.files.del(
"asst_abc123",
"file-abc123"
);
console.log(deletedAssistantFile);
}
main();
response: |
{
id: "file-abc123",
object: "assistant.file.deleted",
deleted: true
}
components:
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
schemas:
FunctionObject:
type: object
properties:
description:
type: string
description: >-
A description of what the function does, used by the model to choose
when and how to call the function.
name:
type: string
description: >-
The name of the function to be called. Must be a-z, A-Z, 0-9, or
contain underscores and dashes, with a maximum length of 64.
parameters:
$ref: '#/components/schemas/FunctionParameters'
required:
- name
FunctionParameters:
type: object
description: >-
The parameters the functions accepts, described as a JSON Schema object.
See the [guide](/docs/guides/text-generation/function-calling) for
examples, and the [JSON Schema
reference](https://json-schema.org/understanding-json-schema/) for
documentation about the format.
Omitting `parameters` defines a function with an empty parameter list.
additionalProperties: true
AssistantToolsCode:
type: object
title: Code interpreter tool
properties:
type:
type: string
description: 'The type of tool being defined: `code_interpreter`'
enum:
- code_interpreter
required:
- type
AssistantToolsRetrieval:
type: object
title: Retrieval tool
properties:
type:
type: string
description: 'The type of tool being defined: `retrieval`'
enum:
- retrieval
required:
- type
AssistantToolsFunction:
type: object
title: Function tool
properties:
type:
type: string
description: 'The type of tool being defined: `function`'
enum:
- function
function:
$ref: '#/components/schemas/FunctionObject'
required:
- type
- function
CreateAssistantFileRequest:
type: object
additionalProperties: false
properties:
file_id:
description: >-
A [File](/docs/api-reference/files) ID (with `purpose="assistants"`)
that the assistant should use. Useful for tools like `retrieval` and
`code_interpreter` that can access files.
type: string
required:
- file_id
ModifyAssistantRequest:
type: object
additionalProperties: false
properties:
model:
description: model_description
anyOf:
- type: string
name:
description: assistant_name_param_description
type: string
nullable: true
maxLength: 256
description:
description: assistant_description_param_description
type: string
nullable: true
maxLength: 512
instructions:
description: assistant_instructions_param_description
type: string
nullable: true
maxLength: 32768
tools:
description: assistant_tools_param_description
default: []
type: array
maxItems: 128
items:
oneOf:
- $ref: '#/components/schemas/AssistantToolsCode'
- $ref: '#/components/schemas/AssistantToolsRetrieva
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/assistants-openapi-original.yml