openapi: 3.0.0
info:
title: OpenAI Assistants Organization 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: Organization
paths:
/organization/admin_api_keys:
get:
security:
- AdminApiKeyAuth: []
summary: List organization API keys
operationId: admin-api-keys-list
description: Retrieve a paginated list of organization admin API keys.
parameters:
- in: query
name: after
required: false
schema:
type: string
nullable: true
description: Return keys with IDs that come after this ID in the pagination order.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: Order results by creation time, ascending or descending.
- in: query
name: limit
required: false
schema:
type: integer
default: 20
description: Maximum number of keys to return.
responses:
'200':
description: A list of organization API keys.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyList'
x-oaiMeta:
name: List all organization and project API keys.
group: administration
examples:
request:
curl: "curl https://api.openai.com/v1/organization/admin_api_keys?after=key_abc&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\n// Automatically fetches more pages as needed.\nfor await (const adminAPIKey of client.admin.organization.adminAPIKeys.list()) {\n console.log(adminAPIKey.id);\n}"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\npage = client.admin.organization.admin_api_keys.list()\npage = page.data[0]\nprint(page.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.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\tpage, err := client.Admin.Organization.AdminAPIKeys.List(context.TODO(), openai.AdminOrganizationAdminAPIKeyListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.adminapikeys.AdminApiKeyListPage;\nimport com.openai.models.admin.organization.adminapikeys.AdminApiKeyListParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n AdminApiKeyListPage page = client.admin().organization().adminApiKeys().list();\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
page = openai.admin.organization.admin_api_keys.list
puts(page)'
response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.admin_api_key\",\n \"id\": \"key_abc\",\n \"name\": \"Main Admin Key\",\n \"redacted_value\": \"sk-admin...def\",\n \"created_at\": 1711471533,\n \"last_used_at\": 1711471534,\n \"owner\": {\n \"type\": \"service_account\",\n \"object\": \"organization.service_account\",\n \"id\": \"sa_456\",\n \"name\": \"My Service Account\",\n \"created_at\": 1711471533,\n \"role\": \"member\"\n }\n }\n ],\n \"first_id\": \"key_abc\",\n \"last_id\": \"key_abc\",\n \"has_more\": false\n}\n"
tags:
- Organization
post:
security:
- AdminApiKeyAuth: []
summary: Create an organization admin API key
operationId: admin-api-keys-create
description: Create a new admin-level API key for the organization.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
example: New Admin Key
responses:
'200':
description: The newly created admin API key.
content:
application/json:
schema:
$ref: '#/components/schemas/AdminApiKeyCreateResponse'
x-oaiMeta:
name: Create admin API key
group: administration
examples:
request:
curl: "curl -X POST https://api.openai.com/v1/organization/admin_api_keys \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"New Admin Key\"\n }'\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\nconst adminAPIKey = await client.admin.organization.adminAPIKeys.create({ name: 'New Admin Key' });\n\nconsole.log(adminAPIKey);"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\nadmin_api_key = client.admin.organization.admin_api_keys.create(\n name=\"New Admin Key\",\n)\nprint(admin_api_key)"
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.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\tadminAPIKey, err := client.Admin.Organization.AdminAPIKeys.New(context.TODO(), openai.AdminOrganizationAdminAPIKeyNewParams{\n\t\tName: \"New Admin Key\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", adminAPIKey)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.adminapikeys.AdminApiKeyCreateParams;\nimport com.openai.models.admin.organization.adminapikeys.AdminApiKeyCreateResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n AdminApiKeyCreateParams params = AdminApiKeyCreateParams.builder()\n .name(\"New Admin Key\")\n .build();\n AdminApiKeyCreateResponse adminApiKey = client.admin().organization().adminApiKeys().create(params);\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
admin_api_key = openai.admin.organization.admin_api_keys.create(name: "New Admin Key")
puts(admin_api_key)'
response: "{\n \"object\": \"organization.admin_api_key\",\n \"id\": \"key_xyz\",\n \"name\": \"New Admin Key\",\n \"redacted_value\": \"sk-admin...xyz\",\n \"created_at\": 1711471533,\n \"last_used_at\": 1711471534,\n \"owner\": {\n \"type\": \"user\",\n \"object\": \"organization.user\",\n \"id\": \"user_123\",\n \"name\": \"John Doe\",\n \"created_at\": 1711471533,\n \"role\": \"owner\"\n },\n \"value\": \"sk-admin-1234abcd\"\n}\n"
tags:
- Organization
/organization/admin_api_keys/{key_id}:
get:
security:
- AdminApiKeyAuth: []
summary: Retrieve a single organization API key
operationId: admin-api-keys-get
description: Get details for a specific organization API key by its ID.
parameters:
- in: path
name: key_id
required: true
schema:
type: string
description: The ID of the API key.
responses:
'200':
description: Details of the requested API key.
content:
application/json:
schema:
$ref: '#/components/schemas/AdminApiKey'
x-oaiMeta:
name: Retrieve admin API key
group: administration
examples:
request:
curl: "curl https://api.openai.com/v1/organization/admin_api_keys/key_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\nconst adminAPIKey = await client.admin.organization.adminAPIKeys.retrieve('key_id');\n\nconsole.log(adminAPIKey.id);"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\nadmin_api_key = client.admin.organization.admin_api_keys.retrieve(\n \"key_id\",\n)\nprint(admin_api_key.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.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\tadminAPIKey, err := client.Admin.Organization.AdminAPIKeys.Get(context.TODO(), \"key_id\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", adminAPIKey.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.adminapikeys.AdminApiKey;\nimport com.openai.models.admin.organization.adminapikeys.AdminApiKeyRetrieveParams;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n AdminApiKey adminApiKey = client.admin().organization().adminApiKeys().retrieve(\"key_id\");\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
admin_api_key = openai.admin.organization.admin_api_keys.retrieve("key_id")
puts(admin_api_key)'
response: "{\n \"object\": \"organization.admin_api_key\",\n \"id\": \"key_abc\",\n \"name\": \"Main Admin Key\",\n \"redacted_value\": \"sk-admin...xyz\",\n \"created_at\": 1711471533,\n \"last_used_at\": 1711471534,\n \"owner\": {\n \"type\": \"user\",\n \"object\": \"organization.user\",\n \"id\": \"user_123\",\n \"name\": \"John Doe\",\n \"created_at\": 1711471533,\n \"role\": \"owner\"\n }\n}\n"
tags:
- Organization
delete:
security:
- AdminApiKeyAuth: []
summary: Delete an organization admin API key
operationId: admin-api-keys-delete
description: Delete the specified admin API key.
parameters:
- in: path
name: key_id
required: true
schema:
type: string
description: The ID of the API key to be deleted.
responses:
'200':
description: Confirmation that the API key was deleted.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: key_abc
object:
type: string
enum:
- organization.admin_api_key.deleted
example: organization.admin_api_key.deleted
x-stainless-const: true
deleted:
type: boolean
example: true
required:
- id
- object
- deleted
x-oaiMeta:
name: Delete admin API key
group: administration
examples:
request:
curl: "curl -X DELETE https://api.openai.com/v1/organization/admin_api_keys/key_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n"
node.js: "import OpenAI from 'openai';\n\nconst client = new OpenAI({\n adminAPIKey: process.env['OPENAI_ADMIN_KEY'], // This is the default and can be omitted\n});\n\nconst adminAPIKey = await client.admin.organization.adminAPIKeys.delete('key_id');\n\nconsole.log(adminAPIKey.id);"
python: "import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n admin_api_key=os.environ.get(\"OPENAI_ADMIN_KEY\"), # This is the default and can be omitted\n)\nadmin_api_key = client.admin.organization.admin_api_keys.delete(\n \"key_id\",\n)\nprint(admin_api_key.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.WithAdminAPIKey(\"My Admin API Key\"),\n\t)\n\tadminAPIKey, err := client.Admin.Organization.AdminAPIKeys.Delete(context.TODO(), \"key_id\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", adminAPIKey.ID)\n}\n"
java: "package com.openai.example;\n\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.admin.organization.adminapikeys.AdminApiKeyDeleteParams;\nimport com.openai.models.admin.organization.adminapikeys.AdminApiKeyDeleteResponse;\n\npublic final class Main {\n private Main() {}\n\n public static void main(String[] args) {\n OpenAIClient client = OpenAIOkHttpClient.fromEnv();\n\n AdminApiKeyDeleteResponse adminApiKey = client.admin().organization().adminApiKeys().delete(\"key_id\");\n }\n}"
ruby: 'require "openai"
openai = OpenAI::Client.new(admin_api_key: "My Admin API Key")
admin_api_key = openai.admin.organization.admin_api_keys.delete("key_id")
puts(admin_api_key)'
response: "{\n \"id\": \"key_abc\",\n \"object\": \"organization.admin_api_key.deleted\",\n \"deleted\": true\n}\n"
tags:
- Organization
components:
schemas:
ApiKeyList:
type: object
properties:
object:
type: string
enum:
- list
example: list
x-stainless-const: true
data:
type: array
items:
$ref: '#/components/schemas/AdminApiKey'
has_more:
type: boolean
example: false
first_id:
anyOf:
- type: string
- type: 'null'
example: key_abc
last_id:
anyOf:
- type: string
- type: 'null'
example: key_xyz
required:
- object
- data
- has_more
AdminApiKeyCreateResponse:
allOf:
- $ref: '#/components/schemas/AdminApiKey'
- type: object
description: The newly created admin API key. The `value` field is only returned once, when the key is created.
properties:
value:
type: string
example: sk-admin-1234abcd
description: The value of the API key. Only shown on create.
required:
- value
AdminApiKey:
type: object
description: Represents an individual Admin API key in an org.
properties:
object:
type: string
enum:
- organization.admin_api_key
description: The object type, which is always `organization.admin_api_key`
x-stainless-const: true
id:
type: string
example: key_abc
description: The identifier, which can be referenced in API endpoints
name:
anyOf:
- type: string
- type: 'null'
example: Administration Key
description: The name of the API key
redacted_value:
type: string
example: sk-admin...def
description: The redacted value of the API key
created_at:
type: integer
format: unixtime
example: 1711471533
description: The Unix timestamp (in seconds) of when the API key was created
last_used_at:
anyOf:
- type: integer
format: unixtime
example: 1711471534
description: The Unix timestamp (in seconds) of when the API key was last used
- type: 'null'
owner:
type: object
properties:
type:
type: string
example: user
description: Always `user`
object:
type: string
example: organization.user
description: The object type, which is always organization.user
id:
type: string
example: sa_456
description: The identifier, which can be referenced in API endpoints
name:
type: string
example: My Service Account
description: The name of the user
created_at:
type: integer
format: unixtime
example: 1711471533
description: The Unix timestamp (in seconds) of when the user was created
role:
type: string
example: owner
description: Always `owner`
required:
- object
- redacted_value
- created_at
- id
- owner
x-oaiMeta:
name: The admin API key object
example: "{\n \"object\": \"organization.admin_api_key\",\n \"id\": \"key_abc\",\n \"name\": \"Main Admin Key\",\n \"redacted_value\": \"sk-admin...xyz\",\n \"created_at\": 1711471533,\n \"last_used_at\": 1711471534,\n \"owner\": {\n \"type\": \"user\",\n \"object\": \"organization.user\",\n \"id\": \"user_123\",\n \"name\": \"John Doe\",\n \"created_at\": 1711471533,\n \"role\": \"owner\"\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