openapi: 3.0.0 info: title: OpenAI Assistants Threads 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: Threads paths: /threads/{thread_id}/messages/{message_id}/files: get: operationId: listMessageFiles tags: - Threads summary: OpenAI Returns a list of message files. parameters: - name: thread_id in: path description: The ID of the thread that the message and files belong to. required: true schema: type: string - name: message_id in: path description: The ID of the message that the files 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/ListMessageFilesResponse' x-oaiMeta: name: List message files group: threads beta: true returns: A list of [message file](/docs/api-reference/messages/file-object) objects. examples: request: curl: "curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_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\nmessage_files = client.beta.threads.messages.files.list(\n thread_id=\"thread_abc123\",\n message_id=\"msg_abc123\"\n)\nprint(message_files)\n" node.js: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nasync function main() {\n const messageFiles = await openai.beta.threads.messages.files.list(\n \"thread_abc123\",\n \"msg_abc123\"\n );\n console.log(messageFiles);\n}\n\nmain();\n" response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"file-abc123\",\n \"object\": \"thread.message.file\",\n \"created_at\": 1699061776,\n \"message_id\": \"msg_abc123\"\n },\n {\n \"id\": \"file-abc123\",\n \"object\": \"thread.message.file\",\n \"created_at\": 1699061776,\n \"message_id\": \"msg_abc123\"\n }\n ],\n \"first_id\": \"file-abc123\",\n \"last_id\": \"file-abc123\",\n \"has_more\": false\n}\n" /threads/{thread_id}/messages/{message_id}/files/{file_id}: get: operationId: getMessageFile tags: - Threads summary: OpenAI Retrieves a message file. parameters: - in: path name: thread_id required: true schema: type: string example: thread_abc123 description: The ID of the thread to which the message and File belong. - in: path name: message_id required: true schema: type: string example: msg_abc123 description: The ID of the message the file belongs to. - in: path name: file_id required: true schema: type: string example: file-abc123 description: The ID of the file being retrieved. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/MessageFileObject' x-oaiMeta: name: Retrieve message file group: threads beta: true returns: The [message file](/docs/api-reference/messages/file-object) object. examples: request: curl: "curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_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\nmessage_files = client.beta.threads.messages.files.retrieve(\n thread_id=\"thread_abc123\",\n message_id=\"msg_abc123\",\n file_id=\"file-abc123\"\n)\nprint(message_files)\n" node.js: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nasync function main() {\n const messageFile = await openai.beta.threads.messages.files.retrieve(\n \"thread_abc123\",\n \"msg_abc123\",\n \"file-abc123\"\n );\n console.log(messageFile);\n}\n\nmain();\n" response: "{\n \"id\": \"file-abc123\",\n \"object\": \"thread.message.file\",\n \"created_at\": 1699061776,\n \"message_id\": \"msg_abc123\"\n}\n" /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 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d ''\n" python: 'from openai import OpenAI client = OpenAI() empty_thread = client.beta.threads.create() print(empty_thread) ' node.js: "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();" response: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread\",\n \"created_at\": 1699012949,\n \"metadata\": {}\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=v1\" \\\n-d '{\n \"messages\": [{\n \"role\": \"user\",\n \"content\": \"Hello, what is AI?\",\n \"file_ids\": [\"file-abc123\"]\n }, {\n \"role\": \"user\",\n \"content\": \"How does AI work? Explain it in simple terms.\"\n }]\n }'\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nmessage_thread = client.beta.threads.create(\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"Hello, what is AI?\",\n \"file_ids\": [\"file-abc123\"],\n },\n {\n \"role\": \"user\",\n \"content\": \"How does AI work? Explain it in simple terms.\"\n },\n ]\n)\n\nprint(message_thread)\n" node.js: "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 file_ids: [\"file-abc123\"],\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();" response: "{\n id: 'thread_abc123',\n object: 'thread',\n created_at: 1699014083,\n metadata: {}\n}\n" /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 \\\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_thread = client.beta.threads.retrieve("thread_abc123") print(my_thread) ' node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myThread = await openai.beta.threads.retrieve(\n \"thread_abc123\"\n );\n\n console.log(myThread);\n}\n\nmain();" response: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread\",\n \"created_at\": 1699014083,\n \"metadata\": {}\n}\n" 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 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"metadata\": {\n \"modified\": \"true\",\n \"user\": \"abc123\"\n }\n }'\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nmy_updated_thread = client.beta.threads.update(\n \"thread_abc123\",\n metadata={\n \"modified\": \"true\",\n \"user\": \"abc123\"\n }\n)\nprint(my_updated_thread)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const updatedThread = await openai.beta.threads.update(\n \"thread_abc123\",\n {\n metadata: { modified: \"true\", user: \"abc123\" },\n }\n );\n\n console.log(updatedThread);\n}\n\nmain();" response: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread\",\n \"created_at\": 1699014083,\n \"metadata\": {\n \"modified\": \"true\",\n \"user\": \"abc123\"\n }\n}\n" 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 \\\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.threads.delete("thread_abc123") print(response) ' node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.beta.threads.del(\"thread_abc123\");\n\n console.log(response);\n}\nmain();" response: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread.deleted\",\n \"deleted\": true\n}\n" /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 \\\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() thread_messages = client.beta.threads.messages.list("thread_abc123") print(thread_messages.data) ' node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const threadMessages = await openai.beta.threads.messages.list(\n \"thread_abc123\"\n );\n\n console.log(threadMessages.data);\n}\n\nmain();" response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"msg_abc123\",\n \"object\": \"thread.message\",\n \"created_at\": 1699016383,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"How does AI work? Explain it in simple terms.\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [],\n \"assistant_id\": null,\n \"run_id\": null,\n \"metadata\": {}\n },\n {\n \"id\": \"msg_abc456\",\n \"object\": \"thread.message\",\n \"created_at\": 1699016383,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"Hello, what is AI?\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [\n \"file-abc123\"\n ],\n \"assistant_id\": null,\n \"run_id\": null,\n \"metadata\": {}\n }\n ],\n \"first_id\": \"msg_abc123\",\n \"last_id\": \"msg_abc456\",\n \"has_more\": false\n}\n" 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 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"role\": \"user\",\n \"content\": \"How does AI work? Explain it in simple terms.\"\n }'\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nthread_message = client.beta.threads.messages.create(\n \"thread_abc123\",\n role=\"user\",\n content=\"How does AI work? Explain it in simple terms.\",\n)\nprint(thread_message)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const threadMessages = await openai.beta.threads.messages.create(\n \"thread_abc123\",\n { role: \"user\", content: \"How does AI work? Explain it in simple terms.\" }\n );\n\n console.log(threadMessages);\n}\n\nmain();" response: "{\n \"id\": \"msg_abc123\",\n \"object\": \"thread.message\",\n \"created_at\": 1699017614,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"How does AI work? Explain it in simple terms.\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [],\n \"assistant_id\": null,\n \"run_id\": null,\n \"metadata\": {}\n}\n" /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 \\\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\nmessage = client.beta.threads.messages.retrieve(\n message_id=\"msg_abc123\",\n thread_id=\"thread_abc123\",\n)\nprint(message)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const message = await openai.beta.threads.messages.retrieve(\n \"thread_abc123\",\n \"msg_abc123\"\n );\n\n console.log(message);\n}\n\nmain();" response: "{\n \"id\": \"msg_abc123\",\n \"object\": \"thread.message\",\n \"created_at\": 1699017614,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"How does AI work? Explain it in simple terms.\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [],\n \"assistant_id\": null,\n \"run_id\": null,\n \"metadata\": {}\n}\n" 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 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"metadata\": {\n \"modified\": \"true\",\n \"user\": \"abc123\"\n }\n }'\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nmessage = client.beta.threads.messages.update(\n message_id=\"msg_abc12\",\n thread_id=\"thread_abc123\",\n metadata={\n \"modified\": \"true\",\n \"user\": \"abc123\",\n },\n)\nprint(message)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const message = await openai.beta.threads.messages.update(\n \"thread_abc123\",\n \"msg_abc123\",\n {\n metadata: {\n modified: \"true\",\n user: \"abc123\",\n },\n }\n }'" response: "{\n \"id\": \"msg_abc123\",\n \"object\": \"thread.message\",\n \"created_at\": 1699017614,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"How does AI work? Explain it in simple terms.\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [],\n \"assistant_id\": null,\n \"run_id\": null,\n \"metadata\": {\n \"modified\": \"true\",\n \"user\": \"abc123\"\n }\n}\n" /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 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\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: "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.beta.threads.create_and_run(\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" node.js: "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" response: "{\n \"id\": \"run_abc123\",\n \"object\": \"thread.run\",\n \"created_at\": 1699076792,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"queued\",\n \"started_at\": null,\n \"expires_at\": 1699077392,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": null,\n \"last_error\": null,\n \"model\": \"gpt-4\",\n \"instructions\": \"You are a helpful assistant.\",\n \"tools\": [],\n \"file_ids\": [],\n \"metadata\": {},\n \"usage\": null\n}\n" /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 \\\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\nruns = client.beta.threads.runs.list(\n \"thread_abc123\"\n)\nprint(runs)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const runs = await openai.beta.threads.runs.list(\n \"thread_abc123\"\n );\n\n console.log(runs);\n}\n\nmain();\n" response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"run_abc123\",\n \"object\": \"thread.run\",\n \"created_at\": 1699075072,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"completed\",\n \"started_at\": 1699075072,\n \"expires_at\": null,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": 1699075073,\n \"last_error\": null,\n \"model\": \"gpt-3.5-turbo\",\n \"instructions\": null,\n \"tools\": [\n {\n \"type\": \"code_interpreter\"\n }\n ],\n \"file_ids\": [\n \"file-abc123\",\n \"file-abc456\"\n ],\n \"metadata\": {},\n \"usage\": {\n \"prompt_tokens\": 123,\n \"completion_tokens\": 456,\n \"total_tokens\": 579\n }\n },\n {\n \"id\": \"run_abc456\",\n \"object\": \"thread.run\",\n \"created_at\": 1699063290,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"completed\",\n \"started_at\": 1699063290,\n \"expires_at\": null,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": 1699063291,\n \"last_error\": null,\n \"model\": \"gpt-3.5-turbo\",\n \"instructions\": null,\n \"tools\": [\n {\n \"type\": \"code_interpreter\"\n }\n ],\n \"file_ids\": [\n \"file-abc123\",\n \"file-abc456\"\n ],\n \"metadata\": {},\n \"usage\": {\n \"prompt_tokens\": 123,\n \"completion_tokens\": 456,\n \"total_tokens\": 579\n }\n }\n ],\n \"first_id\": \"run_abc123\",\n \"last_id\": \"run_abc456\",\n \"has_more\": false\n}\n" 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: name: Create run group: threads beta: true returns: A [run](/docs/api-reference/runs/object) object. examples: request: curl: "curl https://api.openai.com/v1/threads/thread_abc123/runs \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"assistant_id\": \"asst_abc123\"\n }'\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.beta.threads.runs.create(\n thread_id=\"thread_abc123\",\n assistant_id=\"asst_abc123\"\n)\nprint(run)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const run = await openai.beta.threads.runs.create(\n \"thread_abc123\",\n { assistant_id: \"asst_abc123\" }\n );\n\n console.log(run);\n}\n\nmain();\n" response: "{\n \"id\": \"run_abc123\",\n \"object\": \"thread.run\",\n \"created_at\": 1699063290,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"queued\",\n \"started_at\": 1699063290,\n \"expires_at\": null,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": 1699063291,\n \"last_error\": null,\n \"model\": \"gpt-4\",\n \"instructions\": null,\n \"tools\": [\n {\n \"type\": \"code_interpreter\"\n }\n ],\n \"file_ids\": [\n \"file-abc123\",\n \"file-abc456\"\n ],\n \"metadata\": {},\n \"usage\": null\n}\n" /threads/{thread_id}/runs/{run_id}: get: operationId: getRun tags: - Threads summary: OpenAI Retrieves a run. parameters: - in: path name: thread_id required: true schema: type: string description: The ID of the [thread](/docs/api-reference/threads) that was run. - in: path name: run_id required: true schema: type: string description: The ID of the run to retrieve. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RunObject' x-oaiMeta: name: Retrieve run group: threads beta: true returns: The [run](/docs/api-reference/runs/object) object matching the specified ID. examples: request: curl: "curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\"\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.beta.threads.runs.retrieve(\n thread_id=\"thread_abc123\",\n run_id=\"run_abc123\"\n)\nprint(run)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const run = await openai.beta.threads.runs.retrieve(\n \"thread_abc123\",\n \"run_abc123\"\n );\n\n console.log(run);\n}\n\nmain();\n" response: "{\n \"id\": \"run_abc123\",\n \"object\": \"thread.run\",\n \"created_at\": 1699075072,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"completed\",\n \"started_at\": 1699075072,\n \"expires_at\": null,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": 1699075073,\n \"last_error\": null,\n \"model\": \"gpt-3.5-turbo\",\n \"instructions\": null,\n \"tools\": [\n {\n \"type\": \"code_interpreter\"\n }\n ],\n \"file_ids\": [\n \"file-abc123\",\n \"file-abc456\"\n ],\n \"metadata\": {},\n \"usage\": {\n \"prompt_tokens\": 123,\n \"completion_tokens\": 456,\n \"total_tokens\": 579\n }\n}\n" post: operationId: modifyRun tags: - Threads summary: OpenAI Modifies a run. parameters: - in: path name: thread_id required: true schema: type: string description: The ID of the [thread](/docs/api-reference/threads) that was run. - in: path name: run_id required: true schema: type: string description: The ID of the run to modify. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ModifyRunRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RunObject' x-oaiMeta: name: Modify run group: threads beta: true returns: The modified [run](/docs/api-reference/runs/object) object matching the specified ID. examples: request: curl: "curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"metadata\": {\n \"user_id\": \"user_abc123\"\n }\n }'\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.beta.threads.runs.update(\n thread_id=\"thread_abc123\",\n run_id=\"run_abc123\",\n metadata={\"user_id\": \"user_abc123\"},\n)\nprint(run)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const run = await openai.beta.threads.runs.update(\n \"thread_abc123\",\n \"run_abc123\",\n {\n metadata: {\n user_id: \"user_abc123\",\n },\n }\n );\n\n console.log(run);\n}\n\nmain();\n" response: "{\n \"id\": \"run_abc123\",\n \"object\": \"thread.run\",\n \"created_at\": 1699075072,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"completed\",\n \"started_at\": 1699075072,\n \"expires_at\": null,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": 1699075073,\n \"last_error\": null,\n \"model\": \"gpt-3.5-turbo\",\n \"instructions\": null,\n \"tools\": [\n {\n \"type\": \"code_interpreter\"\n }\n ],\n \"file_ids\": [\n \"file-abc123\",\n \"file-abc456\"\n ],\n \"metadata\": {\n \"user_id\": \"user_abc123\"\n },\n \"usage\": {\n \"prompt_tokens\": 123,\n \"completion_tokens\": 456,\n \"total_tokens\": 579\n }\n}\n" /threads/{thread_id}/runs/{run_id}/submit_tool_outputs: post: operationId: submitToolOuputsToRun tags: - Threads summary: 'OpenAI When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they''re all completed. All outputs must be submitted in a single request.' parameters: - in: path name: thread_id required: true schema: type: string description: The ID of the [thread](/docs/api-reference/threads) to which this run belongs. - in: path name: run_id required: true schema: type: string description: The ID of the run that requires the tool output submission. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitToolOutputsRunRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RunObject' x-oaiMeta: name: Submit tool outputs to run group: threads beta: true returns: The modified [run](/docs/api-reference/runs/object) object matching the specified ID. examples: request: curl: "curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/submit_tool_outputs \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"tool_outputs\": [\n {\n \"tool_call_id\": \"call_abc123\",\n \"output\": \"28C\"\n }\n ]\n }'\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.beta.threads.runs.submit_tool_outputs(\n thread_id=\"thread_abc123\",\n run_id=\"run_abc123\",\n tool_outputs=[\n {\n \"tool_call_id\": \"call_abc123\",\n \"output\": \"28C\"\n }\n ]\n)\nprint(run)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const run = await openai.beta.threads.runs.submitToolOutputs(\n \"thread_abc123\",\n \"run_abc123\",\n {\n tool_outputs: [\n {\n tool_call_id: \"call_abc123\",\n output: \"28C\",\n },\n ],\n }\n );\n\n console.log(run);\n}\n\nmain();\n" response: "{\n \"id\": \"run_abc123\",\n \"object\": \"thread.run\",\n \"created_at\": 1699075592,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"queued\",\n \"started_at\": 1699075592,\n \"expires_at\": 1699076192,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": null,\n \"last_error\": null,\n \"model\": \"gpt-4\",\n \"instructions\": \"You tell the weather.\",\n \"tools\": [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_weather\",\n \"description\": \"Determine weather in my location\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"The city and state e.g. San Francisco, CA\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\n \"c\",\n \"f\"\n ]\n }\n },\n \"required\": [\n \"location\"\n ]\n }\n }\n }\n ],\n \"file_ids\": [],\n \"metadata\": {},\n \"usage\": null\n}\n" /threads/{thread_id}/runs/{run_id}/cancel: post: operationId: cancelRun tags: - Threads summary: OpenAI Cancels a run that is `in_progress`. parameters: - in: path name: thread_id required: true schema: type: string description: The ID of the thread to which this run belongs. - in: path name: run_id required: true schema: type: string description: The ID of the run to cancel. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RunObject' x-oaiMeta: name: Cancel a run group: threads beta: true returns: The modified [run](/docs/api-reference/runs/object) object matching the specified ID. examples: request: curl: "curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -X POST\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.beta.threads.runs.cancel(\n thread_id=\"thread_abc123\",\n run_id=\"run_abc123\"\n)\nprint(run)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const run = await openai.beta.threads.runs.cancel(\n \"thread_abc123\",\n \"run_abc123\"\n );\n\n console.log(run);\n}\n\nmain();\n" response: "{\n \"id\": \"run_abc123\",\n \"object\": \"thread.run\",\n \"created_at\": 1699076126,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"cancelling\",\n \"started_at\": 1699076126,\n \"expires_at\": 1699076726,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": null,\n \"last_error\": null,\n \"model\": \"gpt-4\",\n \"instructions\": \"You summarize books.\",\n \"tools\": [\n {\n \"type\": \"retrieval\"\n }\n ],\n \"file_ids\": [],\n \"metadata\": {},\n \"usage\": null\n}\n" /threads/{thread_id}/runs/{run_id}/steps: get: operationId: listRunSteps tags: - Threads summary: OpenAI Returns a list of run steps belonging to a run. parameters: - name: thread_id in: path required: true schema: type: string description: The ID of the thread the run and run steps belong to. - name: run_id in: path required: true schema: type: string description: The ID of the run the run steps 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/ListRunStepsResponse' x-oaiMeta: name: List run steps group: threads beta: true returns: A list of [run step](/docs/api-reference/runs/step-object) objects. examples: request: curl: "curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \\\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\nrun_steps = client.beta.threads.runs.steps.list(\n thread_id=\"thread_abc123\",\n run_id=\"run_abc123\"\n)\nprint(run_steps)\n" node.js: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nasync function main() {\n const runStep = await openai.beta.threads.runs.steps.list(\n \"thread_abc123\",\n \"run_abc123\"\n );\n console.log(runStep);\n}\n\nmain();\n" response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"step_abc123\",\n \"object\": \"thread.run.step\",\n \"created_at\": 1699063291,\n \"run_id\": \"run_abc123\",\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"type\": \"message_creation\",\n \"status\": \"completed\",\n \"cancelled_at\": null,\n \"completed_at\": 1699063291,\n \"expired_at\": null,\n \"failed_at\": null,\n \"last_error\": null,\n \"step_details\": {\n \"type\": \"message_creation\",\n \"message_creation\": {\n \"message_id\": \"msg_abc123\"\n }\n },\n \"usage\": {\n \"prompt_tokens\": 123,\n \"completion_tokens\": 456,\n \"total_tokens\": 579\n }\n }\n ],\n \"first_id\": \"step_abc123\",\n \"last_id\": \"step_abc456\",\n \"has_more\": false\n}\n" /threads/{thread_id}/runs/{run_id}/steps/{step_id}: get: operationId: getRunStep tags: - Threads summary: OpenAI Retrieves a run step. parameters: - in: path name: thread_id required: true schema: type: string description: The ID of the thread to which the run and run step belongs. - in: path name: run_id required: true schema: type: string description: The ID of the run to which the run step belongs. - in: path name: step_id required: true schema: type: string description: The ID of the run step to retrieve. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RunStepObject' x-oaiMeta: name: Retrieve run step group: threads beta: true returns: The [run step](/docs/api-reference/runs/step-object) object matching the specified ID. examples: request: curl: "curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_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\nrun_step = client.beta.threads.runs.steps.retrieve(\n thread_id=\"thread_abc123\",\n run_id=\"run_abc123\",\n step_id=\"step_abc123\"\n)\nprint(run_step)\n" node.js: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nasync function main() {\n const runStep = await openai.beta.threads.runs.steps.retrieve(\n \"thread_abc123\",\n \"run_abc123\",\n \"step_abc123\"\n );\n console.log(runStep);\n}\n\nmain();\n" response: "{\n \"id\": \"step_abc123\",\n \"object\": \"thread.run.step\",\n \"created_at\": 1699063291,\n \"run_id\": \"run_abc123\",\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"type\": \"message_creation\",\n \"status\": \"completed\",\n \"cancelled_at\": null,\n \"completed_at\": 1699063291,\n \"expired_at\": null,\n \"failed_at\": null,\n \"last_error\": null,\n \"step_details\": {\n \"type\": \"message_creation\",\n \"message_creation\": {\n \"message_id\": \"msg_abc123\"\n }\n },\n \"usage\": {\n \"prompt_tokens\": 123,\n \"completion_tokens\": 456,\n \"total_tokens\": 579\n }\n}\n" components: schemas: ListMessagesResponse: properties: object: type: string example: list data: type: array items: $ref: '#/components/schemas/MessageObject' first_id: type: string example: msg_abc123 last_id: type: string example: msg_abc123 has_more: type: boolean example: false required: - object - data - first_id - last_id - has_more DeleteThreadResponse: type: object properties: id: type: string deleted: type: boolean object: type: string enum: - thread.deleted required: - id - object - deleted ListRunStepsResponse: properties: object: type: string example: list data: type: array items: $ref: '#/components/schemas/RunStepObject' first_id: type: string example: step_abc123 last_id: type: string example: step_abc456 has_more: type: boolean example: false required: - object - data - first_id - last_id - has_more RunStepObject: type: object title: Run steps description: 'Represents a step in execution of a run. ' properties: id: description: The identifier of the run step, which can be referenced in API endpoints. type: string object: description: The object type, which is always `thread.run.step`. type: string enum: - thread.run.step created_at: description: The Unix timestamp (in seconds) for when the run step was created. type: integer assistant_id: description: The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. type: string thread_id: description: The ID of the [thread](/docs/api-reference/threads) that was run. type: string run_id: description: The ID of the [run](/docs/api-reference/runs) that this run step is a part of. type: string type: description: The type of run step, which can be either `message_creation` or `tool_calls`. type: string enum: - message_creation - tool_calls status: description: The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. type: string enum: - in_progress - cancelled - failed - completed - expired step_details: type: object description: The details of the run step. oneOf: - $ref: '#/components/schemas/RunStepDetailsMessageCreationObject' - $ref: '#/components/schemas/RunStepDetailsToolCallsObject' x-oaiExpandable: true last_error: type: object description: The last error associated with this run step. Will be `null` if there are no errors. nullable: true properties: code: type: string description: One of `server_error` or `rate_limit_exceeded`. enum: - server_error - rate_limit_exceeded message: type: string description: A human-readable description of the error. required: - code - message expired_at: description: The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. type: integer nullable: true cancelled_at: description: The Unix timestamp (in seconds) for when the run step was cancelled. type: integer nullable: true failed_at: description: The Unix timestamp (in seconds) for when the run step failed. type: integer nullable: true completed_at: description: The Unix timestamp (in seconds) for when the run step completed. type: integer nullable: true metadata: description: '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. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long. ' type: object x-oaiTypeLabel: map nullable: true usage: $ref: '#/components/schemas/RunStepCompletionUsage' required: - id - object - created_at - assistant_id - thread_id - run_id - type - status - step_details - last_error - expired_at - cancelled_at - failed_at - completed_at - metadata - usage x-oaiMeta: name: The run step object beta: true example: "{\n \"id\": \"step_abc123\",\n \"object\": \"thread.run.step\",\n \"created_at\": 1699063291,\n \"run_id\": \"run_abc123\",\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"type\": \"message_creation\",\n \"status\": \"completed\",\n \"cancelled_at\": null,\n \"completed_at\": 1699063291,\n \"expired_at\": null,\n \"failed_at\": null,\n \"last_error\": null,\n \"step_details\": {\n \"type\": \"message_creation\",\n \"message_creation\": {\n \"message_id\": \"msg_abc123\"\n }\n },\n \"usage\": {\n \"prompt_tokens\": 123,\n \"completion_tokens\": 456,\n \"total_tokens\": 579\n }\n}\n" ListRunsResponse: type: object properties: object: type: string example: list data: type: array items: $ref: '#/components/schemas/RunObject' first_id: type: string example: run_abc123 last_id: type: string example: run_abc456 has_more: type: boolean example: false required: - object - data - first_id - last_id - has_more ListMessageFilesResponse: properties: object: type: string example: list data: type: array items: $ref: '#/components/schemas/MessageFileObject' first_id: type: string example: file-abc123 last_id: type: string example: file-abc456 has_more: type: boolean example: false required: - object - data - items - first_id - last_id - has_more MessageObject: type: object title: The message object description: Represents a message within a [thread](/docs/api-reference/threads). properties: id: description: The identifier, which can be referenced in API endpoints. type: string object: description: The object type, which is always `thread.message`. type: string enum: - thread.message created_at: description: The Unix timestamp (in seconds) for when the message was created. type: integer thread_id: description: The [thread](/docs/api-reference/threads) ID that this message belongs to. type: string role: description: The entity that produced the message. One of `user` or `assistant`. type: string enum: - user - assistant content: description: The content of the message in array of text and/or images. type: array items: oneOf: - $ref: '#/components/schemas/MessageContentImageFileObject' - $ref: '#/components/schemas/MessageContentTextObject' x-oaiExpandable: true assistant_id: description: If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. type: string nullable: true run_id: description: If applicable, the ID of the [run](/docs/api-reference/runs) associated with the authoring of this message. type: string nullable: true file_ids: description: A list of [file](/docs/api-reference/files) IDs that the assistant should use. Useful for tools like retrieval and code_interpreter that can access files. A maximum of 10 files can be attached to a message. default: [] maxItems: 10 type: array items: type: string metadata: description: '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. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long. ' type: object x-oaiTypeLabel: map nullable: true required: - id - object - created_at - thread_id - role - content - assistant_id - run_id - file_ids - metadata x-oaiMeta: name: The message object beta: true example: "{\n \"id\": \"msg_abc123\",\n \"object\": \"thread.message\",\n \"created_at\": 1698983503,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"assistant\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"Hi! How can I help you today?\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [],\n \"assistant_id\": \"asst_abc123\",\n \"run_id\": \"run_abc123\",\n \"metadata\": {}\n}\n" ThreadObject: type: object title: Thread description: Represents a thread that contains [messages](/docs/api-reference/messages). properties: id: description: The identifier, which can be referenced in API endpoints. type: string object: description: The object type, which is always `thread`. type: string enum: - thread created_at: description: The Unix timestamp (in seconds) for when the thread was created. type: integer metadata: description: '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. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long. ' type: object x-oaiTypeLabel: map nullable: true required: - id - object - created_at - metadata x-oaiMeta: name: The thread object beta: true example: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread\",\n \"created_at\": 1698107661,\n \"metadata\": {}\n}\n" MessageFileObject: type: object title: Message files description: A list of files attached to a `message`. properties: id: description: The identifier, which can be referenced in API endpoints. type: string object: description: The object type, which is always `thread.message.file`. type: string enum: - thread.message.file created_at: description: The Unix timestamp (in seconds) for when the message file was created. type: integer message_id: description: The ID of the [message](/docs/api-reference/messages) that the [File](/docs/api-reference/files) is attached to. type: string required: - id - object - created_at - message_id x-oaiMeta: name: The message file object beta: true example: "{\n \"id\": \"file-abc123\",\n \"object\": \"thread.message.file\",\n \"created_at\": 1698107661,\n \"message_id\": \"message_QLoItBbqwyAJEzlTy4y9kOMM\",\n \"file_id\": \"file-abc123\"\n}\n" RunObject: type: object title: A run on a thread description: Represents an execution run on a [thread](/docs/api-reference/threads). properties: id: description: The identifier, which can be referenced in API endpoints. type: string object: description: The object type, which is always `thread.run`. type: string enum: - thread.run created_at: description: The Unix timestamp (in seconds) for when the run was created. type: integer thread_id: description: The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. type: string assistant_id: description: The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. type: string status: description: The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, or `expired`. type: string enum: - queued - in_progress - requires_action - cancelling - cancelled - failed - completed - expired required_action: type: object description: Details on the action required to continue the run. Will be `null` if no action is required. nullable: true properties: type: description: For now, this is always `submit_tool_outputs`. type: string enum: - submit_tool_outputs submit_tool_outputs: type: object description: Details on the tool outputs needed for this run to continue. properties: tool_calls: type: array description: A list of the relevant tool calls. items: $ref: '#/components/schemas/RunToolCallObject' required: - tool_calls required: - type - submit_tool_outputs last_error: type: object description: The last error associated with this run. Will be `null` if there are no errors. nullable: true properties: code: type: string description: One of `server_error` or `rate_limit_exceeded`. enum: - server_error - rate_limit_exceeded message: type: string description: A human-readable description of the error. required: - code - message expires_at: description: The Unix timestamp (in seconds) for when the run will expire. type: integer started_at: description: The Unix timestamp (in seconds) for when the run was started. type: integer nullable: true cancelled_at: description: The Unix timestamp (in seconds) for when the run was cancelled. type: integer nullable: true failed_at: description: The Unix timestamp (in seconds) for when the run failed. type: integer nullable: true completed_at: description: The Unix timestamp (in seconds) for when the run was completed. type: integer nullable: true model: description: The model that the [assistant](/docs/api-reference/assistants) used for this run. type: string instructions: description: The instructions that the [assistant](/docs/api-reference/assistants) used for this run. type: string tools: description: The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. default: [] type: array maxItems: 20 items: oneOf: - $ref: '#/components/schemas/AssistantToolsCode' - $ref: '#/components/schemas/AssistantToolsRetrieval' - $ref: '#/components/schemas/AssistantToolsFunction' x-oaiExpandable: true file_ids: description: The list of [File](/docs/api-reference/files) IDs the [assistant](/docs/api-reference/assistants) used for this run. default: [] type: array items: type: string metadata: description: '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. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long. ' type: object x-oaiTypeLabel: map nullable: true usage: $ref: '#/components/schemas/RunCompletionUsage' required: - id - object - created_at - thread_id - assistant_id - status - required_action - last_error - expires_at - started_at - cancelled_at - failed_at - completed_at - model - instructions - tools - file_ids - metadata - usage x-oaiMeta: name: The run object beta: true example: "{\n \"id\": \"run_abc123\",\n \"object\": \"thread.run\",\n \"created_at\": 1698107661,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"completed\",\n \"started_at\": 1699073476,\n \"expires_at\": null,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": 1699073498,\n \"last_error\": null,\n \"model\": \"gpt-4\",\n \"instructions\": null,\n \"tools\": [{\"type\": \"retrieval\"}, {\"type\": \"code_interpreter\"}],\n \"file_ids\": [],\n \"metadata\": {},\n \"usage\": {\n \"prompt_tokens\": 123,\n \"completion_tokens\": 456,\n \"total_tokens\": 579\n }\n}\n" securitySchemes: ApiKeyAuth: type: http scheme: bearer x-oaiMeta: groups: - id: audio title: Audio description: 'Learn how to turn audio into text or text into audio. Related guide: [Speech to text](/docs/guides/speech-to-text) ' sections: - type: endpoint key: createSpeech path: createSpeech - type: endpoint key: createTranscription path: createTranscription - type: endpoint key: createTranslation path: createTranslation - id: chat title: Chat description: 'Given a list of messages comprising a conversation, the model will return a response. Related guide: [Chat Completions](/docs/guides/text-generation) ' sections: - type: endpoint key: createChatCompletion path: create - type: object key: CreateChatCompletionResponse path: object - type: object key: CreateChatCompletionStreamResponse path: streaming - id: embeddings title: Embeddings description: 'Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms. Related guide: [Embeddings](/docs/guides/embeddings) ' sections: - type: endpoint key: createEmbedding path: create - type: object key: Embedding path: object - id: fine-tuning title: Fine-tuning description: 'Manage fine-tuning jobs to tailor a model to your specific training data. Related guide: [Fine-tune models](/docs/guides/fine-tuning) ' sections: - type: endpoint key: createFineTuningJob path: create - type: endpoint key: listPaginatedFineTuningJobs path: list - type: endpoint key: listFineTuningEvents path: list-events - type: endpoint key: retrieveFineTuningJob path: retrieve - type: endpoint key: cancelFineTuningJob path: cancel - type: object key: FineTuningJob path: object - type: object key: FineTuningJobEvent path: event-object - id: files title: Files description: 'Files are used to upload documents that can be used with features like [Assistants](/docs/api-reference/assistants) and [Fine-tuning](/docs/api-reference/fine-tuning). ' sections: - type: endpoint key: createFile path: create - type: endpoint key: listFiles path: list - type: endpoint key: retrieveFile path: retrieve - type: endpoint key: deleteFile path: delete - type: endpoint key: downloadFile path: retrieve-contents - type: object key: OpenAIFile path: object - id: images title: Images description: 'Given a prompt and/or an input image, the model will generate a new image. Related guide: [Image generation](/docs/guides/images) ' sections: - type: endpoint key: createImage path: create - type: endpoint key: createImageEdit path: createEdit - type: endpoint key: createImageVariation path: createVariation - type: object key: Image path: object - id: models title: Models description: 'List and describe the various models available in the API. You can refer to the [Models](/docs/models) documentation to understand what models are available and the differences between them. ' sections: - type: endpoint key: listModels path: list - type: endpoint key: retrieveModel path: retrieve - type: endpoint key: deleteModel path: delete - type: object key: Model path: object - id: moderations title: Moderations description: 'Given a input text, outputs if the model classifies it as violating OpenAI''s content policy. Related guide: [Moderations](/docs/guides/moderation) ' sections: - type: endpoint key: createModeration path: create - type: object key: CreateModerationResponse path: object - id: assistants title: Assistants beta: true description: 'Build assistants that can call models and use tools to perform tasks. [Get started with the Assistants API](/docs/assistants) ' sections: - type: endpoint key: createAssistant path: createAssistant - type: endpoint key: createAssistantFile path: createAssistantFile - type: endpoint key: listAssistants path: listAssistants - type: endpoint key: listAssistantFiles path: listAssistantFiles - type: endpoint key: getAssistant path: getAssistant - type: endpoint key: getAssistantFile path: getAssistantFile - type: endpoint key: modifyAssistant path: modifyAssistant - type: endpoint key: deleteAssistant path: deleteAssistant - type: endpoint key: deleteAssistantFile path: deleteAssistantFile - type: object key: AssistantObject path: object - type: object key: AssistantFileObject path: file-object - id: threads title: Threads beta: true description: 'Create threads that assistants can interact with. Related guide: [Assistants](/docs/assistants/overview) ' sections: - type: endpoint key: createThread path: createThread - type: endpoint key: getThread path: getThread - type: endpoint key: modifyThread path: modifyThread - type: endpoint key: deleteThread path: deleteThread - type: object key: ThreadObject path: object - id: messages title: Messages beta: true description: 'Create messages within threads Related guide: [Assistants](/docs/assistants/overview) ' sections: - type: endpoint key: createMessage path: createMessage - type: endpoint key: listMessages path: listMessages - type: endpoint key: listMessageFiles path: listMessageFiles - type: endpoint key: getMessage path: getMessage - type: endpoint key: getMessageFile path: getMessageFile - type: endpoint key: modifyMessage path: modifyMessage - type: object key: MessageObject path: object - type: object key: MessageFileObject path: file-object - id: runs title: Runs beta: true description: 'Represents an execution run on a thread. Related guide: [Assistants](/docs/assistants/overview) ' sections: - type: endpoint key: createRun path: createRun - type: endpoint key: createThreadAndRun path: createThreadAndRun - type: endpoint key: listRuns path: listRuns - type: endpoint key: listRunSteps path: listRunSteps - type: endpoint key: getRun path: getRun - type: endpoint key: getRunStep path: getRunStep - type: endpoint key: modifyRun path: modifyRun - type: endpoint key: submitToolOuputsToRun path: submitToolOutputs - type: endpoint key: cancelRun path: cancelRun - type: object key: RunObject path: object - type: object key: RunStepObject path: step-object - id: completions title: Completions legacy: true description: 'Given a prompt, the model will return one or more predicted completions along with the probabilities of alternative tokens at each position. Most developer should use our [Chat Completions API](/docs/guides/text-generation/text-generation-models) to leverage our best and newest models. Most models that support the legacy Completions endpoint [will be shut off on January 4th, 2024](/docs/deprecations/2023-07-06-gpt-and-embeddings). ' sections: - type: endpoint key: createCompletion path: create - type: object key: CreateCompletionResponse path: object