{ "openapi": "3.1.0", "info": { "title": "OpenAI API", "description": "The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details.", "version": "2.3.0", "termsOfService": "https://openai.com/policies/terms-of-use", "contact": { "name": "OpenAI Support", "url": "https://help.openai.com/" }, "license": { "name": "MIT", "identifier": "MIT" } }, "servers": [ { "url": "https://api.openai.com/v1" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Assistants", "description": "Build Assistants that can call models and use tools." }, { "name": "Audio", "description": "Turn audio into text or text into audio." }, { "name": "Chat", "description": "Given a list of messages comprising a conversation, the model will return a response." }, { "name": "Conversations", "description": "Manage conversations and conversation items." }, { "name": "Completions", "description": "Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position." }, { "name": "Embeddings", "description": "Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms." }, { "name": "Evals", "description": "Manage and run evals in the OpenAI platform." }, { "name": "Fine-tuning", "description": "Manage fine-tuning jobs to tailor a model to your specific training data." }, { "name": "Graders", "description": "Manage and run graders in the OpenAI platform." }, { "name": "Batch", "description": "Create large batches of API requests to run asynchronously." }, { "name": "Files", "description": "Files are used to upload documents that can be used with features like Assistants and Fine-tuning." }, { "name": "Uploads", "description": "Use Uploads to upload large files in multiple parts." }, { "name": "Images", "description": "Given a prompt and/or an input image, the model will generate a new image." }, { "name": "Models", "description": "List and describe the various models available in the API." }, { "name": "Moderations", "description": "Given text and/or image inputs, classifies if those inputs are potentially harmful." }, { "name": "Audit Logs", "description": "List user actions and configuration changes within this organization." } ], "paths": { "/assistants": { "get": { "operationId": "listAssistants", "tags": [ "Assistants" ], "summary": "Returns a list of assistants.", "deprecated": true, "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.\n", "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.\n", "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.\n", "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, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAssistantsResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List assistants", "group": "assistants", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/assistants?order=desc&limit=20\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistants = client.beta.assistants.list(\n order=\"desc\",\n limit=\"20\",\n)\nprint(my_assistants.data)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistants = await openai.beta.assistants.list({\n order: \"desc\",\n limit: \"20\",\n });\n\n console.log(myAssistants.data);\n}\n\nmain();" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1698982736,\n \"name\": \"Coding Tutor\",\n \"description\": null,\n \"model\": \"gpt-4o\",\n \"instructions\": \"You are a helpful assistant designed to make me better at coding!\",\n \"tools\": [],\n \"tool_resources\": {},\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n },\n {\n \"id\": \"asst_abc456\",\n \"object\": \"assistant\",\n \"created_at\": 1698982718,\n \"name\": \"My Assistant\",\n \"description\": null,\n \"model\": \"gpt-4o\",\n \"instructions\": \"You are a helpful assistant designed to make me better at coding!\",\n \"tools\": [],\n \"tool_resources\": {},\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n },\n {\n \"id\": \"asst_abc789\",\n \"object\": \"assistant\",\n \"created_at\": 1698982643,\n \"name\": null,\n \"description\": null,\n \"model\": \"gpt-4o\",\n \"instructions\": null,\n \"tools\": [],\n \"tool_resources\": {},\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n }\n ],\n \"first_id\": \"asst_abc123\",\n \"last_id\": \"asst_abc789\",\n \"has_more\": false\n}\n" } } }, "post": { "operationId": "createAssistant", "tags": [ "Assistants" ], "summary": "Create an assistant with a model and instructions.", "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssistantRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantObject" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create assistant", "group": "assistants", "examples": [ { "title": "Code Interpreter", "request": { "curl": "curl \"https://api.openai.com/v1/assistants\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\" \\\n -d '{\n \"instructions\": \"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n \"name\": \"Math Tutor\",\n \"tools\": [{\"type\": \"code_interpreter\"}],\n \"model\": \"gpt-4o\"\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistant = client.beta.assistants.create(\n instructions=\"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n name=\"Math Tutor\",\n tools=[{\"type\": \"code_interpreter\"}],\n model=\"gpt-4o\",\n)\nprint(my_assistant)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistant = await openai.beta.assistants.create({\n instructions:\n \"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n name: \"Math Tutor\",\n tools: [{ type: \"code_interpreter\" }],\n model: \"gpt-4o\",\n });\n\n console.log(myAssistant);\n}\n\nmain();" }, "response": "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1698984975,\n \"name\": \"Math Tutor\",\n \"description\": null,\n \"model\": \"gpt-4o\",\n \"instructions\": \"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n \"tools\": [\n {\n \"type\": \"code_interpreter\"\n }\n ],\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n}\n" }, { "title": "Files", "request": { "curl": "curl https://api.openai.com/v1/assistants \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\" \\\n -d '{\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n \"tools\": [{\"type\": \"file_search\"}],\n \"tool_resources\": {\"file_search\": {\"vector_store_ids\": [\"vs_123\"]}},\n \"model\": \"gpt-4o\"\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistant = client.beta.assistants.create(\n instructions=\"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n name=\"HR Helper\",\n tools=[{\"type\": \"file_search\"}],\n tool_resources={\"file_search\": {\"vector_store_ids\": [\"vs_123\"]}},\n model=\"gpt-4o\"\n)\nprint(my_assistant)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistant = await openai.beta.assistants.create({\n instructions:\n \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n name: \"HR Helper\",\n tools: [{ type: \"file_search\" }],\n tool_resources: {\n file_search: {\n vector_store_ids: [\"vs_123\"]\n }\n },\n model: \"gpt-4o\"\n });\n\n console.log(myAssistant);\n}\n\nmain();" }, "response": "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1699009403,\n \"name\": \"HR Helper\",\n \"description\": null,\n \"model\": \"gpt-4o\",\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n \"tools\": [\n {\n \"type\": \"file_search\"\n }\n ],\n \"tool_resources\": {\n \"file_search\": {\n \"vector_store_ids\": [\"vs_123\"]\n }\n },\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n}\n" } ] } } }, "/assistants/{assistant_id}": { "get": { "operationId": "getAssistant", "tags": [ "Assistants" ], "summary": "Retrieves an assistant.", "deprecated": true, "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" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve assistant", "group": "assistants", "examples": { "request": { "curl": "curl https://api.openai.com/v1/assistants/asst_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistant = client.beta.assistants.retrieve(\"asst_abc123\")\nprint(my_assistant)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myAssistant = await openai.beta.assistants.retrieve(\n \"asst_abc123\"\n );\n\n console.log(myAssistant);\n}\n\nmain();" }, "response": "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1699009709,\n \"name\": \"HR Helper\",\n \"description\": null,\n \"model\": \"gpt-4o\",\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies.\",\n \"tools\": [\n {\n \"type\": \"file_search\"\n }\n ],\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n}\n" } } }, "post": { "operationId": "modifyAssistant", "tags": [ "Assistants" ], "summary": "Modifies an assistant.", "deprecated": true, "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" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Modify assistant", "group": "assistants", "examples": { "request": { "curl": "curl https://api.openai.com/v1/assistants/asst_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\" \\\n -d '{\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n \"tools\": [{\"type\": \"file_search\"}],\n \"model\": \"gpt-4o\"\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_updated_assistant = client.beta.assistants.update(\n \"asst_abc123\",\n instructions=\"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n name=\"HR Helper\",\n tools=[{\"type\": \"file_search\"}],\n model=\"gpt-4o\"\n)\n\nprint(my_updated_assistant)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myUpdatedAssistant = await openai.beta.assistants.update(\n \"asst_abc123\",\n {\n instructions:\n \"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n name: \"HR Helper\",\n tools: [{ type: \"file_search\" }],\n model: \"gpt-4o\"\n }\n );\n\n console.log(myUpdatedAssistant);\n}\n\nmain();" }, "response": "{\n \"id\": \"asst_123\",\n \"object\": \"assistant\",\n \"created_at\": 1699009709,\n \"name\": \"HR Helper\",\n \"description\": null,\n \"model\": \"gpt-4o\",\n \"instructions\": \"You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.\",\n \"tools\": [\n {\n \"type\": \"file_search\"\n }\n ],\n \"tool_resources\": {\n \"file_search\": {\n \"vector_store_ids\": []\n }\n },\n \"metadata\": {},\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"response_format\": \"auto\"\n}\n" } } }, "delete": { "operationId": "deleteAssistant", "tags": [ "Assistants" ], "summary": "Delete an assistant.", "deprecated": true, "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" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Delete assistant", "group": "assistants", "examples": { "request": { "curl": "curl https://api.openai.com/v1/assistants/asst_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v2\" \\\n -X DELETE\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nresponse = client.beta.assistants.delete(\"asst_abc123\")\nprint(response)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.beta.assistants.delete(\"asst_abc123\");\n\n console.log(response);\n}\nmain();" }, "response": "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant.deleted\",\n \"deleted\": true\n}\n" } } } }, "/audio/speech": { "post": { "operationId": "createSpeech", "tags": [ "Audio" ], "summary": "Generates audio from the input text.\n\nReturns the audio file content, or a stream of audio events.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpeechRequest" } } } }, "responses": { "200": { "description": "OK", "headers": { "Transfer-Encoding": { "schema": { "type": "string" }, "description": "chunked" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/CreateSpeechResponseStreamEvent" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create speech", "group": "audio", "examples": [ { "title": "Default", "request": { "curl": "curl https://api.openai.com/v1/audio/speech \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-4o-mini-tts\",\n \"input\": \"The quick brown fox jumped over the lazy dog.\",\n \"voice\": \"alloy\"\n }' \\\n --output speech.mp3\n", "python": "from pathlib import Path\nimport openai\n\nspeech_file_path = Path(__file__).parent / \"speech.mp3\"\nwith openai.audio.speech.with_streaming_response.create(\n model=\"gpt-4o-mini-tts\",\n voice=\"alloy\",\n input=\"The quick brown fox jumped over the lazy dog.\"\n) as response:\n response.stream_to_file(speech_file_path)\n", "javascript": "import fs from \"fs\";\nimport path from \"path\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst speechFile = path.resolve(\"./speech.mp3\");\n\nasync function main() {\n const mp3 = await openai.audio.speech.create({\n model: \"gpt-4o-mini-tts\",\n voice: \"alloy\",\n input: \"Today is a wonderful day to build something people love!\",\n });\n console.log(speechFile);\n const buffer = Buffer.from(await mp3.arrayBuffer());\n await fs.promises.writeFile(speechFile, buffer);\n}\nmain();\n", "csharp": "using System;\nusing System.IO;\n\nusing OpenAI.Audio;\n\nAudioClient client = new(\n model: \"gpt-4o-mini-tts\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nBinaryData speech = client.GenerateSpeech(\n text: \"The quick brown fox jumped over the lazy dog.\",\n voice: GeneratedSpeechVoice.Alloy\n);\n\nusing FileStream stream = File.OpenWrite(\"speech.mp3\");\nspeech.ToStream().CopyTo(stream);\n" } }, { "title": "SSE Stream Format", "request": { "curl": "curl https://api.openai.com/v1/audio/speech \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-4o-mini-tts\",\n \"input\": \"The quick brown fox jumped over the lazy dog.\",\n \"voice\": \"alloy\",\n \"stream_format\": \"sse\"\n }'\n" } } ] } } }, "/audio/transcriptions": { "post": { "operationId": "createTranscription", "tags": [ "Audio" ], "summary": "Transcribes audio into the input language.\n\nReturns a transcription object in `json`, `diarized_json`, or `verbose_json`\nformat, or a stream of transcript events.\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateTranscriptionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateTranscriptionResponseJson" }, { "$ref": "#/components/schemas/CreateTranscriptionResponseDiarizedJson" }, { "$ref": "#/components/schemas/CreateTranscriptionResponseVerboseJson" } ] } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/CreateTranscriptionResponseStreamEvent" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create transcription", "group": "audio", "examples": [ { "title": "Default", "request": { "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F model=\"gpt-4o-transcribe\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.transcriptions.create(\n model=\"gpt-4o-transcribe\",\n file=audio_file\n)\n", "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const transcription = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"gpt-4o-transcribe\",\n });\n\n console.log(transcription.text);\n}\nmain();\n", "csharp": "using System;\n\nusing OpenAI.Audio;\nstring audioFilePath = \"audio.mp3\";\n\nAudioClient client = new(\n model: \"gpt-4o-transcribe\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nAudioTranscription transcription = client.TranscribeAudio(audioFilePath);\n\nConsole.WriteLine($\"{transcription.Text}\");\n" }, "response": "{\n \"text\": \"Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that.\",\n \"usage\": {\n \"type\": \"tokens\",\n \"input_tokens\": 14,\n \"input_token_details\": {\n \"text_tokens\": 0,\n \"audio_tokens\": 14\n },\n \"output_tokens\": 45,\n \"total_tokens\": 59\n }\n}\n" }, { "title": "Diarization", "request": { "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/meeting.wav\" \\\n -F model=\"gpt-4o-transcribe-diarize\" \\\n -F response_format=\"diarized_json\" \\\n -F chunking_strategy=auto \\\n -F 'known_speaker_names[]=agent' \\\n -F 'known_speaker_references[]=data:audio/wav;base64,AAA...'\n", "python": "import base64\nfrom openai import OpenAI\n\nclient = OpenAI()\n\ndef to_data_url(path: str) -> str:\n with open(path, \"rb\") as fh:\n return \"data:audio/wav;base64,\" + base64.b64encode(fh.read()).decode(\"utf-8\")\n\nwith open(\"meeting.wav\", \"rb\") as audio_file:\n transcript = client.audio.transcriptions.create(\n model=\"gpt-4o-transcribe-diarize\",\n file=audio_file,\n response_format=\"diarized_json\",\n chunking_strategy=\"auto\",\n extra_body={\n \"known_speaker_names\": [\"agent\"],\n \"known_speaker_references\": [to_data_url(\"agent.wav\")],\n },\n )\n\nprint(transcript.segments)\n", "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst speakerRef = fs.readFileSync(\"agent.wav\").toString(\"base64\");\n\nconst transcript = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"meeting.wav\"),\n model: \"gpt-4o-transcribe-diarize\",\n response_format: \"diarized_json\",\n chunking_strategy: \"auto\",\n extra_body: {\n known_speaker_names: [\"agent\"],\n known_speaker_references: [`data:audio/wav;base64,${speakerRef}`],\n },\n});\n\nconsole.log(transcript.segments);\n" }, "response": "{\n \"task\": \"transcribe\",\n \"duration\": 27.4,\n \"text\": \"Agent: Thanks for calling OpenAI support.\\nA: Hi, I'm trying to enable diarization.\\nAgent: Happy to walk you through the steps.\",\n \"segments\": [\n {\n \"type\": \"transcript.text.segment\",\n \"id\": \"seg_001\",\n \"start\": 0.0,\n \"end\": 4.7,\n \"text\": \"Thanks for calling OpenAI support.\",\n \"speaker\": \"agent\"\n },\n {\n \"type\": \"transcript.text.segment\",\n \"id\": \"seg_002\",\n \"start\": 4.7,\n \"end\": 11.8,\n \"text\": \"Hi, I'm trying to enable diarization.\",\n \"speaker\": \"A\"\n },\n {\n \"type\": \"transcript.text.segment\",\n \"id\": \"seg_003\",\n \"start\": 12.1,\n \"end\": 18.5,\n \"text\": \"Happy to walk you through the steps.\",\n \"speaker\": \"agent\"\n }\n ],\n \"usage\": {\n \"type\": \"duration\",\n \"seconds\": 27\n }\n}\n" }, { "title": "Streaming", "request": { "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F model=\"gpt-4o-mini-transcribe\" \\\n -F stream=true\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\nstream = client.audio.transcriptions.create(\n file=audio_file,\n model=\"gpt-4o-mini-transcribe\",\n stream=True\n)\n\nfor event in stream:\n print(event)\n", "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst stream = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"gpt-4o-mini-transcribe\",\n stream: true,\n});\n\nfor await (const event of stream) {\n console.log(event);\n}\n" }, "response": "data: {\"type\":\"transcript.text.delta\",\"delta\":\"I\",\"logprobs\":[{\"token\":\"I\",\"logprob\":-0.00007588794,\"bytes\":[73]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" see\",\"logprobs\":[{\"token\":\" see\",\"logprob\":-3.1281633e-7,\"bytes\":[32,115,101,101]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" skies\",\"logprobs\":[{\"token\":\" skies\",\"logprob\":-2.3392786e-6,\"bytes\":[32,115,107,105,101,115]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" of\",\"logprobs\":[{\"token\":\" of\",\"logprob\":-3.1281633e-7,\"bytes\":[32,111,102]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" blue\",\"logprobs\":[{\"token\":\" blue\",\"logprob\":-1.0280384e-6,\"bytes\":[32,98,108,117,101]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" and\",\"logprobs\":[{\"token\":\" and\",\"logprob\":-0.0005108566,\"bytes\":[32,97,110,100]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" clouds\",\"logprobs\":[{\"token\":\" clouds\",\"logprob\":-1.9361265e-7,\"bytes\":[32,99,108,111,117,100,115]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" of\",\"logprobs\":[{\"token\":\" of\",\"logprob\":-1.9361265e-7,\"bytes\":[32,111,102]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" white\",\"logprobs\":[{\"token\":\" white\",\"logprob\":-7.89631e-7,\"bytes\":[32,119,104,105,116,101]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\",\",\"logprobs\":[{\"token\":\",\",\"logprob\":-0.0014890312,\"bytes\":[44]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" the\",\"logprobs\":[{\"token\":\" the\",\"logprob\":-0.0110956915,\"bytes\":[32,116,104,101]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" bright\",\"logprobs\":[{\"token\":\" bright\",\"logprob\":0.0,\"bytes\":[32,98,114,105,103,104,116]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" blessed\",\"logprobs\":[{\"token\":\" blessed\",\"logprob\":-0.000045848617,\"bytes\":[32,98,108,101,115,115,101,100]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" days\",\"logprobs\":[{\"token\":\" days\",\"logprob\":-0.000010802739,\"bytes\":[32,100,97,121,115]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\",\",\"logprobs\":[{\"token\":\",\",\"logprob\":-0.00001700133,\"bytes\":[44]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" the\",\"logprobs\":[{\"token\":\" the\",\"logprob\":-0.0000118755715,\"bytes\":[32,116,104,101]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" dark\",\"logprobs\":[{\"token\":\" dark\",\"logprob\":-5.5122365e-7,\"bytes\":[32,100,97,114,107]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" sacred\",\"logprobs\":[{\"token\":\" sacred\",\"logprob\":-5.4385737e-6,\"bytes\":[32,115,97,99,114,101,100]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" nights\",\"logprobs\":[{\"token\":\" nights\",\"logprob\":-4.00813e-6,\"bytes\":[32,110,105,103,104,116,115]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\",\",\"logprobs\":[{\"token\":\",\",\"logprob\":-0.0036910512,\"bytes\":[44]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" and\",\"logprobs\":[{\"token\":\" and\",\"logprob\":-0.0031903093,\"bytes\":[32,97,110,100]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" I\",\"logprobs\":[{\"token\":\" I\",\"logprob\":-1.504853e-6,\"bytes\":[32,73]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" think\",\"logprobs\":[{\"token\":\" think\",\"logprob\":-4.3202e-7,\"bytes\":[32,116,104,105,110,107]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" to\",\"logprobs\":[{\"token\":\" to\",\"logprob\":-1.9361265e-7,\"bytes\":[32,116,111]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" myself\",\"logprobs\":[{\"token\":\" myself\",\"logprob\":-1.7432603e-6,\"bytes\":[32,109,121,115,101,108,102]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\",\",\"logprobs\":[{\"token\":\",\",\"logprob\":-0.29254505,\"bytes\":[44]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" what\",\"logprobs\":[{\"token\":\" what\",\"logprob\":-0.016815351,\"bytes\":[32,119,104,97,116]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" a\",\"logprobs\":[{\"token\":\" a\",\"logprob\":-3.1281633e-7,\"bytes\":[32,97]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" wonderful\",\"logprobs\":[{\"token\":\" wonderful\",\"logprob\":-2.1008714e-6,\"bytes\":[32,119,111,110,100,101,114,102,117,108]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\" world\",\"logprobs\":[{\"token\":\" world\",\"logprob\":-8.180258e-6,\"bytes\":[32,119,111,114,108,100]}]}\n\ndata: {\"type\":\"transcript.text.delta\",\"delta\":\".\",\"logprobs\":[{\"token\":\".\",\"logprob\":-0.014231676,\"bytes\":[46]}]}\n\ndata: {\"type\":\"transcript.text.done\",\"text\":\"I see skies of blue and clouds of white, the bright blessed days, the dark sacred nights, and I think to myself, what a wonderful world.\",\"logprobs\":[{\"token\":\"I\",\"logprob\":-0.00007588794,\"bytes\":[73]},{\"token\":\" see\",\"logprob\":-3.1281633e-7,\"bytes\":[32,115,101,101]},{\"token\":\" skies\",\"logprob\":-2.3392786e-6,\"bytes\":[32,115,107,105,101,115]},{\"token\":\" of\",\"logprob\":-3.1281633e-7,\"bytes\":[32,111,102]},{\"token\":\" blue\",\"logprob\":-1.0280384e-6,\"bytes\":[32,98,108,117,101]},{\"token\":\" and\",\"logprob\":-0.0005108566,\"bytes\":[32,97,110,100]},{\"token\":\" clouds\",\"logprob\":-1.9361265e-7,\"bytes\":[32,99,108,111,117,100,115]},{\"token\":\" of\",\"logprob\":-1.9361265e-7,\"bytes\":[32,111,102]},{\"token\":\" white\",\"logprob\":-7.89631e-7,\"bytes\":[32,119,104,105,116,101]},{\"token\":\",\",\"logprob\":-0.0014890312,\"bytes\":[44]},{\"token\":\" the\",\"logprob\":-0.0110956915,\"bytes\":[32,116,104,101]},{\"token\":\" bright\",\"logprob\":0.0,\"bytes\":[32,98,114,105,103,104,116]},{\"token\":\" blessed\",\"logprob\":-0.000045848617,\"bytes\":[32,98,108,101,115,115,101,100]},{\"token\":\" days\",\"logprob\":-0.000010802739,\"bytes\":[32,100,97,121,115]},{\"token\":\",\",\"logprob\":-0.00001700133,\"bytes\":[44]},{\"token\":\" the\",\"logprob\":-0.0000118755715,\"bytes\":[32,116,104,101]},{\"token\":\" dark\",\"logprob\":-5.5122365e-7,\"bytes\":[32,100,97,114,107]},{\"token\":\" sacred\",\"logprob\":-5.4385737e-6,\"bytes\":[32,115,97,99,114,101,100]},{\"token\":\" nights\",\"logprob\":-4.00813e-6,\"bytes\":[32,110,105,103,104,116,115]},{\"token\":\",\",\"logprob\":-0.0036910512,\"bytes\":[44]},{\"token\":\" and\",\"logprob\":-0.0031903093,\"bytes\":[32,97,110,100]},{\"token\":\" I\",\"logprob\":-1.504853e-6,\"bytes\":[32,73]},{\"token\":\" think\",\"logprob\":-4.3202e-7,\"bytes\":[32,116,104,105,110,107]},{\"token\":\" to\",\"logprob\":-1.9361265e-7,\"bytes\":[32,116,111]},{\"token\":\" myself\",\"logprob\":-1.7432603e-6,\"bytes\":[32,109,121,115,101,108,102]},{\"token\":\",\",\"logprob\":-0.29254505,\"bytes\":[44]},{\"token\":\" what\",\"logprob\":-0.016815351,\"bytes\":[32,119,104,97,116]},{\"token\":\" a\",\"logprob\":-3.1281633e-7,\"bytes\":[32,97]},{\"token\":\" wonderful\",\"logprob\":-2.1008714e-6,\"bytes\":[32,119,111,110,100,101,114,102,117,108]},{\"token\":\" world\",\"logprob\":-8.180258e-6,\"bytes\":[32,119,111,114,108,100]},{\"token\":\".\",\"logprob\":-0.014231676,\"bytes\":[46]}],\"usage\":{\"input_tokens\":14,\"input_token_details\":{\"text_tokens\":0,\"audio_tokens\":14},\"output_tokens\":45,\"total_tokens\":59}}\n" }, { "title": "Logprobs", "request": { "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F \"include[]=logprobs\" \\\n -F model=\"gpt-4o-transcribe\" \\\n -F response_format=\"json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.transcriptions.create(\n file=audio_file,\n model=\"gpt-4o-transcribe\",\n response_format=\"json\",\n include=[\"logprobs\"]\n)\n\nprint(transcript)\n", "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const transcription = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"gpt-4o-transcribe\",\n response_format: \"json\",\n include: [\"logprobs\"]\n });\n\n console.log(transcription);\n}\nmain();\n" }, "response": "{\n \"text\": \"Hey, my knee is hurting and I want to see the doctor tomorrow ideally.\",\n \"logprobs\": [\n { \"token\": \"Hey\", \"logprob\": -1.0415299, \"bytes\": [72, 101, 121] },\n { \"token\": \",\", \"logprob\": -9.805982e-5, \"bytes\": [44] },\n { \"token\": \" my\", \"logprob\": -0.00229799, \"bytes\": [32, 109, 121] },\n {\n \"token\": \" knee\",\n \"logprob\": -4.7159858e-5,\n \"bytes\": [32, 107, 110, 101, 101]\n },\n { \"token\": \" is\", \"logprob\": -0.043909557, \"bytes\": [32, 105, 115] },\n {\n \"token\": \" hurting\",\n \"logprob\": -1.1041146e-5,\n \"bytes\": [32, 104, 117, 114, 116, 105, 110, 103]\n },\n { \"token\": \" and\", \"logprob\": -0.011076359, \"bytes\": [32, 97, 110, 100] },\n { \"token\": \" I\", \"logprob\": -5.3193703e-6, \"bytes\": [32, 73] },\n {\n \"token\": \" want\",\n \"logprob\": -0.0017156356,\n \"bytes\": [32, 119, 97, 110, 116]\n },\n { \"token\": \" to\", \"logprob\": -7.89631e-7, \"bytes\": [32, 116, 111] },\n { \"token\": \" see\", \"logprob\": -5.5122365e-7, \"bytes\": [32, 115, 101, 101] },\n { \"token\": \" the\", \"logprob\": -0.0040786397, \"bytes\": [32, 116, 104, 101] },\n {\n \"token\": \" doctor\",\n \"logprob\": -2.3392786e-6,\n \"bytes\": [32, 100, 111, 99, 116, 111, 114]\n },\n {\n \"token\": \" tomorrow\",\n \"logprob\": -7.89631e-7,\n \"bytes\": [32, 116, 111, 109, 111, 114, 114, 111, 119]\n },\n {\n \"token\": \" ideally\",\n \"logprob\": -0.5800861,\n \"bytes\": [32, 105, 100, 101, 97, 108, 108, 121]\n },\n { \"token\": \".\", \"logprob\": -0.00011093382, \"bytes\": [46] }\n ],\n \"usage\": {\n \"type\": \"tokens\",\n \"input_tokens\": 14,\n \"input_token_details\": {\n \"text_tokens\": 0,\n \"audio_tokens\": 14\n },\n \"output_tokens\": 45,\n \"total_tokens\": 59\n }\n}\n" }, { "title": "Word timestamps", "request": { "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F \"timestamp_granularities[]=word\" \\\n -F model=\"whisper-1\" \\\n -F response_format=\"verbose_json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.transcriptions.create(\n file=audio_file,\n model=\"whisper-1\",\n response_format=\"verbose_json\",\n timestamp_granularities=[\"word\"]\n)\n\nprint(transcript.words)\n", "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const transcription = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"whisper-1\",\n response_format: \"verbose_json\",\n timestamp_granularities: [\"word\"]\n });\n\n console.log(transcription.text);\n}\nmain();\n", "csharp": "using System;\n\nusing OpenAI.Audio;\n\nstring audioFilePath = \"audio.mp3\";\n\nAudioClient client = new(\n model: \"whisper-1\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nAudioTranscriptionOptions options = new()\n{\n ResponseFormat = AudioTranscriptionFormat.Verbose,\n TimestampGranularities = AudioTimestampGranularities.Word,\n};\n\nAudioTranscription transcription = client.TranscribeAudio(audioFilePath, options);\n\nConsole.WriteLine($\"{transcription.Text}\");\n" }, "response": "{\n \"task\": \"transcribe\",\n \"language\": \"english\",\n \"duration\": 8.470000267028809,\n \"text\": \"The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.\",\n \"words\": [\n {\n \"word\": \"The\",\n \"start\": 0.0,\n \"end\": 0.23999999463558197\n },\n ...\n {\n \"word\": \"volleyball\",\n \"start\": 7.400000095367432,\n \"end\": 7.900000095367432\n }\n ],\n \"usage\": {\n \"type\": \"duration\",\n \"seconds\": 9\n }\n}\n" }, { "title": "Segment timestamps", "request": { "curl": "curl https://api.openai.com/v1/audio/transcriptions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/audio.mp3\" \\\n -F \"timestamp_granularities[]=segment\" \\\n -F model=\"whisper-1\" \\\n -F response_format=\"verbose_json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.transcriptions.create(\n file=audio_file,\n model=\"whisper-1\",\n response_format=\"verbose_json\",\n timestamp_granularities=[\"segment\"]\n)\n\nprint(transcript.words)\n", "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const transcription = await openai.audio.transcriptions.create({\n file: fs.createReadStream(\"audio.mp3\"),\n model: \"whisper-1\",\n response_format: \"verbose_json\",\n timestamp_granularities: [\"segment\"]\n });\n\n console.log(transcription.text);\n}\nmain();\n", "csharp": "using System;\n\nusing OpenAI.Audio;\n\nstring audioFilePath = \"audio.mp3\";\n\nAudioClient client = new(\n model: \"whisper-1\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nAudioTranscriptionOptions options = new()\n{\n ResponseFormat = AudioTranscriptionFormat.Verbose,\n TimestampGranularities = AudioTimestampGranularities.Segment,\n};\n\nAudioTranscription transcription = client.TranscribeAudio(audioFilePath, options);\n\nConsole.WriteLine($\"{transcription.Text}\");\n" }, "response": "{\n \"task\": \"transcribe\",\n \"language\": \"english\",\n \"duration\": 8.470000267028809,\n \"text\": \"The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.\",\n \"segments\": [\n {\n \"id\": 0,\n \"seek\": 0,\n \"start\": 0.0,\n \"end\": 3.319999933242798,\n \"text\": \" The beach was a popular spot on a hot summer day.\",\n \"tokens\": [\n 50364, 440, 7534, 390, 257, 3743, 4008, 322, 257, 2368, 4266, 786, 13, 50530\n ],\n \"temperature\": 0.0,\n \"avg_logprob\": -0.2860786020755768,\n \"compression_ratio\": 1.2363636493682861,\n \"no_speech_prob\": 0.00985979475080967\n },\n ...\n ],\n \"usage\": {\n \"type\": \"duration\",\n \"seconds\": 9\n }\n}\n" } ] } } }, "/audio/translations": { "post": { "operationId": "createTranslation", "tags": [ "Audio" ], "summary": "Translates audio into English.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateTranslationRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateTranslationResponseJson" }, { "$ref": "#/components/schemas/CreateTranslationResponseVerboseJson" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create translation", "group": "audio", "examples": { "request": { "curl": "curl https://api.openai.com/v1/audio/translations \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: multipart/form-data\" \\\n -F file=\"@/path/to/file/german.m4a\" \\\n -F model=\"whisper-1\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\naudio_file = open(\"speech.mp3\", \"rb\")\ntranscript = client.audio.translations.create(\n model=\"whisper-1\",\n file=audio_file\n)\n", "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const translation = await openai.audio.translations.create({\n file: fs.createReadStream(\"speech.mp3\"),\n model: \"whisper-1\",\n });\n\n console.log(translation.text);\n}\nmain();\n", "csharp": "using System;\n\nusing OpenAI.Audio;\n\nstring audioFilePath = \"audio.mp3\";\n\nAudioClient client = new(\n model: \"whisper-1\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nAudioTranscription transcription = client.TranscribeAudio(audioFilePath);\n\nConsole.WriteLine($\"{transcription.Text}\");\n" }, "response": "{\n \"text\": \"Hello, my name is Wolfgang and I come from Germany. Where are you heading today?\"\n}\n" } } } }, "/audio/voice_consents": { "post": { "operationId": "createVoiceConsent", "tags": [ "Audio" ], "summary": "Upload a voice consent recording.", "description": "Upload a consent recording that authorizes creation of a custom voice.\n\nSee the [custom voices guide](/docs/guides/text-to-speech#custom-voices) for requirements and best practices. Custom voices are limited to eligible customers.\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateVoiceConsentRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceConsentResource" } } } } }, "x-oaiMeta": { "name": "Create voice consent", "group": "audio", "examples": { "request": { "curl": "curl https://api.openai.com/v1/audio/voice_consents \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"name=John Doe\" \\\n -F \"language=en-US\" \\\n -F \"recording=@$HOME/consent_recording.wav;type=audio/x-wav\"\n" } } } }, "get": { "operationId": "listVoiceConsents", "tags": [ "Audio" ], "summary": "Returns a list of voice consent recordings.", "description": "List consent recordings available to your organization for creating custom voices.\n\nSee the [custom voices guide](/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers.\n", "parameters": [ { "in": "query", "name": "after", "required": false, "schema": { "type": "string" }, "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.\n" }, { "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceConsentListResource" } } } } }, "x-oaiMeta": { "name": "List voice consents", "group": "audio", "examples": { "request": { "curl": "curl https://api.openai.com/v1/audio/voice_consents?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" } } } } }, "/audio/voice_consents/{consent_id}": { "get": { "operationId": "getVoiceConsent", "tags": [ "Audio" ], "summary": "Retrieves a voice consent recording.", "description": "Retrieve consent recording metadata used for creating custom voices.\n\nSee the [custom voices guide](/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers.\n", "parameters": [ { "in": "path", "name": "consent_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the consent recording to retrieve." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceConsentResource" } } } } }, "x-oaiMeta": { "name": "Retrieve voice consent", "group": "audio", "examples": { "request": { "curl": "curl https://api.openai.com/v1/audio/voice_consents/cons_1234 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" } } } }, "post": { "operationId": "updateVoiceConsent", "tags": [ "Audio" ], "summary": "Updates a voice consent recording (metadata only).", "description": "Update consent recording metadata used for creating custom voices. This endpoint updates metadata only and does not replace the underlying audio.\n\nSee the [custom voices guide](/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers.\n", "parameters": [ { "in": "path", "name": "consent_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the consent recording to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVoiceConsentRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceConsentResource" } } } } }, "x-oaiMeta": { "name": "Update voice consent", "group": "audio", "examples": { "request": { "curl": "curl https://api.openai.com/v1/audio/voice_consents/cons_1234 \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"John Doe\"\n }'\n" } } } }, "delete": { "operationId": "deleteVoiceConsent", "tags": [ "Audio" ], "summary": "Deletes a voice consent recording.", "description": "Delete a consent recording that was uploaded for creating custom voices.\n\nSee the [custom voices guide](/docs/guides/text-to-speech#custom-voices). Custom voices are limited to eligible customers.\n", "parameters": [ { "in": "path", "name": "consent_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the consent recording to delete." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceConsentDeletedResource" } } } } }, "x-oaiMeta": { "name": "Delete voice consent", "group": "audio", "examples": { "request": { "curl": "curl https://api.openai.com/v1/audio/voice_consents/cons_1234 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" } } } } }, "/audio/voices": { "post": { "operationId": "createVoice", "tags": [ "Audio" ], "summary": "Creates a custom voice.", "description": "Create a custom voice you can use for audio output (for example, in Text-to-Speech and the Realtime API). This requires an audio sample and a previously uploaded consent recording.\n\nSee the [custom voices guide](/docs/guides/text-to-speech#custom-voices) for requirements and best practices. Custom voices are limited to eligible customers.\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateVoiceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceResource" } } } } }, "x-oaiMeta": { "name": "Create voice", "group": "audio", "examples": { "request": { "curl": "curl https://api.openai.com/v1/audio/voices \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"name=My new voice\" \\\n -F \"consent=cons_1234\" \\\n -F \"audio_sample=@$HOME/audio_sample.wav;type=audio/x-wav\"\n" } } } } }, "/batches": { "post": { "summary": "Creates and executes a batch from an uploaded file of requests", "operationId": "createBatch", "tags": [ "Batch" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBatchRequest" } } } }, "responses": { "200": { "description": "Batch created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } } }, "x-oaiMeta": { "name": "Create batch", "group": "batch", "examples": { "request": { "curl": "curl https://api.openai.com/v1/batches \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input_file_id\": \"file-abc123\",\n \"endpoint\": \"/v1/chat/completions\",\n \"completion_window\": \"24h\"\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.batches.create(\n input_file_id=\"file-abc123\",\n endpoint=\"/v1/chat/completions\",\n completion_window=\"24h\"\n)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const batch = await openai.batches.create({\n input_file_id: \"file-abc123\",\n endpoint: \"/v1/chat/completions\",\n completion_window: \"24h\"\n });\n\n console.log(batch);\n}\n\nmain();\n" }, "response": "{\n \"id\": \"batch_abc123\",\n \"object\": \"batch\",\n \"endpoint\": \"/v1/chat/completions\",\n \"errors\": null,\n \"input_file_id\": \"file-abc123\",\n \"completion_window\": \"24h\",\n \"status\": \"validating\",\n \"output_file_id\": null,\n \"error_file_id\": null,\n \"created_at\": 1711471533,\n \"in_progress_at\": null,\n \"expires_at\": null,\n \"finalizing_at\": null,\n \"completed_at\": null,\n \"failed_at\": null,\n \"expired_at\": null,\n \"cancelling_at\": null,\n \"cancelled_at\": null,\n \"request_counts\": {\n \"total\": 0,\n \"completed\": 0,\n \"failed\": 0\n },\n \"metadata\": {\n \"customer_id\": \"user_123456789\",\n \"batch_description\": \"Nightly eval job\",\n }\n}\n" } } }, "get": { "operationId": "listBatches", "tags": [ "Batch" ], "summary": "List your organization's batches.", "parameters": [ { "in": "query", "name": "after", "required": false, "schema": { "type": "string" }, "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.\n" }, { "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Batch listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBatchesResponse" } } } } }, "x-oaiMeta": { "name": "List batches", "group": "batch", "examples": { "request": { "curl": "curl https://api.openai.com/v1/batches?limit=2 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.batches.list()\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.batches.list();\n\n for await (const batch of list) {\n console.log(batch);\n }\n}\n\nmain();\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"batch_abc123\",\n \"object\": \"batch\",\n \"endpoint\": \"/v1/chat/completions\",\n \"errors\": null,\n \"input_file_id\": \"file-abc123\",\n \"completion_window\": \"24h\",\n \"status\": \"completed\",\n \"output_file_id\": \"file-cvaTdG\",\n \"error_file_id\": \"file-HOWS94\",\n \"created_at\": 1711471533,\n \"in_progress_at\": 1711471538,\n \"expires_at\": 1711557933,\n \"finalizing_at\": 1711493133,\n \"completed_at\": 1711493163,\n \"failed_at\": null,\n \"expired_at\": null,\n \"cancelling_at\": null,\n \"cancelled_at\": null,\n \"request_counts\": {\n \"total\": 100,\n \"completed\": 95,\n \"failed\": 5\n },\n \"metadata\": {\n \"customer_id\": \"user_123456789\",\n \"batch_description\": \"Nightly job\",\n }\n },\n { ... },\n ],\n \"first_id\": \"batch_abc123\",\n \"last_id\": \"batch_abc456\",\n \"has_more\": true\n}\n" } } } }, "/batches/{batch_id}": { "get": { "operationId": "retrieveBatch", "tags": [ "Batch" ], "summary": "Retrieves a batch.", "parameters": [ { "in": "path", "name": "batch_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the batch to retrieve." } ], "responses": { "200": { "description": "Batch retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } } }, "x-oaiMeta": { "name": "Retrieve batch", "group": "batch", "examples": { "request": { "curl": "curl https://api.openai.com/v1/batches/batch_abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.batches.retrieve(\"batch_abc123\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const batch = await openai.batches.retrieve(\"batch_abc123\");\n\n console.log(batch);\n}\n\nmain();\n" }, "response": "{\n \"id\": \"batch_abc123\",\n \"object\": \"batch\",\n \"endpoint\": \"/v1/completions\",\n \"errors\": null,\n \"input_file_id\": \"file-abc123\",\n \"completion_window\": \"24h\",\n \"status\": \"completed\",\n \"output_file_id\": \"file-cvaTdG\",\n \"error_file_id\": \"file-HOWS94\",\n \"created_at\": 1711471533,\n \"in_progress_at\": 1711471538,\n \"expires_at\": 1711557933,\n \"finalizing_at\": 1711493133,\n \"completed_at\": 1711493163,\n \"failed_at\": null,\n \"expired_at\": null,\n \"cancelling_at\": null,\n \"cancelled_at\": null,\n \"request_counts\": {\n \"total\": 100,\n \"completed\": 95,\n \"failed\": 5\n },\n \"metadata\": {\n \"customer_id\": \"user_123456789\",\n \"batch_description\": \"Nightly eval job\",\n }\n}\n" } } } }, "/batches/{batch_id}/cancel": { "post": { "operationId": "cancelBatch", "tags": [ "Batch" ], "summary": "Cancels an in-progress batch. The batch will be in status `cancelling` for up to 10 minutes, before changing to `cancelled`, where it will have partial results (if any) available in the output file.", "parameters": [ { "in": "path", "name": "batch_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the batch to cancel." } ], "responses": { "200": { "description": "Batch is cancelling. Returns the cancelling batch's details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } } }, "x-oaiMeta": { "name": "Cancel batch", "group": "batch", "examples": { "request": { "curl": "curl https://api.openai.com/v1/batches/batch_abc123/cancel \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -X POST\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.batches.cancel(\"batch_abc123\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const batch = await openai.batches.cancel(\"batch_abc123\");\n\n console.log(batch);\n}\n\nmain();\n" }, "response": "{\n \"id\": \"batch_abc123\",\n \"object\": \"batch\",\n \"endpoint\": \"/v1/chat/completions\",\n \"errors\": null,\n \"input_file_id\": \"file-abc123\",\n \"completion_window\": \"24h\",\n \"status\": \"cancelling\",\n \"output_file_id\": null,\n \"error_file_id\": null,\n \"created_at\": 1711471533,\n \"in_progress_at\": 1711471538,\n \"expires_at\": 1711557933,\n \"finalizing_at\": null,\n \"completed_at\": null,\n \"failed_at\": null,\n \"expired_at\": null,\n \"cancelling_at\": 1711475133,\n \"cancelled_at\": null,\n \"request_counts\": {\n \"total\": 100,\n \"completed\": 23,\n \"failed\": 1\n },\n \"metadata\": {\n \"customer_id\": \"user_123456789\",\n \"batch_description\": \"Nightly eval job\",\n }\n}\n" } } } }, "/chat/completions": { "get": { "operationId": "listChatCompletions", "tags": [ "Chat" ], "summary": "List stored Chat Completions. Only Chat Completions that have been stored\nwith the `store` parameter set to `true` will be returned.\n", "parameters": [ { "name": "model", "in": "query", "description": "The model used to generate the Chat Completions.", "required": false, "schema": { "type": "string" } }, { "name": "metadata", "in": "query", "description": "A list of metadata keys to filter the Chat Completions by. Example:\n\n`metadata[key1]=value1&metadata[key2]=value2`\n", "required": false, "schema": { "$ref": "#/components/schemas/Metadata" } }, { "name": "after", "in": "query", "description": "Identifier for the last chat completion from the previous pagination request.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of Chat Completions to retrieve.", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "order", "in": "query", "description": "Sort order for Chat Completions by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "A list of Chat Completions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionList" } } } } }, "x-oaiMeta": { "name": "List Chat Completions", "group": "chat", "path": "list", "examples": { "request": { "curl": "curl https://api.openai.com/v1/chat/completions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletions = client.chat.completions.list()\nprint(completions)\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"chat.completion\",\n \"id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2\",\n \"model\": \"gpt-5.4\",\n \"created\": 1738960610,\n \"request_id\": \"req_ded8ab984ec4bf840f37566c1011c417\",\n \"tool_choice\": null,\n \"usage\": {\n \"total_tokens\": 31,\n \"completion_tokens\": 18,\n \"prompt_tokens\": 13\n },\n \"seed\": 4944116822809979520,\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"presence_penalty\": 0.0,\n \"frequency_penalty\": 0.0,\n \"system_fingerprint\": \"fp_50cad350e4\",\n \"input_user\": null,\n \"service_tier\": \"default\",\n \"tools\": null,\n \"metadata\": {},\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"content\": \"Mind of circuits hum, \\nLearning patterns in silence— \\nFuture's quiet spark.\",\n \"role\": \"assistant\",\n \"tool_calls\": null,\n \"function_call\": null\n },\n \"finish_reason\": \"stop\",\n \"logprobs\": null\n }\n ],\n \"response_format\": null\n }\n ],\n \"first_id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2\",\n \"last_id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2\",\n \"has_more\": false\n}\n" } } }, "post": { "operationId": "createChatCompletion", "tags": [ "Chat" ], "summary": "**Starting a new project?** We recommend trying [Responses](/docs/api-reference/responses)\nto take advantage of the latest OpenAI platform features. Compare\n[Chat Completions with Responses](/docs/guides/responses-vs-chat-completions?api-mode=responses).\n\n---\n\nCreates a model response for the given chat conversation. Learn more in the\n[text generation](/docs/guides/text-generation), [vision](/docs/guides/vision),\nand [audio](/docs/guides/audio) guides.\n\nParameter support can differ depending on the model used to generate the\nresponse, particularly for newer reasoning models. Parameters that are only\nsupported for reasoning models are noted below. For the current state of\nunsupported parameters in reasoning models,\n[refer to the reasoning guide](/docs/guides/reasoning).\n\nReturns a chat completion object, or a streamed sequence of chat completion\nchunk objects if the request is streamed.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionStreamResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create chat completion", "group": "chat", "path": "create", "examples": [ { "title": "Default", "request": { "curl": "curl https://api.openai.com/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"VAR_chat_model_id\",\n \"messages\": [\n {\n \"role\": \"developer\",\n \"content\": \"You are a helpful assistant.\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Hello!\"\n }\n ]\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletion = client.chat.completions.create(\n model=\"VAR_chat_model_id\",\n messages=[\n {\"role\": \"developer\", \"content\": \"You are a helpful assistant.\"},\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ]\n)\n\nprint(completion.choices[0].message)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const completion = await openai.chat.completions.create({\n messages: [{ role: \"developer\", content: \"You are a helpful assistant.\" }],\n model: \"VAR_chat_model_id\",\n store: true,\n });\n\n console.log(completion.choices[0]);\n}\n\nmain();\n", "csharp": "using System;\nusing System.Collections.Generic;\n\nusing OpenAI.Chat;\n\nChatClient client = new(\n model: \"gpt-5.4\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nList messages =\n[\n new SystemChatMessage(\"You are a helpful assistant.\"),\n new UserChatMessage(\"Hello!\")\n];\n\nChatCompletion completion = client.CompleteChat(messages);\n\nConsole.WriteLine(completion.Content[0].Text);\n" }, "response": "{\n \"id\": \"chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT\",\n \"object\": \"chat.completion\",\n \"created\": 1741569952,\n \"model\": \"gpt-5.4\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"Hello! How can I assist you today?\",\n \"refusal\": null,\n \"annotations\": []\n },\n \"logprobs\": null,\n \"finish_reason\": \"stop\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 19,\n \"completion_tokens\": 10,\n \"total_tokens\": 29,\n \"prompt_tokens_details\": {\n \"cached_tokens\": 0,\n \"audio_tokens\": 0\n },\n \"completion_tokens_details\": {\n \"reasoning_tokens\": 0,\n \"audio_tokens\": 0,\n \"accepted_prediction_tokens\": 0,\n \"rejected_prediction_tokens\": 0\n }\n },\n \"service_tier\": \"default\"\n}\n" }, { "title": "Image input", "request": { "curl": "curl https://api.openai.com/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-5.4\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"What is in this image?\"\n },\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\"\n }\n }\n ]\n }\n ],\n \"max_tokens\": 300\n }'\n", "python": "from openai import OpenAI\n\nclient = OpenAI()\n\nresponse = client.chat.completions.create(\n model=\"gpt-5.4\",\n messages=[\n {\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"text\", \"text\": \"What's in this image?\"},\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\",\n }\n },\n ],\n }\n ],\n max_tokens=300,\n)\n\nprint(response.choices[0])\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.chat.completions.create({\n model: \"gpt-5.4\",\n messages: [\n {\n role: \"user\",\n content: [\n { type: \"text\", text: \"What's in this image?\" },\n {\n type: \"image_url\",\n image_url: {\n \"url\": \"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\",\n },\n }\n ],\n },\n ],\n });\n console.log(response.choices[0]);\n}\nmain();\n", "csharp": "using System;\nusing System.Collections.Generic;\n\nusing OpenAI.Chat;\n\nChatClient client = new(\n model: \"gpt-5.4\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nList messages =\n[\n new UserChatMessage(\n [\n ChatMessageContentPart.CreateTextPart(\"What's in this image?\"),\n ChatMessageContentPart.CreateImagePart(new Uri(\"https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg\"))\n ])\n];\n\nChatCompletion completion = client.CompleteChat(messages);\n\nConsole.WriteLine(completion.Content[0].Text);\n" }, "response": "{\n \"id\": \"chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG\",\n \"object\": \"chat.completion\",\n \"created\": 1741570283,\n \"model\": \"gpt-5.4\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.\",\n \"refusal\": null,\n \"annotations\": []\n },\n \"logprobs\": null,\n \"finish_reason\": \"stop\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 1117,\n \"completion_tokens\": 46,\n \"total_tokens\": 1163,\n \"prompt_tokens_details\": {\n \"cached_tokens\": 0,\n \"audio_tokens\": 0\n },\n \"completion_tokens_details\": {\n \"reasoning_tokens\": 0,\n \"audio_tokens\": 0,\n \"accepted_prediction_tokens\": 0,\n \"rejected_prediction_tokens\": 0\n }\n },\n \"service_tier\": \"default\"\n}\n" }, { "title": "Streaming", "request": { "curl": "curl https://api.openai.com/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"VAR_chat_model_id\",\n \"messages\": [\n {\n \"role\": \"developer\",\n \"content\": \"You are a helpful assistant.\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Hello!\"\n }\n ],\n \"stream\": true\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletion = client.chat.completions.create(\n model=\"VAR_chat_model_id\",\n messages=[\n {\"role\": \"developer\", \"content\": \"You are a helpful assistant.\"},\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ],\n stream=True\n)\n\nfor chunk in completion:\n print(chunk.choices[0].delta)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const completion = await openai.chat.completions.create({\n model: \"VAR_chat_model_id\",\n messages: [\n {\"role\": \"developer\", \"content\": \"You are a helpful assistant.\"},\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ],\n stream: true,\n });\n\n for await (const chunk of completion) {\n console.log(chunk.choices[0].delta.content);\n }\n}\n\nmain();\n", "csharp": "using System;\nusing System.ClientModel;\nusing System.Collections.Generic;\nusing System.Threading.Tasks;\n\nusing OpenAI.Chat;\n\nChatClient client = new(\n model: \"gpt-5.4\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nList messages =\n[\n new SystemChatMessage(\"You are a helpful assistant.\"),\n new UserChatMessage(\"Hello!\")\n];\n\nAsyncCollectionResult completionUpdates = client.CompleteChatStreamingAsync(messages);\n\nawait foreach (StreamingChatCompletionUpdate completionUpdate in completionUpdates)\n{\n if (completionUpdate.ContentUpdate.Count > 0)\n {\n Console.Write(completionUpdate.ContentUpdate[0].Text);\n }\n}\n" }, "response": "{\"id\":\"chatcmpl-123\",\"object\":\"chat.completion.chunk\",\"created\":1694268190,\"model\":\"gpt-4o-mini\", \"system_fingerprint\": \"fp_44709d6fcb\", \"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"\"},\"logprobs\":null,\"finish_reason\":null}]}\n\n{\"id\":\"chatcmpl-123\",\"object\":\"chat.completion.chunk\",\"created\":1694268190,\"model\":\"gpt-4o-mini\", \"system_fingerprint\": \"fp_44709d6fcb\", \"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\"},\"logprobs\":null,\"finish_reason\":null}]}\n\n....\n\n{\"id\":\"chatcmpl-123\",\"object\":\"chat.completion.chunk\",\"created\":1694268190,\"model\":\"gpt-4o-mini\", \"system_fingerprint\": \"fp_44709d6fcb\", \"choices\":[{\"index\":0,\"delta\":{},\"logprobs\":null,\"finish_reason\":\"stop\"}]}\n" }, { "title": "Functions", "request": { "curl": "curl https://api.openai.com/v1/chat/completions \\\n-H \"Content-Type: application/json\" \\\n-H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n-d '{\n \"model\": \"gpt-5.4\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"What is the weather like in Boston today?\"\n }\n ],\n \"tools\": [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"description\": \"Get the current weather in a given 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\": [\"celsius\", \"fahrenheit\"]\n }\n },\n \"required\": [\"location\"]\n }\n }\n }\n ],\n \"tool_choice\": \"auto\"\n}'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ntools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"description\": \"Get the current weather in a given 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\": {\"type\": \"string\", \"enum\": [\"celsius\", \"fahrenheit\"]},\n },\n \"required\": [\"location\"],\n },\n }\n }\n]\nmessages = [{\"role\": \"user\", \"content\": \"What's the weather like in Boston today?\"}]\ncompletion = client.chat.completions.create(\n model=\"VAR_chat_model_id\",\n messages=messages,\n tools=tools,\n tool_choice=\"auto\"\n)\n\nprint(completion)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const messages = [{\"role\": \"user\", \"content\": \"What's the weather like in Boston today?\"}];\n const tools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"description\": \"Get the current weather in a given 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\": {\"type\": \"string\", \"enum\": [\"celsius\", \"fahrenheit\"]},\n },\n \"required\": [\"location\"],\n },\n }\n }\n ];\n\n const response = await openai.chat.completions.create({\n model: \"gpt-5.4\",\n messages: messages,\n tools: tools,\n tool_choice: \"auto\",\n });\n\n console.log(response);\n}\n\nmain();\n", "csharp": "using System;\nusing System.Collections.Generic;\n\nusing OpenAI.Chat;\n\nChatClient client = new(\n model: \"gpt-5.4\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nChatTool getCurrentWeatherTool = ChatTool.CreateFunctionTool(\n functionName: \"get_current_weather\",\n functionDescription: \"Get the current weather in a given location\",\n functionParameters: BinaryData.FromString(\"\"\"\n {\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\": [ \"celsius\", \"fahrenheit\" ]\n }\n },\n \"required\": [ \"location\" ]\n }\n \"\"\")\n);\n\nList messages =\n[\n new UserChatMessage(\"What's the weather like in Boston today?\"),\n];\n\nChatCompletionOptions options = new()\n{\n Tools =\n {\n getCurrentWeatherTool\n },\n ToolChoice = ChatToolChoice.CreateAutoChoice(),\n};\n\nChatCompletion completion = client.CompleteChat(messages, options);\n" }, "response": "{\n \"id\": \"chatcmpl-abc123\",\n \"object\": \"chat.completion\",\n \"created\": 1699896916,\n \"model\": \"gpt-4o-mini\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": null,\n \"tool_calls\": [\n {\n \"id\": \"call_abc123\",\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"arguments\": \"{\\n\\\"location\\\": \\\"Boston, MA\\\"\\n}\"\n }\n }\n ]\n },\n \"logprobs\": null,\n \"finish_reason\": \"tool_calls\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 82,\n \"completion_tokens\": 17,\n \"total_tokens\": 99,\n \"completion_tokens_details\": {\n \"reasoning_tokens\": 0,\n \"accepted_prediction_tokens\": 0,\n \"rejected_prediction_tokens\": 0\n }\n }\n}\n" }, { "title": "Logprobs", "request": { "curl": "curl https://api.openai.com/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"VAR_chat_model_id\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello!\"\n }\n ],\n \"logprobs\": true,\n \"top_logprobs\": 2\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletion = client.chat.completions.create(\n model=\"VAR_chat_model_id\",\n messages=[\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ],\n logprobs=True,\n top_logprobs=2\n)\n\nprint(completion.choices[0].message)\nprint(completion.choices[0].logprobs)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const completion = await openai.chat.completions.create({\n messages: [{ role: \"user\", content: \"Hello!\" }],\n model: \"VAR_chat_model_id\",\n logprobs: true,\n top_logprobs: 2,\n });\n\n console.log(completion.choices[0]);\n}\n\nmain();\n", "csharp": "using System;\nusing System.Collections.Generic;\n\nusing OpenAI.Chat;\n\nChatClient client = new(\n model: \"gpt-5.4\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nList messages =\n[\n new UserChatMessage(\"Hello!\")\n];\n\nChatCompletionOptions options = new()\n{\n IncludeLogProbabilities = true,\n TopLogProbabilityCount = 2\n};\n\nChatCompletion completion = client.CompleteChat(messages, options);\n\nConsole.WriteLine(completion.Content[0].Text);\n" }, "response": "{\n \"id\": \"chatcmpl-123\",\n \"object\": \"chat.completion\",\n \"created\": 1702685778,\n \"model\": \"gpt-4o-mini\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"Hello! How can I assist you today?\"\n },\n \"logprobs\": {\n \"content\": [\n {\n \"token\": \"Hello\",\n \"logprob\": -0.31725305,\n \"bytes\": [72, 101, 108, 108, 111],\n \"top_logprobs\": [\n {\n \"token\": \"Hello\",\n \"logprob\": -0.31725305,\n \"bytes\": [72, 101, 108, 108, 111]\n },\n {\n \"token\": \"Hi\",\n \"logprob\": -1.3190403,\n \"bytes\": [72, 105]\n }\n ]\n },\n {\n \"token\": \"!\",\n \"logprob\": -0.02380986,\n \"bytes\": [\n 33\n ],\n \"top_logprobs\": [\n {\n \"token\": \"!\",\n \"logprob\": -0.02380986,\n \"bytes\": [33]\n },\n {\n \"token\": \" there\",\n \"logprob\": -3.787621,\n \"bytes\": [32, 116, 104, 101, 114, 101]\n }\n ]\n },\n {\n \"token\": \" How\",\n \"logprob\": -0.000054669687,\n \"bytes\": [32, 72, 111, 119],\n \"top_logprobs\": [\n {\n \"token\": \" How\",\n \"logprob\": -0.000054669687,\n \"bytes\": [32, 72, 111, 119]\n },\n {\n \"token\": \"<|end|>\",\n \"logprob\": -10.953937,\n \"bytes\": null\n }\n ]\n },\n {\n \"token\": \" can\",\n \"logprob\": -0.015801601,\n \"bytes\": [32, 99, 97, 110],\n \"top_logprobs\": [\n {\n \"token\": \" can\",\n \"logprob\": -0.015801601,\n \"bytes\": [32, 99, 97, 110]\n },\n {\n \"token\": \" may\",\n \"logprob\": -4.161023,\n \"bytes\": [32, 109, 97, 121]\n }\n ]\n },\n {\n \"token\": \" I\",\n \"logprob\": -3.7697225e-6,\n \"bytes\": [\n 32,\n 73\n ],\n \"top_logprobs\": [\n {\n \"token\": \" I\",\n \"logprob\": -3.7697225e-6,\n \"bytes\": [32, 73]\n },\n {\n \"token\": \" assist\",\n \"logprob\": -13.596657,\n \"bytes\": [32, 97, 115, 115, 105, 115, 116]\n }\n ]\n },\n {\n \"token\": \" assist\",\n \"logprob\": -0.04571125,\n \"bytes\": [32, 97, 115, 115, 105, 115, 116],\n \"top_logprobs\": [\n {\n \"token\": \" assist\",\n \"logprob\": -0.04571125,\n \"bytes\": [32, 97, 115, 115, 105, 115, 116]\n },\n {\n \"token\": \" help\",\n \"logprob\": -3.1089056,\n \"bytes\": [32, 104, 101, 108, 112]\n }\n ]\n },\n {\n \"token\": \" you\",\n \"logprob\": -5.4385737e-6,\n \"bytes\": [32, 121, 111, 117],\n \"top_logprobs\": [\n {\n \"token\": \" you\",\n \"logprob\": -5.4385737e-6,\n \"bytes\": [32, 121, 111, 117]\n },\n {\n \"token\": \" today\",\n \"logprob\": -12.807695,\n \"bytes\": [32, 116, 111, 100, 97, 121]\n }\n ]\n },\n {\n \"token\": \" today\",\n \"logprob\": -0.0040071653,\n \"bytes\": [32, 116, 111, 100, 97, 121],\n \"top_logprobs\": [\n {\n \"token\": \" today\",\n \"logprob\": -0.0040071653,\n \"bytes\": [32, 116, 111, 100, 97, 121]\n },\n {\n \"token\": \"?\",\n \"logprob\": -5.5247097,\n \"bytes\": [63]\n }\n ]\n },\n {\n \"token\": \"?\",\n \"logprob\": -0.0008108172,\n \"bytes\": [63],\n \"top_logprobs\": [\n {\n \"token\": \"?\",\n \"logprob\": -0.0008108172,\n \"bytes\": [63]\n },\n {\n \"token\": \"?\\n\",\n \"logprob\": -7.184561,\n \"bytes\": [63, 10]\n }\n ]\n }\n ]\n },\n \"finish_reason\": \"stop\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 9,\n \"completion_tokens\": 9,\n \"total_tokens\": 18,\n \"completion_tokens_details\": {\n \"reasoning_tokens\": 0,\n \"accepted_prediction_tokens\": 0,\n \"rejected_prediction_tokens\": 0\n }\n },\n \"system_fingerprint\": null\n}\n" } ] } } }, "/chat/completions/{completion_id}": { "get": { "operationId": "getChatCompletion", "tags": [ "Chat" ], "summary": "Get a stored chat completion. Only Chat Completions that have been created\nwith the `store` parameter set to `true` will be returned.\n", "parameters": [ { "in": "path", "name": "completion_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the chat completion to retrieve." } ], "responses": { "200": { "description": "A chat completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionResponse" } } } } }, "x-oaiMeta": { "name": "Get chat completion", "group": "chat", "examples": { "request": { "curl": "curl https://api.openai.com/v1/chat/completions/chatcmpl-abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletions = client.chat.completions.list()\nfirst_id = completions[0].id\nfirst_completion = client.chat.completions.retrieve(completion_id=first_id)\nprint(first_completion)\n" }, "response": "{\n \"object\": \"chat.completion\",\n \"id\": \"chatcmpl-abc123\",\n \"model\": \"gpt-4o-2024-08-06\",\n \"created\": 1738960610,\n \"request_id\": \"req_ded8ab984ec4bf840f37566c1011c417\",\n \"tool_choice\": null,\n \"usage\": {\n \"total_tokens\": 31,\n \"completion_tokens\": 18,\n \"prompt_tokens\": 13\n },\n \"seed\": 4944116822809979520,\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"presence_penalty\": 0.0,\n \"frequency_penalty\": 0.0,\n \"system_fingerprint\": \"fp_50cad350e4\",\n \"input_user\": null,\n \"service_tier\": \"default\",\n \"tools\": null,\n \"metadata\": {},\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"content\": \"Mind of circuits hum, \\nLearning patterns in silence— \\nFuture's quiet spark.\",\n \"role\": \"assistant\",\n \"tool_calls\": null,\n \"function_call\": null\n },\n \"finish_reason\": \"stop\",\n \"logprobs\": null\n }\n ],\n \"response_format\": null\n}\n" } } }, "post": { "operationId": "updateChatCompletion", "tags": [ "Chat" ], "summary": "Modify a stored chat completion. Only Chat Completions that have been\ncreated with the `store` parameter set to `true` can be modified. Currently,\nthe only supported modification is to update the `metadata` field.\n", "parameters": [ { "in": "path", "name": "completion_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the chat completion to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "metadata" ], "properties": { "metadata": { "$ref": "#/components/schemas/Metadata" } } } } } }, "responses": { "200": { "description": "A chat completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionResponse" } } } } }, "x-oaiMeta": { "name": "Update chat completion", "group": "chat", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/chat/completions/chat_abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"metadata\": {\"foo\": \"bar\"}}'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletions = client.chat.completions.list()\nfirst_id = completions[0].id\nupdated_completion = client.chat.completions.update(completion_id=first_id, request_body={\"metadata\": {\"foo\": \"bar\"}})\nprint(updated_completion)\n" }, "response": "{\n \"object\": \"chat.completion\",\n \"id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2\",\n \"model\": \"gpt-4o-2024-08-06\",\n \"created\": 1738960610,\n \"request_id\": \"req_ded8ab984ec4bf840f37566c1011c417\",\n \"tool_choice\": null,\n \"usage\": {\n \"total_tokens\": 31,\n \"completion_tokens\": 18,\n \"prompt_tokens\": 13\n },\n \"seed\": 4944116822809979520,\n \"top_p\": 1.0,\n \"temperature\": 1.0,\n \"presence_penalty\": 0.0,\n \"frequency_penalty\": 0.0,\n \"system_fingerprint\": \"fp_50cad350e4\",\n \"input_user\": null,\n \"service_tier\": \"default\",\n \"tools\": null,\n \"metadata\": {\n \"foo\": \"bar\"\n },\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"content\": \"Mind of circuits hum, \\nLearning patterns in silence— \\nFuture's quiet spark.\",\n \"role\": \"assistant\",\n \"tool_calls\": null,\n \"function_call\": null\n },\n \"finish_reason\": \"stop\",\n \"logprobs\": null\n }\n ],\n \"response_format\": null\n}\n" } } }, "delete": { "operationId": "deleteChatCompletion", "tags": [ "Chat" ], "summary": "Delete a stored chat completion. Only Chat Completions that have been\ncreated with the `store` parameter set to `true` can be deleted.\n", "parameters": [ { "in": "path", "name": "completion_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the chat completion to delete." } ], "responses": { "200": { "description": "The chat completion was deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionDeleted" } } } } }, "x-oaiMeta": { "name": "Delete chat completion", "group": "chat", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/chat/completions/chat_abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletions = client.chat.completions.list()\nfirst_id = completions[0].id\ndelete_response = client.chat.completions.delete(completion_id=first_id)\nprint(delete_response)\n" }, "response": "{\n \"object\": \"chat.completion.deleted\",\n \"id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2\",\n \"deleted\": true\n}\n" } } } }, "/chat/completions/{completion_id}/messages": { "get": { "operationId": "getChatCompletionMessages", "tags": [ "Chat" ], "summary": "Get the messages in a stored chat completion. Only Chat Completions that\nhave been created with the `store` parameter set to `true` will be\nreturned.\n", "parameters": [ { "in": "path", "name": "completion_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the chat completion to retrieve messages from." }, { "name": "after", "in": "query", "description": "Identifier for the last message from the previous pagination request.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of messages to retrieve.", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "order", "in": "query", "description": "Sort order for messages by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "A list of messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionMessageList" } } } } }, "x-oaiMeta": { "name": "Get chat messages", "group": "chat", "examples": { "request": { "curl": "curl https://api.openai.com/v1/chat/completions/chat_abc123/messages \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletions = client.chat.completions.list()\nfirst_id = completions[0].id\nfirst_completion = client.chat.completions.retrieve(completion_id=first_id)\nmessages = client.chat.completions.messages.list(completion_id=first_id)\nprint(messages)\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0\",\n \"role\": \"user\",\n \"content\": \"write a haiku about ai\",\n \"name\": null,\n \"content_parts\": null\n }\n ],\n \"first_id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0\",\n \"last_id\": \"chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0\",\n \"has_more\": false\n}\n" } } } }, "/completions": { "post": { "operationId": "createCompletion", "tags": [ "Completions" ], "summary": "Creates a completion for the provided prompt and parameters.\n\nReturns a completion object, or a sequence of completion objects if the request is streamed.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompletionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompletionResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create completion", "group": "completions", "legacy": true, "examples": [ { "title": "No streaming", "request": { "curl": "curl https://api.openai.com/v1/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"VAR_completion_model_id\",\n \"prompt\": \"Say this is a test\",\n \"max_tokens\": 7,\n \"temperature\": 0\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.completions.create(\n model=\"VAR_completion_model_id\",\n prompt=\"Say this is a test\",\n max_tokens=7,\n temperature=0\n)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const completion = await openai.completions.create({\n model: \"VAR_completion_model_id\",\n prompt: \"Say this is a test.\",\n max_tokens: 7,\n temperature: 0,\n });\n\n console.log(completion);\n}\nmain();" }, "response": "{\n \"id\": \"cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7\",\n \"object\": \"text_completion\",\n \"created\": 1589478378,\n \"model\": \"VAR_completion_model_id\",\n \"system_fingerprint\": \"fp_44709d6fcb\",\n \"choices\": [\n {\n \"text\": \"\\n\\nThis is indeed a test\",\n \"index\": 0,\n \"logprobs\": null,\n \"finish_reason\": \"length\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 5,\n \"completion_tokens\": 7,\n \"total_tokens\": 12\n }\n}\n" }, { "title": "Streaming", "request": { "curl": "curl https://api.openai.com/v1/completions \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"VAR_completion_model_id\",\n \"prompt\": \"Say this is a test\",\n \"max_tokens\": 7,\n \"temperature\": 0,\n \"stream\": true\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nfor chunk in client.completions.create(\n model=\"VAR_completion_model_id\",\n prompt=\"Say this is a test\",\n max_tokens=7,\n temperature=0,\n stream=True\n):\n print(chunk.choices[0].text)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const stream = await openai.completions.create({\n model: \"VAR_completion_model_id\",\n prompt: \"Say this is a test.\",\n stream: true,\n });\n\n for await (const chunk of stream) {\n console.log(chunk.choices[0].text)\n }\n}\nmain();" }, "response": "{\n \"id\": \"cmpl-7iA7iJjj8V2zOkCGvWF2hAkDWBQZe\",\n \"object\": \"text_completion\",\n \"created\": 1690759702,\n \"choices\": [\n {\n \"text\": \"This\",\n \"index\": 0,\n \"logprobs\": null,\n \"finish_reason\": null\n }\n ],\n \"model\": \"gpt-3.5-turbo-instruct\"\n \"system_fingerprint\": \"fp_44709d6fcb\",\n}\n" } ] } } }, "/containers": { "get": { "summary": "List Containers", "description": "Lists containers.", "operationId": "ListContainers", "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.\n", "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.\n", "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.\n", "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Filter results by container name.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List containers", "group": "containers", "path": "get", "examples": { "request": { "curl": "curl https://api.openai.com/v1/containers \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863\",\n \"object\": \"container\",\n \"created_at\": 1747844794,\n \"status\": \"running\",\n \"expires_after\": {\n \"anchor\": \"last_active_at\",\n \"minutes\": 20\n },\n \"last_active_at\": 1747844794,\n \"memory_limit\": \"4g\",\n \"name\": \"My Container\"\n }\n ],\n \"first_id\": \"container_123\",\n \"last_id\": \"container_123\",\n \"has_more\": false\n}\n" } } }, "post": { "summary": "Create Container", "description": "Creates a container.", "operationId": "CreateContainer", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContainerBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create container", "group": "containers", "path": "post", "examples": { "request": { "curl": "curl https://api.openai.com/v1/containers \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"My Container\",\n \"memory_limit\": \"4g\",\n \"skills\": [\n {\n \"type\": \"skill_reference\",\n \"skill_id\": \"skill_4db6f1a2c9e73508b41f9da06e2c7b5f\"\n },\n {\n \"type\": \"skill_reference\",\n \"skill_id\": \"openai-spreadsheets\",\n \"version\": \"latest\"\n }\n ],\n \"network_policy\": {\n \"type\": \"allowlist\",\n \"allowed_domains\": [\"api.buildkite.com\"]\n }\n }'\n" }, "response": "{\n \"id\": \"cntr_682e30645a488191b6363a0cbefc0f0a025ec61b66250591\",\n \"object\": \"container\",\n \"created_at\": 1747857508,\n \"status\": \"running\",\n \"expires_after\": {\n \"anchor\": \"last_active_at\",\n \"minutes\": 20\n },\n \"last_active_at\": 1747857508,\n \"network_policy\": {\n \"type\": \"allowlist\",\n \"allowed_domains\": [\"api.buildkite.com\"]\n },\n \"memory_limit\": \"4g\",\n \"name\": \"My Container\"\n}\n" } } } }, "/containers/{container_id}": { "get": { "summary": "Retrieve Container", "description": "Retrieves a container.", "operationId": "RetrieveContainer", "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve container", "group": "containers", "path": "get", "examples": { "request": { "curl": "curl https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "{\n \"id\": \"cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863\",\n \"object\": \"container\",\n \"created_at\": 1747844794,\n \"status\": \"running\",\n \"expires_after\": {\n \"anchor\": \"last_active_at\",\n \"minutes\": 20\n },\n \"last_active_at\": 1747844794,\n \"memory_limit\": \"4g\",\n \"name\": \"My Container\"\n}\n" } } }, "delete": { "operationId": "DeleteContainer", "summary": "Delete Container", "description": "Delete a container.", "parameters": [ { "name": "container_id", "in": "path", "description": "The ID of the container to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Delete a container", "group": "containers", "path": "delete", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "{\n \"id\": \"cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863\",\n \"object\": \"container.deleted\",\n \"deleted\": true\n}\n" } } } }, "/containers/{container_id}/files": { "post": { "summary": "Create a Container File\n\nYou can send either a multipart/form-data request with the raw file content, or a JSON request with a file ID.\n", "description": "Creates a container file.\n", "operationId": "CreateContainerFile", "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContainerFileBody" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateContainerFileBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerFileResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create container file", "group": "containers", "path": "post", "examples": { "request": { "curl": "curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F file=\"@example.txt\"\n" }, "response": "{\n \"id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\",\n \"object\": \"container.file\",\n \"created_at\": 1747848842,\n \"bytes\": 880,\n \"container_id\": \"cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04\",\n \"path\": \"/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json\",\n \"source\": \"user\"\n}\n" } } }, "get": { "summary": "List Container files", "description": "Lists container files.", "operationId": "ListContainerFiles", "parameters": [ { "name": "container_id", "in": "path", "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.\n", "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.\n", "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.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerFileListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List container files", "group": "containers", "path": "get", "examples": { "request": { "curl": "curl https://api.openai.com/v1/containers/cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\",\n \"object\": \"container.file\",\n \"created_at\": 1747848842,\n \"bytes\": 880,\n \"container_id\": \"cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04\",\n \"path\": \"/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json\",\n \"source\": \"user\"\n }\n ],\n \"first_id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\",\n \"has_more\": false,\n \"last_id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\"\n}\n" } } } }, "/containers/{container_id}/files/{file_id}": { "get": { "summary": "Retrieve Container File", "description": "Retrieves a container file.", "operationId": "RetrieveContainerFile", "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerFileResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve container file", "group": "containers", "path": "get", "examples": { "request": { "curl": "curl https://api.openai.com/v1/containers/container_123/files/file_456 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "{\n \"id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\",\n \"object\": \"container.file\",\n \"created_at\": 1747848842,\n \"bytes\": 880,\n \"container_id\": \"cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04\",\n \"path\": \"/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json\",\n \"source\": \"user\"\n}\n" } } }, "delete": { "operationId": "DeleteContainerFile", "summary": "Delete Container File", "description": "Delete a container file.", "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Delete a container file", "group": "containers", "path": "delete", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/containers/cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863/files/cfile_682e0e8a43c88191a7978f477a09bdf5 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "{\n \"id\": \"cfile_682e0e8a43c88191a7978f477a09bdf5\",\n \"object\": \"container.file.deleted\",\n \"deleted\": true\n}\n" } } } }, "/containers/{container_id}/files/{file_id}/content": { "get": { "summary": "Retrieve Container File Content", "description": "Retrieves a container file content.", "operationId": "RetrieveContainerFileContent", "parameters": [ { "name": "container_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve container file content", "group": "containers", "path": "get", "examples": { "request": { "curl": "curl https://api.openai.com/v1/containers/container_123/files/cfile_456/content \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "\n" } } } }, "/conversations/{conversation_id}/items": { "post": { "operationId": "createConversationItems", "tags": [ "Conversations" ], "summary": "Create items in a conversation with the given ID.", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string", "example": "conv_123" }, "description": "The ID of the conversation to add the item to." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IncludeEnum" } }, "description": "Additional fields to include in the response. See the `include`\nparameter for [listing Conversation items above](/docs/api-reference/conversations/list-items#conversations_list_items-include) for more information.\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "description": "The items to add to the conversation. You may add up to 20 items at a time.\n", "items": { "$ref": "#/components/schemas/InputItem" }, "maxItems": 20 } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationItemList" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create items", "group": "conversations", "path": "create-item", "examples": { "request": { "curl": "curl https://api.openai.com/v1/conversations/conv_123/items \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"items\": [\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"Hello!\"}\n ]\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"How are you?\"}\n ]\n }\n ]\n }'\n", "javascript": "import OpenAI from \"openai\";\nconst client = new OpenAI();\n\nconst items = await client.conversations.items.create(\n \"conv_123\",\n {\n items: [\n {\n type: \"message\",\n role: \"user\",\n content: [{ type: \"input_text\", text: \"Hello!\" }],\n },\n {\n type: \"message\",\n role: \"user\",\n content: [{ type: \"input_text\", text: \"How are you?\" }],\n },\n ],\n }\n);\nconsole.log(items.data);\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nitems = client.conversations.items.create(\n \"conv_123\",\n items=[\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": [{\"type\": \"input_text\", \"text\": \"Hello!\"}],\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": [{\"type\": \"input_text\", \"text\": \"How are you?\"}],\n }\n ],\n)\nprint(items.data)\n", "csharp": "using System;\nusing System.Collections.Generic;\nusing OpenAI.Conversations;\n\nOpenAIConversationClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nConversationItemList created = client.ConversationItems.Create(\n conversationId: \"conv_123\",\n new CreateConversationItemsOptions\n {\n Items = new List\n {\n new ConversationMessage\n {\n Role = \"user\",\n Content =\n {\n new ConversationInputText { Text = \"Hello!\" }\n }\n },\n new ConversationMessage\n {\n Role = \"user\",\n Content =\n {\n new ConversationInputText { Text = \"How are you?\" }\n }\n }\n }\n }\n);\nConsole.WriteLine(created.Data.Count);\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"type\": \"message\",\n \"id\": \"msg_abc\",\n \"status\": \"completed\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"Hello!\"}\n ]\n },\n {\n \"type\": \"message\",\n \"id\": \"msg_def\",\n \"status\": \"completed\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"How are you?\"}\n ]\n }\n ],\n \"first_id\": \"msg_abc\",\n \"last_id\": \"msg_def\",\n \"has_more\": false\n}\n" } } }, "get": { "operationId": "listConversationItems", "tags": [ "Conversations" ], "summary": "List all items for a conversation with the given ID.", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string", "example": "conv_123" }, "description": "The ID of the conversation to list items for." }, { "name": "limit", "in": "query", "description": "A limit on the number of objects to be returned. Limit can range between\n1 and 100, and the default is 20.\n", "required": false, "schema": { "type": "integer", "default": 20 } }, { "in": "query", "name": "order", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "The order to return the input items in. Default is `desc`.\n- `asc`: Return the input items in ascending order.\n- `desc`: Return the input items in descending order.\n" }, { "in": "query", "name": "after", "schema": { "type": "string" }, "description": "An item ID to list items after, used in pagination.\n" }, { "name": "include", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IncludeEnum" } }, "description": "Specify additional output data to include in the model response. Currently supported values are:\n- `web_search_call.action.sources`: Include the sources of the web search tool call.\n- `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items.\n- `computer_call_output.output.image_url`: Include image urls from the computer call output.\n- `file_search_call.results`: Include the search results of the file search tool call.\n- `message.input_image.image_url`: Include image urls from the input message.\n- `message.output_text.logprobs`: Include logprobs with assistant messages.\n- `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the `store` parameter is set to `false`, or when an organization is enrolled in the zero data retention program)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationItemList" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List items", "group": "conversations", "path": "list-items", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/conversations/conv_123/items?limit=10\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "javascript": "import OpenAI from \"openai\";\nconst client = new OpenAI();\n\nconst items = await client.conversations.items.list(\"conv_123\", { limit: 10 });\nconsole.log(items.data);\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nitems = client.conversations.items.list(\"conv_123\", limit=10)\nprint(items.data)\n", "csharp": "using System;\nusing OpenAI.Conversations;\n\nOpenAIConversationClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nConversationItemList items = client.ConversationItems.List(\n conversationId: \"conv_123\",\n new ListConversationItemsOptions { Limit = 10 }\n);\nConsole.WriteLine(items.Data.Count);\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"type\": \"message\",\n \"id\": \"msg_abc\",\n \"status\": \"completed\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"Hello!\"}\n ]\n }\n ],\n \"first_id\": \"msg_abc\",\n \"last_id\": \"msg_abc\",\n \"has_more\": false\n}\n" } } } }, "/conversations/{conversation_id}/items/{item_id}": { "get": { "operationId": "getConversationItem", "tags": [ "Conversations" ], "summary": "Get a single item from a conversation with the given IDs.", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string", "example": "conv_123" }, "description": "The ID of the conversation that contains the item." }, { "in": "path", "name": "item_id", "required": true, "schema": { "type": "string", "example": "msg_abc" }, "description": "The ID of the item to retrieve." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IncludeEnum" } }, "description": "Additional fields to include in the response. See the `include`\nparameter for [listing Conversation items above](/docs/api-reference/conversations/list-items#conversations_list_items-include) for more information.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationItem" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve an item", "group": "conversations", "path": "get-item", "examples": { "request": { "curl": "curl https://api.openai.com/v1/conversations/conv_123/items/msg_abc \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "javascript": "import OpenAI from \"openai\";\nconst client = new OpenAI();\n\nconst item = await client.conversations.items.retrieve(\n \"conv_123\",\n \"msg_abc\"\n);\nconsole.log(item);\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nitem = client.conversations.items.retrieve(\"conv_123\", \"msg_abc\")\nprint(item)\n", "csharp": "using System;\nusing OpenAI.Conversations;\n\nOpenAIConversationClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nConversationItem item = client.ConversationItems.Get(\n conversationId: \"conv_123\",\n itemId: \"msg_abc\"\n);\nConsole.WriteLine(item.Id);\n" }, "response": "{\n \"type\": \"message\",\n \"id\": \"msg_abc\",\n \"status\": \"completed\",\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"Hello!\"}\n ]\n}\n" } } }, "delete": { "operationId": "deleteConversationItem", "tags": [ "Conversations" ], "summary": "Delete an item from a conversation with the given IDs.", "parameters": [ { "in": "path", "name": "conversation_id", "required": true, "schema": { "type": "string", "example": "conv_123" }, "description": "The ID of the conversation that contains the item." }, { "in": "path", "name": "item_id", "required": true, "schema": { "type": "string", "example": "msg_abc" }, "description": "The ID of the item to delete." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Delete an item", "group": "conversations", "path": "delete-item", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/conversations/conv_123/items/msg_abc \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "javascript": "import OpenAI from \"openai\";\nconst client = new OpenAI();\n\nconst conversation = await client.conversations.items.delete(\n \"conv_123\",\n \"msg_abc\"\n);\nconsole.log(conversation);\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nconversation = client.conversations.items.delete(\"conv_123\", \"msg_abc\")\nprint(conversation)\n", "csharp": "using System;\nusing OpenAI.Conversations;\n\nOpenAIConversationClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nConversation conversation = client.ConversationItems.Delete(\n conversationId: \"conv_123\",\n itemId: \"msg_abc\"\n);\nConsole.WriteLine(conversation.Id);\n" }, "response": "{\n \"id\": \"conv_123\",\n \"object\": \"conversation\",\n \"created_at\": 1741900000,\n \"metadata\": {\"topic\": \"demo\"}\n}\n" } } } }, "/embeddings": { "post": { "operationId": "createEmbedding", "tags": [ "Embeddings" ], "summary": "Creates an embedding vector representing the input text.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmbeddingRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmbeddingResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create embeddings", "group": "embeddings", "examples": { "request": { "curl": "curl https://api.openai.com/v1/embeddings \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": \"The food was delicious and the waiter...\",\n \"model\": \"text-embedding-ada-002\",\n \"encoding_format\": \"float\"\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.embeddings.create(\n model=\"text-embedding-ada-002\",\n input=\"The food was delicious and the waiter...\",\n encoding_format=\"float\"\n)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const embedding = await openai.embeddings.create({\n model: \"text-embedding-ada-002\",\n input: \"The quick brown fox jumped over the lazy dog\",\n encoding_format: \"float\",\n });\n\n console.log(embedding);\n}\n\nmain();\n", "csharp": "using System;\n\nusing OpenAI.Embeddings;\n\nEmbeddingClient client = new(\n model: \"text-embedding-3-small\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nOpenAIEmbedding embedding = client.GenerateEmbedding(input: \"The quick brown fox jumped over the lazy dog\");\nReadOnlyMemory vector = embedding.ToFloats();\n\nfor (int i = 0; i < vector.Length; i++)\n{\n Console.WriteLine($\" [{i,4}] = {vector.Span[i]}\");\n}\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"embedding\",\n \"embedding\": [\n 0.0023064255,\n -0.009327292,\n .... (1536 floats total for ada-002)\n -0.0028842222,\n ],\n \"index\": 0\n }\n ],\n \"model\": \"text-embedding-ada-002\",\n \"usage\": {\n \"prompt_tokens\": 8,\n \"total_tokens\": 8\n }\n}\n" } } } }, "/evals": { "get": { "operationId": "listEvals", "tags": [ "Evals" ], "summary": "List evaluations for a project.\n", "parameters": [ { "name": "after", "in": "query", "description": "Identifier for the last eval from the previous pagination request.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of evals to retrieve.", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "order", "in": "query", "description": "Sort order for evals by timestamp. Use `asc` for ascending order or `desc` for descending order.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "order_by", "in": "query", "description": "Evals can be ordered by creation time or last updated time. Use\n`created_at` for creation time or `updated_at` for last updated time.\n", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" } } ], "responses": { "200": { "description": "A list of evals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalList" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List evals", "group": "evals", "path": "list", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals?limit=1 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nevals = client.evals.list(limit=1)\nprint(evals)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst evals = await openai.evals.list({ limit: 1 });\nconsole.log(evals);\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"object\": \"eval\",\n \"data_source_config\": {\n \"type\": \"stored_completions\",\n \"metadata\": {\n \"usecase\": \"push_notifications_summarizer\"\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"item\": {\n \"type\": \"object\"\n },\n \"sample\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"item\",\n \"sample\"\n ]\n }\n },\n \"testing_criteria\": [\n {\n \"name\": \"Push Notification Summary Grader\",\n \"id\": \"Push Notification Summary Grader-9b876f24-4762-4be9-aff4-db7a9b31c673\",\n \"type\": \"label_model\",\n \"model\": \"o3-mini\",\n \"input\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"\\nLabel the following push notification summary as either correct or incorrect.\\nThe push notification and the summary will be provided below.\\nA good push notificiation summary is concise and snappy.\\nIf it is good, then label it as correct, if not, then incorrect.\\n\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"\\nPush notifications: {{item.input}}\\nSummary: {{sample.output_text}}\\n\"\n }\n }\n ],\n \"passing_labels\": [\n \"correct\"\n ],\n \"labels\": [\n \"correct\",\n \"incorrect\"\n ],\n \"sampling_params\": null\n }\n ],\n \"name\": \"Push Notification Summary Grader\",\n \"created_at\": 1739314509,\n \"metadata\": {\n \"description\": \"A stored completions eval for push notification summaries\"\n }\n }\n ],\n \"first_id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"last_id\": \"eval_67aa884cf6688190b58f657d4441c8b7\",\n \"has_more\": true\n}\n" } } }, "post": { "operationId": "createEval", "tags": [ "Evals" ], "summary": "Create the structure of an evaluation that can be used to test a model's performance.\nAn evaluation is a set of testing criteria and the config for a data source, which dictates the schema of the data used in the evaluation. After creating an evaluation, you can run it on different models and model parameters. We support several types of graders and datasources.\nFor more information, see the [Evals guide](/docs/guides/evals).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvalRequest" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Eval" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create eval", "group": "evals", "path": "post", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Sentiment\",\n \"data_source_config\": {\n \"type\": \"stored_completions\",\n \"metadata\": {\n \"usecase\": \"chatbot\"\n }\n },\n \"testing_criteria\": [\n {\n \"type\": \"label_model\",\n \"model\": \"o3-mini\",\n \"input\": [\n {\n \"role\": \"developer\",\n \"content\": \"Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'\"\n },\n {\n \"role\": \"user\",\n \"content\": \"Statement: {{item.input}}\"\n }\n ],\n \"passing_labels\": [\n \"positive\"\n ],\n \"labels\": [\n \"positive\",\n \"neutral\",\n \"negative\"\n ],\n \"name\": \"Example label grader\"\n }\n ]\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\neval_obj = client.evals.create(\n name=\"Sentiment\",\n data_source_config={\n \"type\": \"stored_completions\",\n \"metadata\": {\"usecase\": \"chatbot\"}\n },\n testing_criteria=[\n {\n \"type\": \"label_model\",\n \"model\": \"o3-mini\",\n \"input\": [\n {\"role\": \"developer\", \"content\": \"Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'\"},\n {\"role\": \"user\", \"content\": \"Statement: {{item.input}}\"}\n ],\n \"passing_labels\": [\"positive\"],\n \"labels\": [\"positive\", \"neutral\", \"negative\"],\n \"name\": \"Example label grader\"\n }\n ]\n)\nprint(eval_obj)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst evalObj = await openai.evals.create({\n name: \"Sentiment\",\n data_source_config: {\n type: \"stored_completions\",\n metadata: { usecase: \"chatbot\" }\n },\n testing_criteria: [\n {\n type: \"label_model\",\n model: \"o3-mini\",\n input: [\n { role: \"developer\", content: \"Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'\" },\n { role: \"user\", content: \"Statement: {{item.input}}\" }\n ],\n passing_labels: [\"positive\"],\n labels: [\"positive\", \"neutral\", \"negative\"],\n name: \"Example label grader\"\n }\n ]\n});\nconsole.log(evalObj);\n" }, "response": "{\n \"object\": \"eval\",\n \"id\": \"eval_67b7fa9a81a88190ab4aa417e397ea21\",\n \"data_source_config\": {\n \"type\": \"stored_completions\",\n \"metadata\": {\n \"usecase\": \"chatbot\"\n },\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"item\": {\n \"type\": \"object\"\n },\n \"sample\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"item\",\n \"sample\"\n ]\n },\n \"testing_criteria\": [\n {\n \"name\": \"Example label grader\",\n \"type\": \"label_model\",\n \"model\": \"o3-mini\",\n \"input\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"Classify the sentiment of the following statement as one of positive, neutral, or negative\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"Statement: {{item.input}}\"\n }\n }\n ],\n \"passing_labels\": [\n \"positive\"\n ],\n \"labels\": [\n \"positive\",\n \"neutral\",\n \"negative\"\n ]\n }\n ],\n \"name\": \"Sentiment\",\n \"created_at\": 1740110490,\n \"metadata\": {\n \"description\": \"An eval for sentiment analysis\"\n }\n}\n" } } } }, "/evals/{eval_id}": { "get": { "operationId": "getEval", "tags": [ "Evals" ], "summary": "Get an evaluation by ID.\n", "parameters": [ { "name": "eval_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the evaluation to retrieve." } ], "responses": { "200": { "description": "The evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Eval" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Get an eval", "group": "evals", "path": "get", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\neval_obj = client.evals.retrieve(\"eval_67abd54d9b0081909a86353f6fb9317a\")\nprint(eval_obj)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst evalObj = await openai.evals.retrieve(\"eval_67abd54d9b0081909a86353f6fb9317a\");\nconsole.log(evalObj);\n" }, "response": "{\n \"object\": \"eval\",\n \"id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"data_source_config\": {\n \"type\": \"custom\",\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"item\": {\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\"\n },\n \"ground_truth\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"input\",\n \"ground_truth\"\n ]\n }\n },\n \"required\": [\n \"item\"\n ]\n }\n },\n \"testing_criteria\": [\n {\n \"name\": \"String check\",\n \"id\": \"String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2\",\n \"type\": \"string_check\",\n \"input\": \"{{item.input}}\",\n \"reference\": \"{{item.ground_truth}}\",\n \"operation\": \"eq\"\n }\n ],\n \"name\": \"External Data Eval\",\n \"created_at\": 1739314509,\n \"metadata\": {},\n}\n" } } }, "post": { "operationId": "updateEval", "tags": [ "Evals" ], "summary": "Update certain properties of an evaluation.\n", "parameters": [ { "name": "eval_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the evaluation to update." } ], "requestBody": { "description": "Request to update an evaluation", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Rename the evaluation." }, "metadata": { "$ref": "#/components/schemas/Metadata" } } } } } }, "responses": { "200": { "description": "The updated evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Eval" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Update an eval", "group": "evals", "path": "update", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Updated Eval\", \"metadata\": {\"description\": \"Updated description\"}}'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nupdated_eval = client.evals.update(\n \"eval_67abd54d9b0081909a86353f6fb9317a\",\n name=\"Updated Eval\",\n metadata={\"description\": \"Updated description\"}\n)\nprint(updated_eval)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst updatedEval = await openai.evals.update(\n \"eval_67abd54d9b0081909a86353f6fb9317a\",\n {\n name: \"Updated Eval\",\n metadata: { description: \"Updated description\" }\n }\n);\nconsole.log(updatedEval);\n" }, "response": "{\n \"object\": \"eval\",\n \"id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"data_source_config\": {\n \"type\": \"custom\",\n \"schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"item\": {\n \"type\": \"object\",\n \"properties\": {\n \"input\": {\n \"type\": \"string\"\n },\n \"ground_truth\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"input\",\n \"ground_truth\"\n ]\n }\n },\n \"required\": [\n \"item\"\n ]\n }\n },\n \"testing_criteria\": [\n {\n \"name\": \"String check\",\n \"id\": \"String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2\",\n \"type\": \"string_check\",\n \"input\": \"{{item.input}}\",\n \"reference\": \"{{item.ground_truth}}\",\n \"operation\": \"eq\"\n }\n ],\n \"name\": \"Updated Eval\",\n \"created_at\": 1739314509,\n \"metadata\": {\"description\": \"Updated description\"},\n}\n" } } }, "delete": { "operationId": "deleteEval", "tags": [ "Evals" ], "summary": "Delete an evaluation.\n", "parameters": [ { "name": "eval_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the evaluation to delete." } ], "responses": { "200": { "description": "Successfully deleted the evaluation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "eval.deleted" }, "deleted": { "type": "boolean", "example": true }, "eval_id": { "type": "string", "example": "eval_abc123" } }, "required": [ "object", "deleted", "eval_id" ] } } } }, "404": { "description": "Evaluation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Delete an eval", "group": "evals", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals/eval_abc123 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ndeleted = client.evals.delete(\"eval_abc123\")\nprint(deleted)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst deleted = await openai.evals.delete(\"eval_abc123\");\nconsole.log(deleted);\n" }, "response": "{\n \"object\": \"eval.deleted\",\n \"deleted\": true,\n \"eval_id\": \"eval_abc123\"\n}\n" } } } }, "/evals/{eval_id}/runs": { "get": { "operationId": "getEvalRuns", "tags": [ "Evals" ], "summary": "Get a list of runs for an evaluation.\n", "parameters": [ { "name": "eval_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the evaluation to retrieve runs for." }, { "name": "after", "in": "query", "description": "Identifier for the last run from the previous pagination request.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of runs to retrieve.", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "order", "in": "query", "description": "Sort order for runs by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "status", "in": "query", "description": "Filter runs by status. One of `queued` | `in_progress` | `failed` | `completed` | `canceled`.", "required": false, "schema": { "type": "string", "enum": [ "queued", "in_progress", "completed", "canceled", "failed" ] } } ], "responses": { "200": { "description": "A list of runs for the evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalRunList" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Get eval runs", "group": "evals", "path": "get-runs", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals/egroup_67abd54d9b0081909a86353f6fb9317a/runs \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nruns = client.evals.runs.list(\"egroup_67abd54d9b0081909a86353f6fb9317a\")\nprint(runs)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst runs = await openai.evals.runs.list(\"egroup_67abd54d9b0081909a86353f6fb9317a\");\nconsole.log(runs);\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"eval.run\",\n \"id\": \"evalrun_67e0c7d31560819090d60c0780591042\",\n \"eval_id\": \"eval_67e0c726d560819083f19a957c4c640b\",\n \"report_url\": \"https://platform.openai.com/evaluations/eval_67e0c726d560819083f19a957c4c640b\",\n \"status\": \"completed\",\n \"model\": \"o3-mini\",\n \"name\": \"bulk_with_negative_examples_o3-mini\",\n \"created_at\": 1742784467,\n \"result_counts\": {\n \"total\": 1,\n \"errored\": 0,\n \"failed\": 0,\n \"passed\": 1\n },\n \"per_model_usage\": [\n {\n \"model_name\": \"o3-mini\",\n \"invocation_count\": 1,\n \"prompt_tokens\": 563,\n \"completion_tokens\": 874,\n \"total_tokens\": 1437,\n \"cached_tokens\": 0\n }\n ],\n \"per_testing_criteria_results\": [\n {\n \"testing_criteria\": \"Push Notification Summary Grader-1808cd0b-eeec-4e0b-a519-337e79f4f5d1\",\n \"passed\": 1,\n \"failed\": 0\n }\n ],\n \"data_source\": {\n \"type\": \"completions\",\n \"source\": {\n \"type\": \"file_content\",\n \"content\": [\n {\n \"item\": {\n \"notifications\": \"\\n- New message from Sarah: \\\"Can you call me later?\\\"\\n- Your package has been delivered!\\n- Flash sale: 20% off electronics for the next 2 hours!\\n\"\n }\n }\n ]\n },\n \"input_messages\": {\n \"type\": \"template\",\n \"template\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"\\n\\n\\n\\nYou are a helpful assistant that takes in an array of push notifications and returns a collapsed summary of them.\\nThe push notification will be provided as follows:\\n\\n...notificationlist...\\n\\n\\nYou should return just the summary and nothing else.\\n\\n\\nYou should return a summary that is concise and snappy.\\n\\n\\nHere is an example of a good summary:\\n\\n- Traffic alert: Accident reported on Main Street.- Package out for delivery: Expected by 5 PM.- New friend suggestion: Connect with Emma.\\n\\n\\nTraffic alert, package expected by 5pm, suggestion for new friend (Emily).\\n\\n\\n\\nHere is an example of a bad summary:\\n\\n- Traffic alert: Accident reported on Main Street.- Package out for delivery: Expected by 5 PM.- New friend suggestion: Connect with Emma.\\n\\n\\nTraffic alert reported on main street. You have a package that will arrive by 5pm, Emily is a new friend suggested for you.\\n\\n\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"{{item.notifications}}\"\n }\n }\n ]\n },\n \"model\": \"o3-mini\",\n \"sampling_params\": null\n },\n \"error\": null,\n \"metadata\": {}\n }\n ],\n \"first_id\": \"evalrun_67e0c7d31560819090d60c0780591042\",\n \"last_id\": \"evalrun_67e0c7d31560819090d60c0780591042\",\n \"has_more\": true\n}\n" } } }, "post": { "operationId": "createEvalRun", "tags": [ "Evals" ], "summary": "Kicks off a new run for a given evaluation, specifying the data source, and what model configuration to use to test. The datasource will be validated against the schema specified in the config of the evaluation.\n", "parameters": [ { "in": "path", "name": "eval_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the evaluation to create a run for." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEvalRunRequest" } } } }, "responses": { "201": { "description": "Successfully created a run for the evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalRun" } } } }, "400": { "description": "Bad request (for example, missing eval object)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create eval run", "group": "evals", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals/eval_67e579652b548190aaa83ada4b125f47/runs \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"gpt-4o-mini\",\"data_source\":{\"type\":\"completions\",\"input_messages\":{\"type\":\"template\",\"template\":[{\"role\":\"developer\",\"content\":\"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"} , {\"role\":\"user\",\"content\":\"{{item.input}}\"}]} ,\"sampling_params\":{\"temperature\":1,\"max_completions_tokens\":2048,\"top_p\":1,\"seed\":42},\"model\":\"gpt-4o-mini\",\"source\":{\"type\":\"file_content\",\"content\":[{\"item\":{\"input\":\"Tech Company Launches Advanced Artificial Intelligence Platform\",\"ground_truth\":\"Technology\"}}]}}'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.evals.runs.create(\n \"eval_67e579652b548190aaa83ada4b125f47\",\n name=\"gpt-4o-mini\",\n data_source={\n \"type\": \"completions\",\n \"input_messages\": {\n \"type\": \"template\",\n \"template\": [\n {\n \"role\": \"developer\",\n \"content\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"\n },\n {\n \"role\": \"user\",\n \"content\": \"{{item.input}}\"\n }\n ]\n },\n \"sampling_params\": {\n \"temperature\": 1,\n \"max_completions_tokens\": 2048,\n \"top_p\": 1,\n \"seed\": 42\n },\n \"model\": \"gpt-4o-mini\",\n \"source\": {\n \"type\": \"file_content\",\n \"content\": [\n {\n \"item\": {\n \"input\": \"Tech Company Launches Advanced Artificial Intelligence Platform\",\n \"ground_truth\": \"Technology\"\n }\n }\n ]\n }\n }\n)\nprint(run)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst run = await openai.evals.runs.create(\n \"eval_67e579652b548190aaa83ada4b125f47\",\n {\n name: \"gpt-4o-mini\",\n data_source: {\n type: \"completions\",\n input_messages: {\n type: \"template\",\n template: [\n {\n role: \"developer\",\n content: \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"\n },\n {\n role: \"user\",\n content: \"{{item.input}}\"\n }\n ]\n },\n sampling_params: {\n temperature: 1,\n max_completions_tokens: 2048,\n top_p: 1,\n seed: 42\n },\n model: \"gpt-4o-mini\",\n source: {\n type: \"file_content\",\n content: [\n {\n item: {\n input: \"Tech Company Launches Advanced Artificial Intelligence Platform\",\n ground_truth: \"Technology\"\n }\n }\n ]\n }\n }\n }\n);\nconsole.log(run);\n" }, "response": "{\n \"object\": \"eval.run\",\n \"id\": \"evalrun_67e57965b480819094274e3a32235e4c\",\n \"eval_id\": \"eval_67e579652b548190aaa83ada4b125f47\",\n \"report_url\": \"https://platform.openai.com/evaluations/eval_67e579652b548190aaa83ada4b125f47&run_id=evalrun_67e57965b480819094274e3a32235e4c\",\n \"status\": \"queued\",\n \"model\": \"gpt-4o-mini\",\n \"name\": \"gpt-4o-mini\",\n \"created_at\": 1743092069,\n \"result_counts\": {\n \"total\": 0,\n \"errored\": 0,\n \"failed\": 0,\n \"passed\": 0\n },\n \"per_model_usage\": null,\n \"per_testing_criteria_results\": null,\n \"data_source\": {\n \"type\": \"completions\",\n \"source\": {\n \"type\": \"file_content\",\n \"content\": [\n {\n \"item\": {\n \"input\": \"Tech Company Launches Advanced Artificial Intelligence Platform\",\n \"ground_truth\": \"Technology\"\n }\n }\n ]\n },\n \"input_messages\": {\n \"type\": \"template\",\n \"template\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"{{item.input}}\"\n }\n }\n ]\n },\n \"model\": \"gpt-4o-mini\",\n \"sampling_params\": {\n \"seed\": 42,\n \"temperature\": 1.0,\n \"top_p\": 1.0,\n \"max_completions_tokens\": 2048\n }\n },\n \"error\": null,\n \"metadata\": {}\n}\n" } } } }, "/evals/{eval_id}/runs/{run_id}": { "get": { "operationId": "getEvalRun", "tags": [ "Evals" ], "summary": "Get an evaluation run by ID.\n", "parameters": [ { "name": "eval_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the evaluation to retrieve runs for." }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the run to retrieve." } ], "responses": { "200": { "description": "The evaluation run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalRun" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Get an eval run", "group": "evals", "path": "get", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.evals.runs.retrieve(\n \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"evalrun_67abd54d60ec8190832b46859da808f7\"\n)\nprint(run)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst run = await openai.evals.runs.retrieve(\n \"evalrun_67abd54d60ec8190832b46859da808f7\",\n { eval_id: \"eval_67abd54d9b0081909a86353f6fb9317a\" }\n);\nconsole.log(run);\n" }, "response": "{\n \"object\": \"eval.run\",\n \"id\": \"evalrun_67abd54d60ec8190832b46859da808f7\",\n \"eval_id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"report_url\": \"https://platform.openai.com/evaluations/eval_67abd54d9b0081909a86353f6fb9317a?run_id=evalrun_67abd54d60ec8190832b46859da808f7\",\n \"status\": \"queued\",\n \"model\": \"gpt-4o-mini\",\n \"name\": \"gpt-4o-mini\",\n \"created_at\": 1743092069,\n \"result_counts\": {\n \"total\": 0,\n \"errored\": 0,\n \"failed\": 0,\n \"passed\": 0\n },\n \"per_model_usage\": null,\n \"per_testing_criteria_results\": null,\n \"data_source\": {\n \"type\": \"completions\",\n \"source\": {\n \"type\": \"file_content\",\n \"content\": [\n {\n \"item\": {\n \"input\": \"Tech Company Launches Advanced Artificial Intelligence Platform\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"Central Bank Increases Interest Rates Amid Inflation Concerns\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"International Summit Addresses Climate Change Strategies\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Major Retailer Reports Record-Breaking Holiday Sales\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"National Team Qualifies for World Championship Finals\",\n \"ground_truth\": \"Sports\"\n }\n },\n {\n \"item\": {\n \"input\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"Global Manufacturer Announces Merger with Competitor\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"Breakthrough in Renewable Energy Technology Unveiled\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"World Leaders Sign Historic Climate Agreement\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Professional Athlete Sets New Record in Championship Event\",\n \"ground_truth\": \"Sports\"\n }\n },\n {\n \"item\": {\n \"input\": \"Financial Institutions Adapt to New Regulatory Requirements\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"Tech Conference Showcases Advances in Artificial Intelligence\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"Global Markets Respond to Oil Price Fluctuations\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"International Cooperation Strengthened Through New Treaty\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Sports League Announces Revised Schedule for Upcoming Season\",\n \"ground_truth\": \"Sports\"\n }\n }\n ]\n },\n \"input_messages\": {\n \"type\": \"template\",\n \"template\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"{{item.input}}\"\n }\n }\n ]\n },\n \"model\": \"gpt-4o-mini\",\n \"sampling_params\": {\n \"seed\": 42,\n \"temperature\": 1.0,\n \"top_p\": 1.0,\n \"max_completions_tokens\": 2048\n }\n },\n \"error\": null,\n \"metadata\": {}\n}\n" } } }, "post": { "operationId": "cancelEvalRun", "tags": [ "Evals" ], "summary": "Cancel an ongoing evaluation run.\n", "parameters": [ { "name": "eval_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the evaluation whose run you want to cancel." }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the run to cancel." } ], "responses": { "200": { "description": "The canceled eval run object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalRun" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Cancel eval run", "group": "evals", "path": "post", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7/cancel \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncanceled_run = client.evals.runs.cancel(\n \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"evalrun_67abd54d60ec8190832b46859da808f7\"\n)\nprint(canceled_run)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst canceledRun = await openai.evals.runs.cancel(\n \"evalrun_67abd54d60ec8190832b46859da808f7\",\n { eval_id: \"eval_67abd54d9b0081909a86353f6fb9317a\" }\n);\nconsole.log(canceledRun);\n" }, "response": "{\n \"object\": \"eval.run\",\n \"id\": \"evalrun_67abd54d60ec8190832b46859da808f7\",\n \"eval_id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"report_url\": \"https://platform.openai.com/evaluations/eval_67abd54d9b0081909a86353f6fb9317a?run_id=evalrun_67abd54d60ec8190832b46859da808f7\",\n \"status\": \"canceled\",\n \"model\": \"gpt-4o-mini\",\n \"name\": \"gpt-4o-mini\",\n \"created_at\": 1743092069,\n \"result_counts\": {\n \"total\": 0,\n \"errored\": 0,\n \"failed\": 0,\n \"passed\": 0\n },\n \"per_model_usage\": null,\n \"per_testing_criteria_results\": null,\n \"data_source\": {\n \"type\": \"completions\",\n \"source\": {\n \"type\": \"file_content\",\n \"content\": [\n {\n \"item\": {\n \"input\": \"Tech Company Launches Advanced Artificial Intelligence Platform\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"Central Bank Increases Interest Rates Amid Inflation Concerns\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"International Summit Addresses Climate Change Strategies\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Major Retailer Reports Record-Breaking Holiday Sales\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"National Team Qualifies for World Championship Finals\",\n \"ground_truth\": \"Sports\"\n }\n },\n {\n \"item\": {\n \"input\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"Global Manufacturer Announces Merger with Competitor\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"Breakthrough in Renewable Energy Technology Unveiled\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"World Leaders Sign Historic Climate Agreement\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Professional Athlete Sets New Record in Championship Event\",\n \"ground_truth\": \"Sports\"\n }\n },\n {\n \"item\": {\n \"input\": \"Financial Institutions Adapt to New Regulatory Requirements\",\n \"ground_truth\": \"Business\"\n }\n },\n {\n \"item\": {\n \"input\": \"Tech Conference Showcases Advances in Artificial Intelligence\",\n \"ground_truth\": \"Technology\"\n }\n },\n {\n \"item\": {\n \"input\": \"Global Markets Respond to Oil Price Fluctuations\",\n \"ground_truth\": \"Markets\"\n }\n },\n {\n \"item\": {\n \"input\": \"International Cooperation Strengthened Through New Treaty\",\n \"ground_truth\": \"World\"\n }\n },\n {\n \"item\": {\n \"input\": \"Sports League Announces Revised Schedule for Upcoming Season\",\n \"ground_truth\": \"Sports\"\n }\n }\n ]\n },\n \"input_messages\": {\n \"type\": \"template\",\n \"template\": [\n {\n \"type\": \"message\",\n \"role\": \"developer\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\"\n }\n },\n {\n \"type\": \"message\",\n \"role\": \"user\",\n \"content\": {\n \"type\": \"input_text\",\n \"text\": \"{{item.input}}\"\n }\n }\n ]\n },\n \"model\": \"gpt-4o-mini\",\n \"sampling_params\": {\n \"seed\": 42,\n \"temperature\": 1.0,\n \"top_p\": 1.0,\n \"max_completions_tokens\": 2048\n }\n },\n \"error\": null,\n \"metadata\": {}\n}\n" } } }, "delete": { "operationId": "deleteEvalRun", "tags": [ "Evals" ], "summary": "Delete an eval run.\n", "parameters": [ { "name": "eval_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the evaluation to delete the run from." }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the run to delete." } ], "responses": { "200": { "description": "Successfully deleted the eval run", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "eval.run.deleted" }, "deleted": { "type": "boolean", "example": true }, "run_id": { "type": "string", "example": "evalrun_677469f564d48190807532a852da3afb" } } } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Delete eval run", "group": "evals", "path": "delete", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals/eval_123abc/runs/evalrun_abc456 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ndeleted = client.evals.runs.delete(\n \"eval_123abc\",\n \"evalrun_abc456\"\n)\nprint(deleted)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst deleted = await openai.evals.runs.delete(\n \"eval_123abc\",\n \"evalrun_abc456\"\n);\nconsole.log(deleted);\n" }, "response": "{\n \"object\": \"eval.run.deleted\",\n \"deleted\": true,\n \"run_id\": \"evalrun_abc456\"\n}\n" } } } }, "/evals/{eval_id}/runs/{run_id}/output_items": { "get": { "operationId": "getEvalRunOutputItems", "tags": [ "Evals" ], "summary": "Get a list of output items for an evaluation run.\n", "parameters": [ { "name": "eval_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the evaluation to retrieve runs for." }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the run to retrieve output items for." }, { "name": "after", "in": "query", "description": "Identifier for the last output item from the previous pagination request.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of output items to retrieve.", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "status", "in": "query", "description": "Filter output items by status. Use `failed` to filter by failed output\nitems or `pass` to filter by passed output items.\n", "required": false, "schema": { "type": "string", "enum": [ "fail", "pass" ] } }, { "name": "order", "in": "query", "description": "Sort order for output items by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "A list of output items for the evaluation run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalRunOutputItemList" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Get eval run output items", "group": "evals", "path": "get", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals/egroup_67abd54d9b0081909a86353f6fb9317a/runs/erun_67abd54d60ec8190832b46859da808f7/output_items \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\noutput_items = client.evals.runs.output_items.list(\n \"egroup_67abd54d9b0081909a86353f6fb9317a\",\n \"erun_67abd54d60ec8190832b46859da808f7\"\n)\nprint(output_items)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst outputItems = await openai.evals.runs.outputItems.list(\n \"egroup_67abd54d9b0081909a86353f6fb9317a\",\n \"erun_67abd54d60ec8190832b46859da808f7\"\n);\nconsole.log(outputItems);\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"eval.run.output_item\",\n \"id\": \"outputitem_67e5796c28e081909917bf79f6e6214d\",\n \"created_at\": 1743092076,\n \"run_id\": \"evalrun_67abd54d60ec8190832b46859da808f7\",\n \"eval_id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"status\": \"pass\",\n \"datasource_item_id\": 5,\n \"datasource_item\": {\n \"input\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"ground_truth\": \"Markets\"\n },\n \"results\": [\n {\n \"name\": \"String check-a2486074-d803-4445-b431-ad2262e85d47\",\n \"sample\": null,\n \"passed\": true,\n \"score\": 1.0\n }\n ],\n \"sample\": {\n \"input\": [\n {\n \"role\": \"developer\",\n \"content\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n },\n {\n \"role\": \"user\",\n \"content\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n }\n ],\n \"output\": [\n {\n \"role\": \"assistant\",\n \"content\": \"Markets\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n }\n ],\n \"finish_reason\": \"stop\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"usage\": {\n \"total_tokens\": 325,\n \"completion_tokens\": 2,\n \"prompt_tokens\": 323,\n \"cached_tokens\": 0\n },\n \"error\": null,\n \"temperature\": 1.0,\n \"max_completion_tokens\": 2048,\n \"top_p\": 1.0,\n \"seed\": 42\n }\n }\n ],\n \"first_id\": \"outputitem_67e5796c28e081909917bf79f6e6214d\",\n \"last_id\": \"outputitem_67e5796c28e081909917bf79f6e6214d\",\n \"has_more\": true\n}\n" } } } }, "/evals/{eval_id}/runs/{run_id}/output_items/{output_item_id}": { "get": { "operationId": "getEvalRunOutputItem", "tags": [ "Evals" ], "summary": "Get an evaluation run output item by ID.\n", "parameters": [ { "name": "eval_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the evaluation to retrieve runs for." }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the run to retrieve." }, { "name": "output_item_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the output item to retrieve." } ], "responses": { "200": { "description": "The evaluation run output item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvalRunOutputItem" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Get an output item of an eval run", "group": "evals", "path": "get", "examples": { "request": { "curl": "curl https://api.openai.com/v1/evals/eval_67abd54d9b0081909a86353f6fb9317a/runs/evalrun_67abd54d60ec8190832b46859da808f7/output_items/outputitem_67abd55eb6548190bb580745d5644a33 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\noutput_item = client.evals.runs.output_items.retrieve(\n \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"evalrun_67abd54d60ec8190832b46859da808f7\",\n \"outputitem_67abd55eb6548190bb580745d5644a33\"\n)\nprint(output_item)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst outputItem = await openai.evals.runs.outputItems.retrieve(\n \"outputitem_67abd55eb6548190bb580745d5644a33\",\n {\n eval_id: \"eval_67abd54d9b0081909a86353f6fb9317a\",\n run_id: \"evalrun_67abd54d60ec8190832b46859da808f7\",\n }\n);\nconsole.log(outputItem);\n" }, "response": "{\n \"object\": \"eval.run.output_item\",\n \"id\": \"outputitem_67e5796c28e081909917bf79f6e6214d\",\n \"created_at\": 1743092076,\n \"run_id\": \"evalrun_67abd54d60ec8190832b46859da808f7\",\n \"eval_id\": \"eval_67abd54d9b0081909a86353f6fb9317a\",\n \"status\": \"pass\",\n \"datasource_item_id\": 5,\n \"datasource_item\": {\n \"input\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"ground_truth\": \"Markets\"\n },\n \"results\": [\n {\n \"name\": \"String check-a2486074-d803-4445-b431-ad2262e85d47\",\n \"sample\": null,\n \"passed\": true,\n \"score\": 1.0\n }\n ],\n \"sample\": {\n \"input\": [\n {\n \"role\": \"developer\",\n \"content\": \"Categorize a given news headline into one of the following topics: Technology, Markets, World, Business, or Sports.\\n\\n# Steps\\n\\n1. Analyze the content of the news headline to understand its primary focus.\\n2. Extract the subject matter, identifying any key indicators or keywords.\\n3. Use the identified indicators to determine the most suitable category out of the five options: Technology, Markets, World, Business, or Sports.\\n4. Ensure only one category is selected per headline.\\n\\n# Output Format\\n\\nRespond with the chosen category as a single word. For instance: \\\"Technology\\\", \\\"Markets\\\", \\\"World\\\", \\\"Business\\\", or \\\"Sports\\\".\\n\\n# Examples\\n\\n**Input**: \\\"Apple Unveils New iPhone Model, Featuring Advanced AI Features\\\" \\n**Output**: \\\"Technology\\\"\\n\\n**Input**: \\\"Global Stocks Mixed as Investors Await Central Bank Decisions\\\" \\n**Output**: \\\"Markets\\\"\\n\\n**Input**: \\\"War in Ukraine: Latest Updates on Negotiation Status\\\" \\n**Output**: \\\"World\\\"\\n\\n**Input**: \\\"Microsoft in Talks to Acquire Gaming Company for $2 Billion\\\" \\n**Output**: \\\"Business\\\"\\n\\n**Input**: \\\"Manchester United Secures Win in Premier League Football Match\\\" \\n**Output**: \\\"Sports\\\" \\n\\n# Notes\\n\\n- If the headline appears to fit into more than one category, choose the most dominant theme.\\n- Keywords or phrases such as \\\"stocks\\\", \\\"company acquisition\\\", \\\"match\\\", or technological brands can be good indicators for classification.\\n\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n },\n {\n \"role\": \"user\",\n \"content\": \"Stock Markets Rally After Positive Economic Data Released\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n }\n ],\n \"output\": [\n {\n \"role\": \"assistant\",\n \"content\": \"Markets\",\n \"tool_call_id\": null,\n \"tool_calls\": null,\n \"function_call\": null\n }\n ],\n \"finish_reason\": \"stop\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"usage\": {\n \"total_tokens\": 325,\n \"completion_tokens\": 2,\n \"prompt_tokens\": 323,\n \"cached_tokens\": 0\n },\n \"error\": null,\n \"temperature\": 1.0,\n \"max_completion_tokens\": 2048,\n \"top_p\": 1.0,\n \"seed\": 42\n }\n}\n" } } } }, "/files": { "get": { "operationId": "listFiles", "tags": [ "Files" ], "summary": "Returns a list of files.", "parameters": [ { "in": "query", "name": "purpose", "required": false, "schema": { "type": "string" }, "description": "Only return files with the given purpose." }, { "name": "limit", "in": "query", "description": "A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.\n", "required": false, "schema": { "type": "integer", "default": 10000 } }, { "name": "order", "in": "query", "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n", "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.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFilesResponse" } } } } }, "x-oaiMeta": { "name": "List files", "group": "files", "examples": { "request": { "curl": "curl https://api.openai.com/v1/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.list()\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.files.list();\n\n for await (const file of list) {\n console.log(file);\n }\n}\n\nmain();" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 175,\n \"created_at\": 1613677385,\n \"expires_at\": 1677614202,\n \"filename\": \"salesOverview.pdf\",\n \"purpose\": \"assistants\",\n },\n {\n \"id\": \"file-abc456\",\n \"object\": \"file\",\n \"bytes\": 140,\n \"created_at\": 1613779121,\n \"expires_at\": 1677614202,\n \"filename\": \"puppy.jsonl\",\n \"purpose\": \"fine-tune\",\n }\n ],\n \"first_id\": \"file-abc123\",\n \"last_id\": \"file-abc456\",\n \"has_more\": false\n}\n" } } }, "post": { "operationId": "createFile", "tags": [ "Files" ], "summary": "Upload a file that can be used across various endpoints. Individual files\ncan be up to 512 MB, and each project can store up to 2.5 TB of files in\ntotal. There is no organization-wide storage limit. Uploads to this\nendpoint are rate-limited to 1,000 requests per minute per authenticated\nuser.\n\n- The Assistants API supports files up to 2 million tokens and of specific\n file types. See the [Assistants Tools guide](/docs/assistants/tools) for\n details.\n- The Fine-tuning API only supports `.jsonl` files. The input also has\n certain required formats for fine-tuning\n [chat](/docs/api-reference/fine-tuning/chat-input) or\n [completions](/docs/api-reference/fine-tuning/completions-input) models.\n- The Batch API only supports `.jsonl` files up to 200 MB in size. The input\n also has a specific required\n [format](/docs/api-reference/batch/request-input).\n- For Retrieval or `file_search` ingestion, upload files here first. If\n you need to attach multiple uploaded files to the same vector store, use\n [`/vector_stores/{vector_store_id}/file_batches`](/docs/api-reference/vector-stores-file-batches/createBatch)\n instead of attaching them one by one. Vector store attachment has separate\n limits from file upload, including 2,000 attached files per minute per\n organization.\n\nPlease [contact us](https://help.openai.com/) if you need to increase these\nstorage limits.\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateFileRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIFile" } } } } }, "x-oaiMeta": { "name": "Upload file", "group": "files", "description": "Uploads a file for later use across OpenAI APIs. Uploads to this endpoint are rate-limited to 1,000 requests per minute per authenticated user. For Retrieval or `file_search` ingestion, upload files here first. If you need to attach multiple uploaded files to the same vector store, use vector store file batches instead of attaching them one by one.\n", "examples": { "request": { "curl": "curl https://api.openai.com/v1/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F purpose=\"fine-tune\" \\\n -F file=\"@mydata.jsonl\"\n -F expires_after[anchor]=\"created_at\"\n -F expires_after[seconds]=2592000\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.create(\n file=open(\"mydata.jsonl\", \"rb\"),\n purpose=\"fine-tune\",\n expires_after={\n \"anchor\": \"created_at\",\n \"seconds\": 2592000\n }\n)\n", "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.create({\n file: fs.createReadStream(\"mydata.jsonl\"),\n purpose: \"fine-tune\",\n expires_after: {\n anchor: \"created_at\",\n seconds: 2592000\n }\n });\n\n console.log(file);\n}\n\nmain();" }, "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1677614202,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n}\n" } } } }, "/files/{file_id}": { "delete": { "operationId": "deleteFile", "tags": [ "Files" ], "summary": "Delete a file and remove it from all vector stores.", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the file to use for this request." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFileResponse" } } } } }, "x-oaiMeta": { "name": "Delete file", "group": "files", "examples": { "request": { "curl": "curl https://api.openai.com/v1/files/file-abc123 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.delete(\"file-abc123\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.delete(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();" }, "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"deleted\": true\n}\n" } } }, "get": { "operationId": "retrieveFile", "tags": [ "Files" ], "summary": "Returns information about a specific file.", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the file to use for this request." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIFile" } } } } }, "x-oaiMeta": { "name": "Retrieve file", "group": "files", "examples": { "request": { "curl": "curl https://api.openai.com/v1/files/file-abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.retrieve(\"file-abc123\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.retrieve(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();" }, "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1677614202,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n}\n" } } } }, "/files/{file_id}/content": { "get": { "operationId": "downloadFile", "tags": [ "Files" ], "summary": "Returns a response containing the contents of the specified file.", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the file to use for this request." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" } } } } }, "x-oaiMeta": { "name": "Retrieve file content", "group": "files", "examples": { "request": { "curl": "curl https://api.openai.com/v1/files/file-abc123/content \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" > file.jsonl\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncontent = client.files.content(\"file-abc123\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.files.content(\"file-abc123\");\n const content = await response.text();\n\n console.log(content);\n}\n\nmain();\n" } } } } }, "/fine_tuning/alpha/graders/run": { "post": { "operationId": "runGrader", "tags": [ "Fine-tuning" ], "summary": "Run a grader.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunGraderRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunGraderResponse" } } } } }, "x-oaiMeta": { "name": "Run grader", "beta": true, "group": "graders", "examples": [ { "title": "Score text alignment", "request": { "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/alpha/graders/run \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"grader\": {\n \"type\": \"score_model\",\n \"name\": \"Example score model grader\",\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"Score how close the reference answer is to the model answer on a 0-1 scale. Return only the score.\\n\\nReference answer: {{item.reference_answer}}\\n\\nModel answer: {{sample.output_text}}\"\n }\n ]\n }\n ],\n \"model\": \"gpt-5-mini\",\n \"sampling_params\": {\n \"temperature\": 1,\n \"top_p\": 1,\n \"seed\": 42\n }\n },\n \"item\": {\n \"reference_answer\": \"fuzzy wuzzy was a bear\"\n },\n \"model_sample\": \"fuzzy wuzzy was a bear\"\n }'\n", "python": "from openai import OpenAI\n\nclient = OpenAI()\nresult = client.fine_tuning.alpha.graders.run(\n grader={\n \"type\": \"score_model\",\n \"name\": \"Example score model grader\",\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"Score how close the reference answer is to the model answer on a 0-1 scale. Return only the score.\\n\\nReference answer: {{item.reference_answer}}\\n\\nModel answer: {{sample.output_text}}\",\n }\n ],\n }\n ],\n \"model\": \"gpt-5-mini\",\n \"sampling_params\": {\"temperature\": 1, \"top_p\": 1, \"seed\": 42},\n },\n item={\"reference_answer\": \"fuzzy wuzzy was a bear\"},\n model_sample=\"fuzzy wuzzy was a bear\",\n)\nprint(result)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nconst result = await openai.fineTuning.alpha.graders.run({\n grader: {\n type: \"score_model\",\n name: \"Example score model grader\",\n input: [\n {\n role: \"user\",\n content: [\n {\n type: \"input_text\",\n text: \"Score how close the reference answer is to the model answer on a 0-1 scale. Return only the score.\\n\\nReference answer: {{item.reference_answer}}\\n\\nModel answer: {{sample.output_text}}\",\n },\n ],\n },\n ],\n model: \"gpt-5-mini\",\n sampling_params: { temperature: 1, top_p: 1, seed: 42 },\n },\n item: { reference_answer: \"fuzzy wuzzy was a bear\" },\n model_sample: \"fuzzy wuzzy was a bear\",\n});\nconsole.log(result);\n" }, "response": "{\n \"reward\": 1.0,\n \"metadata\": {\n \"name\": \"Example score model grader\",\n \"type\": \"score_model\",\n \"errors\": {\n \"formula_parse_error\": false,\n \"sample_parse_error\": false,\n \"truncated_observation_error\": false,\n \"unresponsive_reward_error\": false,\n \"invalid_variable_error\": false,\n \"other_error\": false,\n \"python_grader_server_error\": false,\n \"python_grader_server_error_type\": null,\n \"python_grader_runtime_error\": false,\n \"python_grader_runtime_error_details\": null,\n \"model_grader_server_error\": false,\n \"model_grader_refusal_error\": false,\n \"model_grader_parse_error\": false,\n \"model_grader_server_error_details\": null\n },\n \"execution_time\": 4.365238428115845,\n \"scores\": {},\n \"token_usage\": {\n \"prompt_tokens\": 190,\n \"total_tokens\": 324,\n \"completion_tokens\": 134,\n \"cached_tokens\": 0\n },\n \"sampled_model_name\": \"gpt-4o-2024-08-06\"\n },\n \"sub_rewards\": {},\n \"model_grader_token_usage_per_model\": {\n \"gpt-4o-2024-08-06\": {\n \"prompt_tokens\": 190,\n \"total_tokens\": 324,\n \"completion_tokens\": 134,\n \"cached_tokens\": 0\n }\n }\n}\n" }, { "title": "Score an image caption", "request": { "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/alpha/graders/run \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"grader\": {\n \"type\": \"score_model\",\n \"name\": \"Image caption grader\",\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"Score how well the provided caption matches the image on a 0-1 scale. Only return the score.\\n\\nCaption: {{sample.output_text}}\"\n },\n {\n \"type\": \"input_image\",\n \"image_url\": \"https://example.com/dog-catching-ball.png\",\n \"file_id\": null,\n \"detail\": \"high\"\n }\n ]\n }\n ],\n \"model\": \"gpt-5-mini\",\n \"sampling_params\": {\n \"temperature\": 0.2\n }\n },\n \"item\": {\n \"expected_caption\": \"A golden retriever jumps to catch a tennis ball\"\n },\n \"model_sample\": \"A dog leaps to grab a tennis ball mid-air\"\n }'\n" } }, { "title": "Score an audio response", "request": { "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/alpha/graders/run \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"grader\": {\n \"type\": \"score_model\",\n \"name\": \"Audio clarity grader\",\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"Listen to the clip and return a confidence score from 0 to 1 that the speaker said: {{item.target_phrase}}\"\n },\n {\n \"type\": \"input_audio\",\n \"input_audio\": {\n \"data\": \"{{item.audio_clip_b64}}\",\n \"format\": \"mp3\"\n }\n }\n ]\n }\n ],\n \"model\": \"gpt-audio\",\n \"sampling_params\": {\n \"temperature\": 0.2,\n \"top_p\": 1,\n \"seed\": 123\n }\n },\n \"item\": {\n \"target_phrase\": \"Please deliver the package on Tuesday\",\n \"audio_clip_b64\": \"\"\n },\n \"model_sample\": \"Please deliver the package on Tuesday\"\n }'\n" } } ] } } }, "/fine_tuning/alpha/graders/validate": { "post": { "operationId": "validateGrader", "tags": [ "Fine-tuning" ], "summary": "Validate a grader.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateGraderRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateGraderResponse" } } } } }, "x-oaiMeta": { "name": "Validate grader", "beta": true, "group": "graders", "examples": { "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/alpha/graders/validate \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"grader\": {\n \"type\": \"string_check\",\n \"name\": \"Example string check grader\",\n \"input\": \"{{sample.output_text}}\",\n \"reference\": \"{{item.label}}\",\n \"operation\": \"eq\"\n }\n }'\n" }, "response": "{\n \"grader\": {\n \"type\": \"string_check\",\n \"name\": \"Example string check grader\",\n \"input\": \"{{sample.output_text}}\",\n \"reference\": \"{{item.label}}\",\n \"operation\": \"eq\"\n }\n}\n" } } } }, "/fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions": { "get": { "operationId": "listFineTuningCheckpointPermissions", "tags": [ "Fine-tuning" ], "summary": "**NOTE:** This endpoint requires an [admin API key](../admin-api-keys).\n\nOrganization owners can use this endpoint to view all permissions for a fine-tuned model checkpoint.\n", "parameters": [ { "in": "path", "name": "fine_tuned_model_checkpoint", "required": true, "schema": { "type": "string", "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" }, "description": "The ID of the fine-tuned model checkpoint to get permissions for.\n" }, { "name": "project_id", "in": "query", "description": "The ID of the project to get permissions for.", "required": false, "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Identifier for the last permission ID from the previous pagination request.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of permissions to retrieve.", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "order", "in": "query", "description": "The order in which to retrieve permissions.", "required": false, "schema": { "type": "string", "enum": [ "ascending", "descending" ], "default": "descending" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFineTuningCheckpointPermissionResponse" } } } } }, "x-oaiMeta": { "name": "List checkpoint permissions", "group": "fine-tuning", "examples": { "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"checkpoint.permission\",\n \"id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"created_at\": 1721764867,\n \"project_id\": \"proj_abGMw1llN8IrBb6SvvY5A1iH\"\n },\n {\n \"object\": \"checkpoint.permission\",\n \"id\": \"cp_enQCFmOTGj3syEpYVhBRLTSy\",\n \"created_at\": 1721764800,\n \"project_id\": \"proj_iqGMw1llN8IrBb6SvvY5A1oF\"\n },\n ],\n \"first_id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"last_id\": \"cp_enQCFmOTGj3syEpYVhBRLTSy\",\n \"has_more\": false\n}\n" } } }, "post": { "operationId": "createFineTuningCheckpointPermission", "tags": [ "Fine-tuning" ], "summary": "**NOTE:** Calling this endpoint requires an [admin API key](../admin-api-keys).\n\nThis enables organization owners to share fine-tuned models with other projects in their organization.\n", "parameters": [ { "in": "path", "name": "fine_tuned_model_checkpoint", "required": true, "schema": { "type": "string", "example": "ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd" }, "description": "The ID of the fine-tuned model checkpoint to create a permission for.\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFineTuningCheckpointPermissionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFineTuningCheckpointPermissionResponse" } } } } }, "x-oaiMeta": { "name": "Create checkpoint permissions", "group": "fine-tuning", "examples": { "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n -d '{\"project_ids\": [\"proj_abGMw1llN8IrBb6SvvY5A1iH\"]}'\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"checkpoint.permission\",\n \"id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"created_at\": 1721764867,\n \"project_id\": \"proj_abGMw1llN8IrBb6SvvY5A1iH\"\n }\n ],\n \"first_id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"last_id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"has_more\": false\n}\n" } } } }, "/fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions/{permission_id}": { "delete": { "operationId": "deleteFineTuningCheckpointPermission", "tags": [ "Fine-tuning" ], "summary": "**NOTE:** This endpoint requires an [admin API key](../admin-api-keys).\n\nOrganization owners can use this endpoint to delete a permission for a fine-tuned model checkpoint.\n", "parameters": [ { "in": "path", "name": "fine_tuned_model_checkpoint", "required": true, "schema": { "type": "string", "example": "ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd" }, "description": "The ID of the fine-tuned model checkpoint to delete a permission for.\n" }, { "in": "path", "name": "permission_id", "required": true, "schema": { "type": "string", "example": "cp_zc4Q7MP6XxulcVzj4MZdwsAB" }, "description": "The ID of the fine-tuned model checkpoint permission to delete.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFineTuningCheckpointPermissionResponse" } } } } }, "x-oaiMeta": { "name": "Delete checkpoint permission", "group": "fine-tuning", "examples": { "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/checkpoints/ft:gpt-4o-mini-2024-07-18:org:weather:B7R9VjQd/permissions/cp_zc4Q7MP6XxulcVzj4MZdwsAB \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "{\n \"object\": \"checkpoint.permission\",\n \"id\": \"cp_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"deleted\": true\n}\n" } } } }, "/fine_tuning/jobs": { "post": { "operationId": "createFineTuningJob", "tags": [ "Fine-tuning" ], "summary": "Creates a fine-tuning job which begins the process of creating a new model from a given dataset.\n\nResponse includes details of the enqueued job including job status and the name of the fine-tuned models once complete.\n\n[Learn more about fine-tuning](/docs/guides/model-optimization)\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFineTuningJobRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FineTuningJob" } } } } }, "x-oaiMeta": { "name": "Create fine-tuning job", "group": "fine-tuning", "examples": [ { "title": "Default", "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-BK7bzQj3FfZFXr7DbL6xJwfo\",\n \"model\": \"gpt-4o-mini\"\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.create(\n training_file=\"file-abc123\",\n model=\"gpt-4o-mini\"\n)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.create({\n training_file: \"file-abc123\"\n });\n\n console.log(fineTune);\n}\n\nmain();\n" }, "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": null,\n \"training_file\": \"file-abc123\",\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\",\n }\n }\n },\n \"metadata\": null\n}\n" }, { "title": "Epochs", "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-abc123\",\n \"model\": \"gpt-4o-mini\",\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"n_epochs\": 2\n }\n }\n }\n }'\n", "python": "from openai import OpenAI\nfrom openai.types.fine_tuning import SupervisedMethod, SupervisedHyperparameters\n\nclient = OpenAI()\n\nclient.fine_tuning.jobs.create(\n training_file=\"file-abc123\",\n model=\"gpt-4o-mini\",\n method={\n \"type\": \"supervised\",\n \"supervised\": SupervisedMethod(\n hyperparameters=SupervisedHyperparameters(\n n_epochs=2\n )\n )\n }\n)\n", "javascript": "import OpenAI from \"openai\";\nimport { SupervisedMethod, SupervisedHyperparameters } from \"openai/resources/fine-tuning/methods\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.create({\n training_file: \"file-abc123\",\n model: \"gpt-4o-mini\",\n method: {\n type: \"supervised\",\n supervised: {\n hyperparameters: {\n n_epochs: 2\n }\n }\n }\n });\n\n console.log(fineTune);\n}\n\nmain();\n" }, "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": null,\n \"training_file\": \"file-abc123\",\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": 2\n },\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": 2\n }\n }\n },\n \"metadata\": null,\n \"error\": {\n \"code\": null,\n \"message\": null,\n \"param\": null\n },\n \"finished_at\": null,\n \"seed\": 683058546,\n \"trained_tokens\": null,\n \"estimated_finish\": null,\n \"integrations\": [],\n \"user_provided_suffix\": null,\n \"usage_metrics\": null,\n \"shared_with_openai\": false\n}\n" }, { "title": "DPO", "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-abc123\",\n \"validation_file\": \"file-abc123\",\n \"model\": \"gpt-4o-mini\",\n \"method\": {\n \"type\": \"dpo\",\n \"dpo\": {\n \"hyperparameters\": {\n \"beta\": 0.1\n }\n }\n }\n }'\n", "python": "from openai import OpenAI\nfrom openai.types.fine_tuning import DpoMethod, DpoHyperparameters\n\nclient = OpenAI()\n\nclient.fine_tuning.jobs.create(\n training_file=\"file-abc\",\n validation_file=\"file-123\",\n model=\"gpt-4o-mini\",\n method={\n \"type\": \"dpo\",\n \"dpo\": DpoMethod(\n hyperparameters=DpoHyperparameters(beta=0.1)\n )\n }\n)\n" }, "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc\",\n \"model\": \"gpt-4o-mini\",\n \"created_at\": 1746130590,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-abc\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": \"file-123\",\n \"training_file\": \"file-abc\",\n \"method\": {\n \"type\": \"dpo\",\n \"dpo\": {\n \"hyperparameters\": {\n \"beta\": 0.1,\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\"\n }\n }\n },\n \"metadata\": null,\n \"error\": {\n \"code\": null,\n \"message\": null,\n \"param\": null\n },\n \"finished_at\": null,\n \"hyperparameters\": null,\n \"seed\": 1036326793,\n \"estimated_finish\": null,\n \"integrations\": [],\n \"user_provided_suffix\": null,\n \"usage_metrics\": null,\n \"shared_with_openai\": false\n}\n" }, { "title": "Reinforcement", "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-abc\",\n \"validation_file\": \"file-123\",\n \"model\": \"o4-mini\",\n \"method\": {\n \"type\": \"reinforcement\",\n \"reinforcement\": {\n \"grader\": {\n \"type\": \"string_check\",\n \"name\": \"Example string check grader\",\n \"input\": \"{{sample.output_text}}\",\n \"reference\": \"{{item.label}}\",\n \"operation\": \"eq\"\n },\n \"hyperparameters\": {\n \"reasoning_effort\": \"medium\"\n }\n }\n }\n }'\n", "python": "from openai import OpenAI\nfrom openai.types.fine_tuning import ReinforcementMethod, ReinforcementHyperparameters\nfrom openai.types.graders import StringCheckGrader\n\nclient = OpenAI()\n\nclient.fine_tuning.jobs.create(\n training_file=\"file-abc\",\n validation_file=\"file-123\",\n model=\"o4-mini\",\n method={\n \"type\": \"reinforcement\",\n \"reinforcement\": ReinforcementMethod(\n grader=StringCheckGrader(\n name=\"Example string check grader\",\n type=\"string_check\",\n input=\"{{item.label}}\",\n operation=\"eq\",\n reference=\"{{sample.output_text}}\"\n ),\n hyperparameters=ReinforcementHyperparameters(\n reasoning_effort=\"medium\",\n )\n )\n }, \n seed=42,\n)\n" }, "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"o4-mini\",\n \"created_at\": 1721764800,\n \"finished_at\": null,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"validating_files\",\n \"validation_file\": \"file-123\",\n \"training_file\": \"file-abc\",\n \"trained_tokens\": null,\n \"error\": {},\n \"user_provided_suffix\": null,\n \"seed\": 950189191,\n \"estimated_finish\": null,\n \"integrations\": [],\n \"method\": {\n \"type\": \"reinforcement\",\n \"reinforcement\": {\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\",\n \"eval_interval\": \"auto\",\n \"eval_samples\": \"auto\",\n \"compute_multiplier\": \"auto\",\n \"reasoning_effort\": \"medium\"\n },\n \"grader\": {\n \"type\": \"string_check\",\n \"name\": \"Example string check grader\",\n \"input\": \"{{sample.output_text}}\",\n \"reference\": \"{{item.label}}\",\n \"operation\": \"eq\"\n },\n \"response_format\": null\n }\n },\n \"metadata\": null,\n \"usage_metrics\": null,\n \"shared_with_openai\": false\n}\n \n" }, { "title": "Validation file", "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-abc123\",\n \"validation_file\": \"file-abc123\",\n \"model\": \"gpt-4o-mini\"\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.create(\n training_file=\"file-abc123\",\n validation_file=\"file-def456\",\n model=\"gpt-4o-mini\"\n)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.create({\n training_file: \"file-abc123\",\n validation_file: \"file-abc123\"\n });\n\n console.log(fineTune);\n}\n\nmain();\n" }, "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": \"file-abc123\",\n \"training_file\": \"file-abc123\",\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\",\n }\n }\n },\n \"metadata\": null\n}\n" }, { "title": "W&B Integration", "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/jobs \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"training_file\": \"file-abc123\",\n \"validation_file\": \"file-abc123\",\n \"model\": \"gpt-4o-mini\",\n \"integrations\": [\n {\n \"type\": \"wandb\",\n \"wandb\": {\n \"project\": \"my-wandb-project\",\n \"name\": \"ft-run-display-name\"\n \"tags\": [\n \"first-experiment\", \"v2\"\n ]\n }\n }\n ]\n }'\n" }, "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": \"file-abc123\",\n \"training_file\": \"file-abc123\",\n \"integrations\": [\n {\n \"type\": \"wandb\",\n \"wandb\": {\n \"project\": \"my-wandb-project\",\n \"entity\": None,\n \"run_id\": \"ftjob-abc123\"\n }\n }\n ],\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\",\n }\n }\n },\n \"metadata\": null\n}\n" } ] } }, "get": { "operationId": "listPaginatedFineTuningJobs", "tags": [ "Fine-tuning" ], "summary": "List your organization's fine-tuning jobs\n", "parameters": [ { "name": "after", "in": "query", "description": "Identifier for the last job from the previous pagination request.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of fine-tuning jobs to retrieve.", "required": false, "schema": { "type": "integer", "default": 20 } }, { "in": "query", "name": "metadata", "required": false, "schema": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "style": "deepObject", "explode": true, "description": "Optional metadata filter. To filter, use the syntax `metadata[k]=v`. Alternatively, set `metadata=null` to indicate no metadata.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPaginatedFineTuningJobsResponse" } } } } }, "x-oaiMeta": { "name": "List fine-tuning jobs", "group": "fine-tuning", "examples": { "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/jobs?limit=2&metadata[key]=value \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.list()\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.fineTuning.jobs.list();\n\n for await (const fineTune of list) {\n console.log(fineTune);\n }\n}\n\nmain();" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": null,\n \"training_file\": \"file-abc123\",\n \"metadata\": {\n \"key\": \"value\"\n }\n },\n { ... },\n { ... }\n ], \"has_more\": true\n}\n" } } } }, "/fine_tuning/jobs/{fine_tuning_job_id}": { "get": { "operationId": "retrieveFineTuningJob", "tags": [ "Fine-tuning" ], "summary": "Get info about a fine-tuning job.\n\n[Learn more about fine-tuning](/docs/guides/model-optimization)\n", "parameters": [ { "in": "path", "name": "fine_tuning_job_id", "required": true, "schema": { "type": "string", "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" }, "description": "The ID of the fine-tuning job.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FineTuningJob" } } } } }, "x-oaiMeta": { "name": "Retrieve fine-tuning job", "group": "fine-tuning", "examples": { "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.retrieve(\"ftjob-abc123\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.retrieve(\"ftjob-abc123\");\n\n console.log(fineTune);\n}\n\nmain();\n" }, "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"davinci-002\",\n \"created_at\": 1692661014,\n \"finished_at\": 1692661190,\n \"fine_tuned_model\": \"ft:davinci-002:my-org:custom_suffix:7q8mpxmy\",\n \"organization_id\": \"org-123\",\n \"result_files\": [\n \"file-abc123\"\n ],\n \"status\": \"succeeded\",\n \"validation_file\": null,\n \"training_file\": \"file-abc123\",\n \"hyperparameters\": {\n \"n_epochs\": 4,\n \"batch_size\": 1,\n \"learning_rate_multiplier\": 1.0\n },\n \"trained_tokens\": 5768,\n \"integrations\": [],\n \"seed\": 0,\n \"estimated_finish\": 0,\n \"method\": {\n \"type\": \"supervised\",\n \"supervised\": {\n \"hyperparameters\": {\n \"n_epochs\": 4,\n \"batch_size\": 1,\n \"learning_rate_multiplier\": 1.0\n }\n }\n }\n}\n" } } } }, "/fine_tuning/jobs/{fine_tuning_job_id}/cancel": { "post": { "operationId": "cancelFineTuningJob", "tags": [ "Fine-tuning" ], "summary": "Immediately cancel a fine-tune job.\n", "parameters": [ { "in": "path", "name": "fine_tuning_job_id", "required": true, "schema": { "type": "string", "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" }, "description": "The ID of the fine-tuning job to cancel.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FineTuningJob" } } } } }, "x-oaiMeta": { "name": "Cancel fine-tuning", "group": "fine-tuning", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/cancel \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.cancel(\"ftjob-abc123\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.cancel(\"ftjob-abc123\");\n\n console.log(fineTune);\n}\nmain();" }, "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"cancelled\",\n \"validation_file\": \"file-abc123\",\n \"training_file\": \"file-abc123\"\n}\n" } } } }, "/fine_tuning/jobs/{fine_tuning_job_id}/checkpoints": { "get": { "operationId": "listFineTuningJobCheckpoints", "tags": [ "Fine-tuning" ], "summary": "List checkpoints for a fine-tuning job.\n", "parameters": [ { "in": "path", "name": "fine_tuning_job_id", "required": true, "schema": { "type": "string", "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" }, "description": "The ID of the fine-tuning job to get checkpoints for.\n" }, { "name": "after", "in": "query", "description": "Identifier for the last checkpoint ID from the previous pagination request.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of checkpoints to retrieve.", "required": false, "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFineTuningJobCheckpointsResponse" } } } } }, "x-oaiMeta": { "name": "List fine-tuning checkpoints", "group": "fine-tuning", "examples": { "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/checkpoints \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"fine_tuning.job.checkpoint\",\n \"id\": \"ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"created_at\": 1721764867,\n \"fine_tuned_model_checkpoint\": \"ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:96olL566:ckpt-step-2000\",\n \"metrics\": {\n \"full_valid_loss\": 0.134,\n \"full_valid_mean_token_accuracy\": 0.874\n },\n \"fine_tuning_job_id\": \"ftjob-abc123\",\n \"step_number\": 2000\n },\n {\n \"object\": \"fine_tuning.job.checkpoint\",\n \"id\": \"ftckpt_enQCFmOTGj3syEpYVhBRLTSy\",\n \"created_at\": 1721764800,\n \"fine_tuned_model_checkpoint\": \"ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:7q8mpxmy:ckpt-step-1000\",\n \"metrics\": {\n \"full_valid_loss\": 0.167,\n \"full_valid_mean_token_accuracy\": 0.781\n },\n \"fine_tuning_job_id\": \"ftjob-abc123\",\n \"step_number\": 1000\n }\n ],\n \"first_id\": \"ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB\",\n \"last_id\": \"ftckpt_enQCFmOTGj3syEpYVhBRLTSy\",\n \"has_more\": true\n}\n" } } } }, "/fine_tuning/jobs/{fine_tuning_job_id}/events": { "get": { "operationId": "listFineTuningEvents", "tags": [ "Fine-tuning" ], "summary": "Get status updates for a fine-tuning job.\n", "parameters": [ { "in": "path", "name": "fine_tuning_job_id", "required": true, "schema": { "type": "string", "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" }, "description": "The ID of the fine-tuning job to get events for.\n" }, { "name": "after", "in": "query", "description": "Identifier for the last event from the previous pagination request.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of events to retrieve.", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFineTuningJobEventsResponse" } } } } }, "x-oaiMeta": { "name": "List fine-tuning events", "group": "fine-tuning", "examples": { "request": { "curl": "curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/events \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.list_events(\n fine_tuning_job_id=\"ftjob-abc123\",\n limit=2\n)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.fineTuning.list_events(id=\"ftjob-abc123\", limit=2);\n\n for await (const fineTune of list) {\n console.log(fineTune);\n }\n}\n\nmain();" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"fine_tuning.job.event\",\n \"id\": \"ft-event-ddTJfwuMVpfLXseO0Am0Gqjm\",\n \"created_at\": 1721764800,\n \"level\": \"info\",\n \"message\": \"Fine tuning job successfully completed\",\n \"data\": null,\n \"type\": \"message\"\n },\n {\n \"object\": \"fine_tuning.job.event\",\n \"id\": \"ft-event-tyiGuB72evQncpH87xe505Sv\",\n \"created_at\": 1721764800,\n \"level\": \"info\",\n \"message\": \"New fine-tuned model created: ft:gpt-4o-mini:openai::7p4lURel\",\n \"data\": null,\n \"type\": \"message\"\n }\n ],\n \"has_more\": true\n}\n" } } } }, "/fine_tuning/jobs/{fine_tuning_job_id}/pause": { "post": { "operationId": "pauseFineTuningJob", "tags": [ "Fine-tuning" ], "summary": "Pause a fine-tune job.\n", "parameters": [ { "in": "path", "name": "fine_tuning_job_id", "required": true, "schema": { "type": "string", "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" }, "description": "The ID of the fine-tuning job to pause.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FineTuningJob" } } } } }, "x-oaiMeta": { "name": "Pause fine-tuning", "group": "fine-tuning", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/pause \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.pause(\"ftjob-abc123\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.pause(\"ftjob-abc123\");\n\n console.log(fineTune);\n}\nmain();" }, "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"paused\",\n \"validation_file\": \"file-abc123\",\n \"training_file\": \"file-abc123\"\n}\n" } } } }, "/fine_tuning/jobs/{fine_tuning_job_id}/resume": { "post": { "operationId": "resumeFineTuningJob", "tags": [ "Fine-tuning" ], "summary": "Resume a fine-tune job.\n", "parameters": [ { "in": "path", "name": "fine_tuning_job_id", "required": true, "schema": { "type": "string", "example": "ft-AF1WoRqd3aJAHsqc9NY7iL8F" }, "description": "The ID of the fine-tuning job to resume.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FineTuningJob" } } } } }, "x-oaiMeta": { "name": "Resume fine-tuning", "group": "fine-tuning", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/resume \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.fine_tuning.jobs.resume(\"ftjob-abc123\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const fineTune = await openai.fineTuning.jobs.resume(\"ftjob-abc123\");\n\n console.log(fineTune);\n}\nmain();" }, "response": "{\n \"object\": \"fine_tuning.job\",\n \"id\": \"ftjob-abc123\",\n \"model\": \"gpt-4o-mini-2024-07-18\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": \"file-abc123\",\n \"training_file\": \"file-abc123\"\n}\n" } } } }, "/images/edits": { "post": { "operationId": "createImageEdit", "tags": [ "Images" ], "summary": "Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models (`gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`, and `chatgpt-image-latest`) and `dall-e-2`.", "description": "You can call this endpoint with either:\n\n- `multipart/form-data`: use binary uploads via `image` (and optional `mask`).\n- `application/json`: use `images` (and optional `mask`) as references with either `image_url` or `file_id`.\n\nNote that JSON requests use `images` (array) instead of the multipart `image` field.\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateImageEditRequest" }, "examples": { "multipart_edit": { "summary": "Multipart form upload (binary image + prompt)", "value": { "model": "gpt-image-1.5", "prompt": "Add a watercolor effect to this image", "image": "", "size": "1024x1024", "quality": "high" } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/EditImageBodyJsonParam" }, "examples": { "json_with_url": { "summary": "JSON request with image URL", "value": { "model": "gpt-image-1.5", "prompt": "Add a watercolor effect to this image", "images": [ { "image_url": "https://example.com/source-image.png" } ], "size": "1024x1024", "quality": "high" } }, "json_with_file_id": { "summary": "JSON request with uploaded file id", "value": { "model": "gpt-image-1.5", "prompt": "Replace the background with a snowy mountain scene", "images": [ { "file_id": "file-abc123" } ], "mask": { "file_id": "file-mask123" }, "output_format": "png", "output_compression": 100 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImagesResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ImageEditStreamEvent" } } } } }, "x-oaiMeta": { "name": "Create image edit", "group": "images", "examples": [ { "title": "Edit image", "request": { "curl": "curl -s -D >(grep -i x-request-id >&2) \\\n -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \\\n -X POST \"https://api.openai.com/v1/images/edits\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"model=gpt-image-1.5\" \\\n -F \"image[]=@body-lotion.png\" \\\n -F \"image[]=@bath-bomb.png\" \\\n -F \"image[]=@incense-kit.png\" \\\n -F \"image[]=@soap.png\" \\\n -F 'prompt=Create a lovely gift basket with these four items in it'\n", "python": "import base64\nfrom openai import OpenAI\nclient = OpenAI()\n\nprompt = \"\"\"\nGenerate a photorealistic image of a gift basket on a white background\nlabeled 'Relax & Unwind' with a ribbon and handwriting-like font,\ncontaining all the items in the reference pictures.\n\"\"\"\n\nresult = client.images.edit(\n model=\"gpt-image-1.5\",\n image=[\n open(\"body-lotion.png\", \"rb\"),\n open(\"bath-bomb.png\", \"rb\"),\n open(\"incense-kit.png\", \"rb\"),\n open(\"soap.png\", \"rb\"),\n ],\n prompt=prompt\n)\n\nimage_base64 = result.data[0].b64_json\nimage_bytes = base64.b64decode(image_base64)\n\n# Save the image to a file\nwith open(\"gift-basket.png\", \"wb\") as f:\n f.write(image_bytes)\n", "javascript": "import fs from \"fs\";\nimport OpenAI, { toFile } from \"openai\";\n\nconst client = new OpenAI();\n\nconst imageFiles = [\n \"bath-bomb.png\",\n \"body-lotion.png\",\n \"incense-kit.png\",\n \"soap.png\",\n];\n\nconst images = await Promise.all(\n imageFiles.map(async (file) =>\n await toFile(fs.createReadStream(file), null, {\n type: \"image/png\",\n })\n ),\n);\n\nconst rsp = await client.images.edit({\n model: \"gpt-image-1.5\",\n image: images,\n prompt: \"Create a lovely gift basket with these four items in it\",\n});\n\n// Save the image to a file\nconst image_base64 = rsp.data[0].b64_json;\nconst image_bytes = Buffer.from(image_base64, \"base64\");\nfs.writeFileSync(\"basket.png\", image_bytes);\n" } }, { "title": "Streaming", "request": { "curl": "curl -s -N -X POST \"https://api.openai.com/v1/images/edits\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"model=gpt-image-1.5\" \\\n -F \"image[]=@body-lotion.png\" \\\n -F \"image[]=@bath-bomb.png\" \\\n -F \"image[]=@incense-kit.png\" \\\n -F \"image[]=@soap.png\" \\\n -F 'prompt=Create a lovely gift basket with these four items in it' \\\n -F \"stream=true\"\n", "python": "from openai import OpenAI\n\nclient = OpenAI()\n\nprompt = \"\"\"\nGenerate a photorealistic image of a gift basket on a white background\nlabeled 'Relax & Unwind' with a ribbon and handwriting-like font,\ncontaining all the items in the reference pictures.\n\"\"\"\n\nstream = client.images.edit(\n model=\"gpt-image-1.5\",\n image=[\n open(\"body-lotion.png\", \"rb\"),\n open(\"bath-bomb.png\", \"rb\"),\n open(\"incense-kit.png\", \"rb\"),\n open(\"soap.png\", \"rb\"),\n ],\n prompt=prompt,\n stream=True\n)\n\nfor event in stream:\n print(event)\n", "javascript": "import fs from \"fs\";\nimport OpenAI, { toFile } from \"openai\";\n\nconst client = new OpenAI();\n\nconst imageFiles = [\n \"bath-bomb.png\",\n \"body-lotion.png\",\n \"incense-kit.png\",\n \"soap.png\",\n];\n\nconst images = await Promise.all(\n imageFiles.map(async (file) =>\n await toFile(fs.createReadStream(file), null, {\n type: \"image/png\",\n })\n ),\n);\n\nconst stream = await client.images.edit({\n model: \"gpt-image-1.5\",\n image: images,\n prompt: \"Create a lovely gift basket with these four items in it\",\n stream: true,\n});\n\nfor await (const event of stream) {\n console.log(event);\n}\n" }, "response": "event: image_edit.partial_image\ndata: {\"type\":\"image_edit.partial_image\",\"b64_json\":\"...\",\"partial_image_index\":0}\n\nevent: image_edit.completed\ndata: {\"type\":\"image_edit.completed\",\"b64_json\":\"...\",\"usage\":{\"total_tokens\":100,\"input_tokens\":50,\"output_tokens\":50,\"input_tokens_details\":{\"text_tokens\":10,\"image_tokens\":40}}}\n" } ] } } }, "/images/generations": { "post": { "operationId": "createImage", "tags": [ "Images" ], "summary": "Creates an image given a prompt. [Learn more](/docs/guides/images).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImageRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImagesResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ImageGenStreamEvent" } } } } }, "x-oaiMeta": { "name": "Create image", "group": "images", "examples": [ { "title": "Generate image", "request": { "curl": "curl https://api.openai.com/v1/images/generations \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-image-1.5\",\n \"prompt\": \"A cute baby sea otter\",\n \"n\": 1,\n \"size\": \"1024x1024\"\n }'\n", "python": "import base64\nfrom openai import OpenAI\nclient = OpenAI()\n\nimg = client.images.generate(\n model=\"gpt-image-1.5\",\n prompt=\"A cute baby sea otter\",\n n=1,\n size=\"1024x1024\"\n)\n\nimage_bytes = base64.b64decode(img.data[0].b64_json)\nwith open(\"output.png\", \"wb\") as f:\n f.write(image_bytes)\n", "javascript": "import OpenAI from \"openai\";\nimport { writeFile } from \"fs/promises\";\n\nconst client = new OpenAI();\n\nconst img = await client.images.generate({\n model: \"gpt-image-1.5\",\n prompt: \"A cute baby sea otter\",\n n: 1,\n size: \"1024x1024\"\n});\n\nconst imageBuffer = Buffer.from(img.data[0].b64_json, \"base64\");\nawait writeFile(\"output.png\", imageBuffer);\n" }, "response": "{\n \"created\": 1713833628,\n \"data\": [\n {\n \"b64_json\": \"...\"\n }\n ],\n \"usage\": {\n \"total_tokens\": 100,\n \"input_tokens\": 50,\n \"output_tokens\": 50,\n \"input_tokens_details\": {\n \"text_tokens\": 10,\n \"image_tokens\": 40\n }\n }\n}\n" }, { "title": "Streaming", "request": { "curl": "curl https://api.openai.com/v1/images/generations \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"gpt-image-1.5\",\n \"prompt\": \"A cute baby sea otter\",\n \"n\": 1,\n \"size\": \"1024x1024\",\n \"stream\": true\n }' \\\n --no-buffer\n", "python": "from openai import OpenAI\n\nclient = OpenAI()\n\nstream = client.images.generate(\n model=\"gpt-image-1.5\",\n prompt=\"A cute baby sea otter\",\n n=1,\n size=\"1024x1024\",\n stream=True\n)\n\nfor event in stream:\n print(event)\n", "javascript": "import OpenAI from \"openai\";\n\nconst client = new OpenAI();\n\nconst stream = await client.images.generate({\n model: \"gpt-image-1.5\",\n prompt: \"A cute baby sea otter\",\n n: 1,\n size: \"1024x1024\",\n stream: true,\n});\n\nfor await (const event of stream) {\n console.log(event);\n}\n" }, "response": "event: image_generation.partial_image\ndata: {\"type\":\"image_generation.partial_image\",\"b64_json\":\"...\",\"partial_image_index\":0}\n\nevent: image_generation.completed\ndata: {\"type\":\"image_generation.completed\",\"b64_json\":\"...\",\"usage\":{\"total_tokens\":100,\"input_tokens\":50,\"output_tokens\":50,\"input_tokens_details\":{\"text_tokens\":10,\"image_tokens\":40}}}\n" } ] } } }, "/images/variations": { "post": { "operationId": "createImageVariation", "tags": [ "Images" ], "summary": "Creates a variation of a given image. This endpoint only supports `dall-e-2`.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateImageVariationRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImagesResponse" } } } } }, "x-oaiMeta": { "name": "Create image variation", "group": "images", "examples": { "request": { "curl": "curl https://api.openai.com/v1/images/variations \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F image=\"@otter.png\" \\\n -F n=2 \\\n -F size=\"1024x1024\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nresponse = client.images.create_variation(\n image=open(\"image_edit_original.png\", \"rb\"),\n n=2,\n size=\"1024x1024\"\n)\n", "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const image = await openai.images.createVariation({\n image: fs.createReadStream(\"otter.png\"),\n });\n\n console.log(image.data);\n}\nmain();", "csharp": "using System;\n\nusing OpenAI.Images;\n\nImageClient client = new(\n model: \"dall-e-2\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nGeneratedImage image = client.GenerateImageVariation(imageFilePath: \"otter.png\");\n\nConsole.WriteLine(image.ImageUri);\n" }, "response": "{\n \"created\": 1589478378,\n \"data\": [\n {\n \"url\": \"https://...\"\n },\n {\n \"url\": \"https://...\"\n }\n ]\n}\n" } } } }, "/models": { "get": { "operationId": "listModels", "tags": [ "Models" ], "summary": "Lists the currently available models, and provides basic information about each one such as the owner and availability.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" } } } } }, "x-oaiMeta": { "name": "List models", "group": "models", "examples": { "request": { "curl": "curl https://api.openai.com/v1/models \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.models.list()\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.models.list();\n\n for await (const model of list) {\n console.log(model);\n }\n}\nmain();", "csharp": "using System;\n\nusing OpenAI.Models;\n\nOpenAIModelClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nforeach (var model in client.GetModels().Value)\n{\n Console.WriteLine(model.Id);\n}\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"model-id-0\",\n \"object\": \"model\",\n \"created\": 1686935002,\n \"owned_by\": \"organization-owner\",\n \"shutdown_date\": null\n },\n {\n \"id\": \"model-id-1\",\n \"object\": \"model\",\n \"created\": 1686935002,\n \"owned_by\": \"organization-owner\",\n \"shutdown_date\": null\n },\n {\n \"id\": \"model-id-2\",\n \"object\": \"model\",\n \"created\": 1686935002,\n \"owned_by\": \"openai\",\n \"shutdown_date\": \"2026-10-23\"\n },\n ]\n}\n" } } } }, "/models/{model}": { "get": { "operationId": "retrieveModel", "tags": [ "Models" ], "summary": "Retrieves a model instance, providing basic information about the model such as the owner and permissioning.", "parameters": [ { "in": "path", "name": "model", "required": true, "schema": { "type": "string", "example": "gpt-4o-mini" }, "description": "The ID of the model to use for this request" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } } }, "x-oaiMeta": { "name": "Retrieve model", "group": "models", "examples": { "request": { "curl": "curl https://api.openai.com/v1/models/VAR_chat_model_id \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.models.retrieve(\"VAR_chat_model_id\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const model = await openai.models.retrieve(\"VAR_chat_model_id\");\n\n console.log(model);\n}\n\nmain();", "csharp": "using System;\nusing System.ClientModel;\n\nusing OpenAI.Models;\n\n OpenAIModelClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nClientResult model = client.GetModel(\"babbage-002\");\nConsole.WriteLine(model.Value.Id);\n" }, "response": "{\n \"id\": \"VAR_chat_model_id\",\n \"object\": \"model\",\n \"created\": 1686935002,\n \"owned_by\": \"openai\",\n \"shutdown_date\": \"2026-10-23\"\n}\n" } } }, "delete": { "operationId": "deleteModel", "tags": [ "Models" ], "summary": "Delete a fine-tuned model. You must have the Owner role in your organization to delete a model.", "parameters": [ { "in": "path", "name": "model", "required": true, "schema": { "type": "string", "example": "ft:gpt-4o-mini:acemeco:suffix:abc123" }, "description": "The model to delete" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteModelResponse" } } } } }, "x-oaiMeta": { "name": "Delete a fine-tuned model", "group": "models", "examples": { "request": { "curl": "curl https://api.openai.com/v1/models/ft:gpt-4o-mini:acemeco:suffix:abc123 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.models.delete(\"ft:gpt-4o-mini:acemeco:suffix:abc123\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const model = await openai.models.delete(\"ft:gpt-4o-mini:acemeco:suffix:abc123\");\n \n console.log(model);\n}\nmain();", "csharp": "using System;\nusing System.ClientModel;\n\nusing OpenAI.Models;\n\nOpenAIModelClient client = new(\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nClientResult success = client.DeleteModel(\"ft:gpt-4o-mini:acemeco:suffix:abc123\");\nConsole.WriteLine(success);\n" }, "response": "{\n \"id\": \"ft:gpt-4o-mini:acemeco:suffix:abc123\",\n \"object\": \"model\",\n \"deleted\": true\n}\n" } } } }, "/moderations": { "post": { "operationId": "createModeration", "tags": [ "Moderations" ], "summary": "Classifies if text and/or image inputs are potentially harmful. Learn\nmore in the [moderation guide](/docs/guides/moderation).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModerationRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModerationResponse" } } } } }, "x-oaiMeta": { "name": "Create moderation", "group": "moderations", "examples": [ { "title": "Single string", "request": { "curl": "curl https://api.openai.com/v1/moderations \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"input\": \"I want to kill them.\"\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nmoderation = client.moderations.create(input=\"I want to kill them.\")\nprint(moderation)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const moderation = await openai.moderations.create({ input: \"I want to kill them.\" });\n\n console.log(moderation);\n}\nmain();\n", "csharp": "using System;\nusing System.ClientModel;\n\nusing OpenAI.Moderations;\n\nModerationClient client = new(\n model: \"omni-moderation-latest\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nClientResult moderation = client.ClassifyText(\"I want to kill them.\");\n" }, "response": "{\n \"id\": \"modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR\",\n \"model\": \"text-moderation-007\",\n \"results\": [\n {\n \"flagged\": true,\n \"categories\": {\n \"sexual\": false,\n \"hate\": false,\n \"harassment\": true,\n \"self-harm\": false,\n \"sexual/minors\": false,\n \"hate/threatening\": false,\n \"violence/graphic\": false,\n \"self-harm/intent\": false,\n \"self-harm/instructions\": false,\n \"harassment/threatening\": true,\n \"violence\": true\n },\n \"category_scores\": {\n \"sexual\": 0.000011726012417057063,\n \"hate\": 0.22706663608551025,\n \"harassment\": 0.5215635299682617,\n \"self-harm\": 2.227119921371923e-6,\n \"sexual/minors\": 7.107352217872176e-8,\n \"hate/threatening\": 0.023547329008579254,\n \"violence/graphic\": 0.00003391829886822961,\n \"self-harm/intent\": 1.646940972932498e-6,\n \"self-harm/instructions\": 1.1198755256458526e-9,\n \"harassment/threatening\": 0.5694745779037476,\n \"violence\": 0.9971134662628174\n }\n }\n ]\n}\n" }, { "title": "Image and text", "request": { "curl": "curl https://api.openai.com/v1/moderations \\\n -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"omni-moderation-latest\",\n \"input\": [\n { \"type\": \"text\", \"text\": \"...text to classify goes here...\" },\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://example.com/image.png\"\n }\n }\n ]\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nresponse = client.moderations.create(\n model=\"omni-moderation-latest\",\n input=[\n {\"type\": \"text\", \"text\": \"...text to classify goes here...\"},\n {\n \"type\": \"image_url\",\n \"image_url\": {\n \"url\": \"https://example.com/image.png\",\n # can also use base64 encoded image URLs\n # \"url\": \"data:image/jpeg;base64,abcdefg...\"\n }\n },\n ],\n)\n\nprint(response)\n", "javascript": "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nconst moderation = await openai.moderations.create({\n model: \"omni-moderation-latest\",\n input: [\n { type: \"text\", text: \"...text to classify goes here...\" },\n {\n type: \"image_url\",\n image_url: {\n url: \"https://example.com/image.png\"\n // can also use base64 encoded image URLs\n // url: \"data:image/jpeg;base64,abcdefg...\"\n }\n }\n ],\n});\n\nconsole.log(moderation);\n" }, "response": "{\n \"id\": \"modr-0d9740456c391e43c445bf0f010940c7\",\n \"model\": \"omni-moderation-latest\",\n \"results\": [\n {\n \"flagged\": true,\n \"categories\": {\n \"harassment\": true,\n \"harassment/threatening\": true,\n \"sexual\": false,\n \"hate\": false,\n \"hate/threatening\": false,\n \"illicit\": false,\n \"illicit/violent\": false,\n \"self-harm/intent\": false,\n \"self-harm/instructions\": false,\n \"self-harm\": false,\n \"sexual/minors\": false,\n \"violence\": true,\n \"violence/graphic\": true\n },\n \"category_scores\": {\n \"harassment\": 0.8189693396524255,\n \"harassment/threatening\": 0.804985420696006,\n \"sexual\": 1.573112165348997e-6,\n \"hate\": 0.007562942636942845,\n \"hate/threatening\": 0.004208854591835476,\n \"illicit\": 0.030535955153511665,\n \"illicit/violent\": 0.008925306722380033,\n \"self-harm/intent\": 0.00023023930975076432,\n \"self-harm/instructions\": 0.0002293869201073356,\n \"self-harm\": 0.012598046106750154,\n \"sexual/minors\": 2.212566909570261e-8,\n \"violence\": 0.9999992735124786,\n \"violence/graphic\": 0.843064871157054\n },\n \"category_applied_input_types\": {\n \"harassment\": [\n \"text\"\n ],\n \"harassment/threatening\": [\n \"text\"\n ],\n \"sexual\": [\n \"text\",\n \"image\"\n ],\n \"hate\": [\n \"text\"\n ],\n \"hate/threatening\": [\n \"text\"\n ],\n \"illicit\": [\n \"text\"\n ],\n \"illicit/violent\": [\n \"text\"\n ],\n \"self-harm/intent\": [\n \"text\",\n \"image\"\n ],\n \"self-harm/instructions\": [\n \"text\",\n \"image\"\n ],\n \"self-harm\": [\n \"text\",\n \"image\"\n ],\n \"sexual/minors\": [\n \"text\"\n ],\n \"violence\": [\n \"text\",\n \"image\"\n ],\n \"violence/graphic\": [\n \"text\",\n \"image\"\n ]\n }\n }\n ]\n}\n" } ] } } }, "/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" }, "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 \"expires_at\": 1714063533,\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" } } }, "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" }, "expires_in_seconds": { "type": "integer", "minimum": 1, "maximum": 31536000, "example": 2592000, "description": "The number of seconds until the API key expires. Omit this field for a key that does not expire." } } } } } }, "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 \"expires_in_seconds\": 2592000\n }'\n" }, "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 \"expires_at\": 1714063533,\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" } } } }, "/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" }, "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" } } }, "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" }, "response": "{\n \"id\": \"key_abc\",\n \"object\": \"organization.admin_api_key.deleted\",\n \"deleted\": true\n}\n" } } } }, "/organization/audit_logs": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "List user actions and configuration changes within this organization.", "operationId": "list-audit-logs", "tags": [ "Audit Logs" ], "parameters": [ { "name": "effective_at", "in": "query", "description": "Return only events whose `effective_at` (Unix seconds) is in this range.", "required": false, "schema": { "type": "object", "properties": { "gt": { "type": "integer", "description": "Return only events whose `effective_at` (Unix seconds) is greater than this value." }, "gte": { "type": "integer", "description": "Return only events whose `effective_at` (Unix seconds) is greater than or equal to this value." }, "lt": { "type": "integer", "description": "Return only events whose `effective_at` (Unix seconds) is less than this value." }, "lte": { "type": "integer", "description": "Return only events whose `effective_at` (Unix seconds) is less than or equal to this value." } } } }, { "name": "project_ids[]", "in": "query", "description": "Return only events for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "event_types[]", "in": "query", "description": "Return only events with a `type` in one of these values. For example, `project.created`. For all options, see the documentation for the [audit log object](/docs/api-reference/audit-logs/object).", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEventType" } } }, { "name": "actor_ids[]", "in": "query", "description": "Return only events performed by these actors. Can be a user ID, a service account ID, or an api key tracking ID.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "actor_emails[]", "in": "query", "description": "Return only events performed by users with these emails.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "resource_ids[]", "in": "query", "description": "Return only events performed on these targets. For example, a project ID updated. For ChatGPT connector role events, use the workspace connector resource ID shown in `details.id`, such as `__`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "tenant_only", "in": "query", "description": "Return only tenant-scoped events associated with this organization. Required for tenant-scoped events such as `role.bound_to_resource` and `role.unbound_from_resource`. When `true`, all supplied event types must be tenant-scoped.", "required": false, "schema": { "type": "boolean", "default": false } }, { "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } }, { "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.\n", "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, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Audit logs listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditLogsResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List audit logs", "group": "audit-logs", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/audit_logs \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"audit_log-xxx_yyyymmdd\",\n \"type\": \"project.archived\",\n \"effective_at\": 1722461446,\n \"actor\": {\n \"type\": \"api_key\",\n \"api_key\": {\n \"type\": \"user\",\n \"user\": {\n \"id\": \"user-xxx\",\n \"email\": \"user@example.com\"\n }\n }\n },\n \"project.archived\": {\n \"id\": \"proj_abc\"\n },\n },\n {\n \"id\": \"audit_log-yyy__20240101\",\n \"type\": \"api_key.updated\",\n \"effective_at\": 1720804190,\n \"actor\": {\n \"type\": \"session\",\n \"session\": {\n \"user\": {\n \"id\": \"user-xxx\",\n \"email\": \"user@example.com\"\n },\n \"ip_address\": \"127.0.0.1\",\n \"user_agent\": \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\",\n \"ja3\": \"a497151ce4338a12c4418c44d375173e\",\n \"ja4\": \"q13d0313h3_55b375c5d22e_c7319ce65786\",\n \"ip_address_details\": {\n \"country\": \"US\",\n \"city\": \"San Francisco\",\n \"region\": \"California\",\n \"region_code\": \"CA\",\n \"asn\": \"1234\",\n \"latitude\": \"37.77490\",\n \"longitude\": \"-122.41940\"\n }\n }\n },\n \"api_key.updated\": {\n \"id\": \"key_xxxx\",\n \"data\": {\n \"scopes\": [\"resource_2.operation_2\"]\n }\n },\n }\n ],\n \"first_id\": \"audit_log-xxx__20240101\",\n \"last_id\": \"audit_log_yyy__20240101\",\n \"has_more\": true\n}\n" } } } }, "/organization/certificates": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "List uploaded certificates for this organization.", "operationId": "listOrganizationCertificates", "tags": [ "Certificates" ], "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } }, { "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.\n", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Certificates listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCertificatesResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List organization certificates", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/certificates \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n \"first_id\": \"cert_abc\",\n \"last_id\": \"cert_abc\",\n \"has_more\": false\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Upload a certificate to the organization. This does **not** automatically activate the certificate.\n\nOrganizations can upload up to 50 certificates.\n", "operationId": "uploadCertificate", "tags": [ "Certificates" ], "requestBody": { "description": "The certificate upload payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadCertificateRequest" } } } }, "responses": { "200": { "description": "Certificate uploaded successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Upload certificate", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/certificates \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"name\": \"My Example Certificate\",\n \"certificate\": \"-----BEGIN CERTIFICATE-----\\\\nMIIDeT...\\\\n-----END CERTIFICATE-----\"\n}'\n" }, "response": "{\n \"object\": \"certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n}\n" } } } }, "/organization/certificates/activate": { "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Activate certificates at the organization level.\n\nYou can atomically and idempotently activate up to 10 certificates at a time.\n", "operationId": "activateOrganizationCertificates", "tags": [ "Certificates" ], "requestBody": { "description": "The certificate activation payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToggleCertificatesRequest" } } } }, "responses": { "200": { "description": "Certificates activated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCertificateActivationResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Activate certificates for organization", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/certificates/activate \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"certificate_ids\": [\"cert_abc\", \"cert_def\"]\n}'\n" }, "response": "{\n \"object\": \"organization.certificate.activation\",\n \"data\": [\n {\n \"object\": \"organization.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n {\n \"object\": \"organization.certificate\",\n \"id\": \"cert_def\",\n \"name\": \"My Example Certificate 2\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n}\n" } } } }, "/organization/certificates/deactivate": { "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deactivate certificates at the organization level.\n\nYou can atomically and idempotently deactivate up to 10 certificates at a time.\n", "operationId": "deactivateOrganizationCertificates", "tags": [ "Certificates" ], "requestBody": { "description": "The certificate deactivation payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToggleCertificatesRequest" } } } }, "responses": { "200": { "description": "Certificates deactivated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCertificateDeactivationResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Deactivate certificates for organization", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/certificates/deactivate \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"certificate_ids\": [\"cert_abc\", \"cert_def\"]\n}'\n" }, "response": "{\n \"object\": \"organization.certificate.deactivation\",\n \"data\": [\n {\n \"object\": \"organization.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": false,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n {\n \"object\": \"organization.certificate\",\n \"id\": \"cert_def\",\n \"name\": \"My Example Certificate 2\",\n \"active\": false,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n}\n" } } } }, "/organization/certificates/{certificate_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get a certificate that has been uploaded to the organization.\n\nYou can get a certificate regardless of whether it is active or not.\n", "operationId": "getCertificate", "tags": [ "Certificates" ], "parameters": [ { "name": "certificate_id", "in": "path", "description": "Unique ID of the certificate to retrieve.", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "A list of additional fields to include in the response. Currently the only supported value is `content` to fetch the PEM content of the certificate.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "content" ] } } } ], "responses": { "200": { "description": "Certificate retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Get certificate", "group": "administration", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/certificates/cert_abc?include[]=content\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\"\n" }, "response": "{\n \"object\": \"certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 1234567,\n \"expires_at\": 12345678,\n \"content\": \"-----BEGIN CERTIFICATE-----MIIDeT...-----END CERTIFICATE-----\"\n }\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Modify a certificate. Note that only the name can be modified.\n", "operationId": "modifyCertificate", "tags": [ "Certificates" ], "parameters": [ { "name": "certificate_id", "in": "path", "description": "Unique ID of the certificate to modify.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The certificate modification payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifyCertificateRequest" } } } }, "responses": { "200": { "description": "Certificate modified successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Modify certificate", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/certificates/cert_abc \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"name\": \"Renamed Certificate\"\n}'\n" }, "response": "{\n \"object\": \"certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"Renamed Certificate\",\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Delete a certificate from the organization.\n\nThe certificate must be inactive for the organization and all projects.\n", "operationId": "deleteCertificate", "tags": [ "Certificates" ], "parameters": [ { "name": "certificate_id", "in": "path", "description": "Unique ID of the certificate to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Certificate deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCertificateResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Delete certificate", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/certificates/cert_abc \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\"\n" }, "response": "{\n \"object\": \"certificate.deleted\",\n \"id\": \"cert_abc\"\n}\n" } } } }, "/organization/costs": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get costs details for the organization.", "operationId": "usage-costs", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently only `1d` is supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1d" ], "default": "1d" } }, { "name": "project_ids", "in": "query", "description": "Return only costs for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "api_key_ids", "in": "query", "description": "Return only costs for these API keys.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "group_by", "in": "query", "description": "Group the costs by the specified fields. Support fields include `project_id`, `line_item`, `api_key_id` and any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "line_item", "api_key_id" ] } } }, { "name": "limit", "in": "query", "description": "A limit on the number of buckets to be returned. Limit can range between 1 and 180, and the default is 7.\n", "required": false, "schema": { "type": "integer", "default": 7 } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Costs data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Costs", "group": "usage-costs", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.costs.result\",\n \"amount\": {\n \"value\": 0.06,\n \"currency\": \"usd\"\n },\n \"line_item\": null,\n \"project_id\": null,\n \"api_key_id\": null,\n \"quantity\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/data_retention": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves organization data retention controls.", "operationId": "retrieve-organization-data-retention", "tags": [ "Data retention" ], "responses": { "200": { "description": "Organization data retention controls retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDataRetention" } } } } }, "x-oaiMeta": { "name": "Retrieve organization data retention", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/data_retention \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.data_retention\",\n \"type\": \"modified_abuse_monitoring\"\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates organization data retention controls.", "operationId": "update-organization-data-retention", "tags": [ "Data retention" ], "requestBody": { "description": "The desired organization data retention setting.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationDataRetentionBody" } } } }, "responses": { "200": { "description": "Organization data retention controls updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDataRetention" } } } } }, "x-oaiMeta": { "name": "Update organization data retention", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/data_retention \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"retention_type\": \"modified_abuse_monitoring\"\n }'\n" }, "response": "{\n \"object\": \"organization.data_retention\",\n \"type\": \"modified_abuse_monitoring\"\n}\n" } } } }, "/organization/groups": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists all groups in the organization.", "operationId": "list-groups", "tags": [ "Groups" ], "parameters": [ { "name": "limit", "in": "query", "description": "A limit on the number of groups to be returned. Limit can range between 0 and 1000, and the default is 100.\n", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 100 } }, { "name": "after", "in": "query", "description": "A cursor for use in pagination. `after` is a group ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with group_abc, your subsequent call can include `after=group_abc` in order to fetch the next page of the list.\n", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Specifies the sort order of the returned groups.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "Groups listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List groups", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/groups?limit=20&order=asc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"is_scim_managed\": false\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Creates a new group in the organization.", "operationId": "create-group", "tags": [ "Groups" ], "requestBody": { "description": "Parameters for the group you want to create.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupBody" } } } }, "responses": { "200": { "description": "Group created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create group", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/groups \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Support Team\"\n }'\n" }, "response": "{\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"is_scim_managed\": false\n}\n" } } } }, "/organization/groups/{group_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves a group.", "operationId": "retrieve-group", "tags": [ "Groups" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Group retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve group", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"is_scim_managed\": false,\n \"group_type\": \"group\"\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates a group's information.", "operationId": "update-group", "tags": [ "Groups" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "New attributes to set on the group.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGroupBody" } } } }, "responses": { "200": { "description": "Group updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResourceWithSuccess" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Update group", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Escalations\"\n }'\n" }, "response": "{\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Escalations\",\n \"created_at\": 1711471533,\n \"is_scim_managed\": false\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deletes a group from the organization.", "operationId": "delete-group", "tags": [ "Groups" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Group deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupDeletedResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Delete group", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"group.deleted\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"deleted\": true\n}\n" } } } }, "/organization/groups/{group_id}/roles": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists the organization roles assigned to a group within the organization.", "operationId": "list-group-role-assignments", "tags": [ "Group organization role assignments" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group whose organization role assignments you want to list.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "A limit on the number of organization role assignments to return.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000 } }, { "name": "after", "in": "query", "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing organization roles.", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order for the returned organization roles.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Group organization role assignments listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List group organization role assignments", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {}\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Assigns an organization role to a group within the organization.", "operationId": "assign-group-role", "tags": [ "Group organization role assignments" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group that should receive the organization role.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Identifies the organization role to assign to the group.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAssignOrganizationGroupRoleBody" } } } }, "responses": { "200": { "description": "Organization role assigned to the group successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupRoleAssignment" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Assign organization role to group", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_id\": \"role_01J1F8ROLE01\"\n }'\n" }, "response": "{\n \"object\": \"group.role\",\n \"group\": {\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"scim_managed\": false\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n }\n}\n" } } } }, "/organization/groups/{group_id}/roles/{role_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves an organization role assigned to a group.", "operationId": "retrieve-group-role", "tags": [ "Group organization role assignments" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the organization role to retrieve for the group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization role retrieved for the group successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignedRoleDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve group organization role", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": null,\n \"metadata\": {},\n \"assignment_sources\": null\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Unassigns an organization role from a group within the organization.", "operationId": "unassign-group-role", "tags": [ "Group organization role assignments" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group to modify.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the organization role to remove from the group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization role unassigned from the group successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedRoleAssignmentResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Unassign organization role from group", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"group.role.deleted\",\n \"deleted\": true\n}\n" } } } }, "/organization/groups/{group_id}/users": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists the users assigned to a group.", "operationId": "list-group-users", "tags": [ "Group users" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "A limit on the number of users to be returned. Limit can range between 0 and 1000, and the default is 100.\n", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 100 } }, { "name": "after", "in": "query", "description": "A cursor for use in pagination. Provide the ID of the last user from the previous list response to retrieve the next page.\n", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Specifies the sort order of users in the list.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Group users listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List group users", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Adds a user to a group.", "operationId": "add-group-user", "tags": [ "Group users" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Identifies the user that should be added to the group.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupUserBody" } } } }, "responses": { "200": { "description": "User added to the group successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUserAssignment" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Add group user", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"user_id\": \"user_abc123\"\n }'\n" }, "response": "{\n \"object\": \"group.user\",\n \"user_id\": \"user_abc123\",\n \"group_id\": \"group_01J1F8ABCDXYZ\"\n}\n" } } } }, "/organization/groups/{group_id}/users/{user_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves a user in a group.", "operationId": "retrieve-group-user", "tags": [ "Group users" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "The ID of the user to retrieve from the group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User retrieved from the group successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupMemberUser" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve group user", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users/user_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\",\n \"picture\": null,\n \"is_service_account\": false,\n \"user_type\": \"user\"\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Removes a user from a group.", "operationId": "remove-group-user", "tags": [ "Group users" ], "parameters": [ { "name": "group_id", "in": "path", "description": "The ID of the group to update.", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "The ID of the user to remove from the group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User removed from the group successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUserDeletedResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Remove group user", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/groups/group_01J1F8ABCDXYZ/users/user_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"group.user.deleted\",\n \"deleted\": true\n}\n" } } } }, "/organization/invites": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Returns a list of invites in the organization.", "operationId": "list-invites", "tags": [ "Invites" ], "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } }, { "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.\n", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invites listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteListResponse" } } } } }, "x-oaiMeta": { "name": "List invites", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/invites?after=invite-abc&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.invite\",\n \"id\": \"invite-abc\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"status\": \"accepted\",\n \"created_at\": 1711471533,\n \"expires_at\": 1711471533,\n \"accepted_at\": 1711471533\n }\n ],\n \"first_id\": \"invite-abc\",\n \"last_id\": \"invite-abc\",\n \"has_more\": false\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Create an invite for a user to the organization. The invite must be accepted by the user before they have access to the organization.", "operationId": "inviteUser", "tags": [ "Invites" ], "requestBody": { "description": "The invite request payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteRequest" } } } }, "responses": { "200": { "description": "User invited successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } } }, "x-oaiMeta": { "name": "Create invite", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/invites \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"email\": \"anotheruser@example.com\",\n \"role\": \"reader\",\n \"projects\": [\n {\n \"id\": \"project-xyz\",\n \"role\": \"member\"\n },\n {\n \"id\": \"project-abc\",\n \"role\": \"owner\"\n }\n ]\n }'\n" }, "response": "{\n \"object\": \"organization.invite\",\n \"id\": \"invite-def\",\n \"email\": \"anotheruser@example.com\",\n \"role\": \"reader\",\n \"status\": \"pending\",\n \"created_at\": 1711471533,\n \"expires_at\": 1711471533,\n \"accepted_at\": null,\n \"projects\": [\n {\n \"id\": \"project-xyz\",\n \"role\": \"member\"\n },\n {\n \"id\": \"project-abc\",\n \"role\": \"owner\"\n }\n ]\n}\n" } } } }, "/organization/invites/{invite_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves an invite.", "operationId": "retrieve-invite", "tags": [ "Invites" ], "parameters": [ { "in": "path", "name": "invite_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the invite to retrieve." } ], "responses": { "200": { "description": "Invite retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } } }, "x-oaiMeta": { "name": "Retrieve invite", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/invites/invite-abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.invite\",\n \"id\": \"invite-abc\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"status\": \"accepted\",\n \"created_at\": 1711471533,\n \"expires_at\": 1711471533,\n \"accepted_at\": 1711471533\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Delete an invite. If the invite has already been accepted, it cannot be deleted.", "operationId": "delete-invite", "tags": [ "Invites" ], "parameters": [ { "in": "path", "name": "invite_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the invite to delete." } ], "responses": { "200": { "description": "Invite deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteDeleteResponse" } } } } }, "x-oaiMeta": { "name": "Delete invite", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/invites/invite-abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.invite.deleted\",\n \"id\": \"invite-abc\",\n \"deleted\": true\n}\n" } } } }, "/organization/projects": { "get": { "summary": "Returns a list of projects.", "operationId": "list-projects", "security": [ { "AdminApiKeyAuth": [] } ], "tags": [ "Projects" ], "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } }, { "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.\n", "required": false, "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If `true` returns all projects including those that have been `archived`. Archived projects are not included by default." } ], "responses": { "200": { "description": "Projects listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectListResponse" } } } } }, "x-oaiMeta": { "name": "List projects", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects?after=proj_abc&limit=20&include_archived=false \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"proj_abc\",\n \"object\": \"organization.project\",\n \"name\": \"Project example\",\n \"created_at\": 1711471533,\n \"archived_at\": null,\n \"status\": \"active\"\n }\n ],\n \"first_id\": \"proj-abc\",\n \"last_id\": \"proj-xyz\",\n \"has_more\": false\n}\n" } } }, "post": { "summary": "Create a new project in the organization. Projects can be created and archived, but cannot be deleted.", "operationId": "create-project", "security": [ { "AdminApiKeyAuth": [] } ], "tags": [ "Projects" ], "requestBody": { "description": "The project create request payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreateRequest" } } } }, "responses": { "200": { "description": "Project created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } }, "x-oaiMeta": { "name": "Create project", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Project ABC\"\n }'\n" }, "response": "{\n \"id\": \"proj_abc\",\n \"object\": \"organization.project\",\n \"name\": \"Project ABC\",\n \"created_at\": 1711471533,\n \"archived_at\": null,\n \"status\": \"active\"\n}\n" } } } }, "/organization/projects/{project_id}": { "get": { "summary": "Retrieves a project.", "operationId": "retrieve-project", "security": [ { "AdminApiKeyAuth": [] } ], "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } }, "x-oaiMeta": { "name": "Retrieve project", "group": "administration", "description": "Retrieve a project.", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"proj_abc\",\n \"object\": \"organization.project\",\n \"name\": \"Project example\",\n \"created_at\": 1711471533,\n \"archived_at\": null,\n \"status\": \"active\"\n}\n" } } }, "post": { "summary": "Modifies a project in the organization.", "operationId": "modify-project", "security": [ { "AdminApiKeyAuth": [] } ], "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The project update request payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdateRequest" } } } }, "responses": { "200": { "description": "Project updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Error response when updating the default project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "name": "Modify project", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Project DEF\"\n }'\n" } } } } }, "/organization/projects/{project_id}/api_keys": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Returns a list of API keys in the project.", "operationId": "list-project-api-keys", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } }, { "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.\n", "required": false, "schema": { "type": "string" } }, { "name": "owner_project_access", "in": "query", "description": "Filter API keys by whether the owner currently has effective access to the project. Use `active` for owners with access, `inactive` for owners without access, or `any` for all enabled project API keys. If omitted, the endpoint applies its existing membership-based visibility rules, which may exclude some enabled keys.\n", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "any" ] } } ], "responses": { "200": { "description": "Project API keys listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectApiKeyListResponse" } } } } }, "x-oaiMeta": { "name": "List project API keys", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys?after=key_abc&limit=20&owner_project_access=any \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.project.api_key\",\n \"redacted_value\": \"sk-abc...def\",\n \"name\": \"My API Key\",\n \"created_at\": 1711471533,\n \"last_used_at\": 1711471534,\n \"id\": \"key_abc\",\n \"owner_project_access\": \"active\",\n \"owner\": {\n \"type\": \"user\",\n \"user\": {\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"created_at\": 1711471533\n }\n }\n }\n ],\n \"first_id\": \"key_abc\",\n \"last_id\": \"key_xyz\",\n \"has_more\": false\n}\n" } } } }, "/organization/projects/{project_id}/api_keys/{api_key_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves an API key in the project.", "operationId": "retrieve-project-api-key", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "api_key_id", "in": "path", "description": "The ID of the API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project API key retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectApiKey" } } } } }, "x-oaiMeta": { "name": "Retrieve project API key", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.project.api_key\",\n \"redacted_value\": \"sk-abc...def\",\n \"name\": \"My API Key\",\n \"created_at\": 1711471533,\n \"last_used_at\": 1711471534,\n \"id\": \"key_abc\",\n \"owner_project_access\": \"active\",\n \"owner\": {\n \"type\": \"user\",\n \"user\": {\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"created_at\": 1711471533\n }\n }\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deletes an API key from the project.\n\nReturns confirmation of the key deletion, or an error if the key belonged to\na service account.\n", "operationId": "delete-project-api-key", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "api_key_id", "in": "path", "description": "The ID of the API key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project API key deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectApiKeyDeleteResponse" } } } }, "400": { "description": "Error response for various conditions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "name": "Delete project API key", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/api_keys/key_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.project.api_key.deleted\",\n \"id\": \"key_abc\",\n \"deleted\": true\n}\n" } } } }, "/organization/projects/{project_id}/archive": { "post": { "summary": "Archives a project in the organization. Archived projects cannot be used or updated.", "operationId": "archive-project", "security": [ { "AdminApiKeyAuth": [] } ], "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project archived successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } }, "x-oaiMeta": { "name": "Archive project", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/archive \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"proj_abc\",\n \"object\": \"organization.project\",\n \"name\": \"Project DEF\",\n \"created_at\": 1711471533,\n \"archived_at\": 1711471533,\n \"status\": \"archived\"\n}\n" } } } }, "/organization/projects/{project_id}/certificates": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "List certificates for this project.", "operationId": "listProjectCertificates", "tags": [ "Certificates" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } }, { "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.\n", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Certificates listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProjectCertificatesResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List project certificates", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/certificates \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.project.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n \"first_id\": \"cert_abc\",\n \"last_id\": \"cert_abc\",\n \"has_more\": false\n}\n" } } } }, "/organization/projects/{project_id}/certificates/activate": { "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Activate certificates at the project level.\n\nYou can atomically and idempotently activate up to 10 certificates at a time.\n", "operationId": "activateProjectCertificates", "tags": [ "Certificates" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The certificate activation payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToggleCertificatesRequest" } } } }, "responses": { "200": { "description": "Certificates activated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationProjectCertificateActivationResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Activate certificates for project", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/activate \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"certificate_ids\": [\"cert_abc\", \"cert_def\"]\n}'\n" }, "response": "{\n \"object\": \"organization.project.certificate.activation\",\n \"data\": [\n {\n \"object\": \"organization.project.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n {\n \"object\": \"organization.project.certificate\",\n \"id\": \"cert_def\",\n \"name\": \"My Example Certificate 2\",\n \"active\": true,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n}\n" } } } }, "/organization/projects/{project_id}/certificates/deactivate": { "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deactivate certificates at the project level. You can atomically and \nidempotently deactivate up to 10 certificates at a time.\n", "operationId": "deactivateProjectCertificates", "tags": [ "Certificates" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The certificate deactivation payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToggleCertificatesRequest" } } } }, "responses": { "200": { "description": "Certificates deactivated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationProjectCertificateDeactivationResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Deactivate certificates for project", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/certificates/deactivate \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\" \\\n-d '{\n \"certificate_ids\": [\"cert_abc\", \"cert_def\"]\n}'\n" }, "response": "{\n \"object\": \"organization.project.certificate.deactivation\",\n \"data\": [\n {\n \"object\": \"organization.project.certificate\",\n \"id\": \"cert_abc\",\n \"name\": \"My Example Certificate\",\n \"active\": false,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n {\n \"object\": \"organization.project.certificate\",\n \"id\": \"cert_def\",\n \"name\": \"My Example Certificate 2\",\n \"active\": false,\n \"created_at\": 1234567,\n \"certificate_details\": {\n \"valid_at\": 12345667,\n \"expires_at\": 12345678\n }\n },\n ],\n}\n" } } } }, "/organization/projects/{project_id}/data_retention": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves project data retention controls.", "operationId": "retrieve-project-data-retention", "tags": [ "Data retention" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to inspect.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project data retention controls retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDataRetention" } } } } }, "x-oaiMeta": { "name": "Retrieve project data retention", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/data_retention \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"project.data_retention\",\n \"type\": \"organization_default\"\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates project data retention controls.", "operationId": "update-project-data-retention", "tags": [ "Data retention" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The desired project data retention setting.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectDataRetentionBody" } } } }, "responses": { "200": { "description": "Project data retention controls updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDataRetention" } } } } }, "x-oaiMeta": { "name": "Update project data retention", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/data_retention \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"retention_type\": \"modified_abuse_monitoring\"\n }'\n" }, "response": "{\n \"object\": \"project.data_retention\",\n \"type\": \"modified_abuse_monitoring\"\n}\n" } } } }, "/organization/projects/{project_id}/groups": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists the groups that have access to a project.", "operationId": "list-project-groups", "tags": [ "Project groups" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "A limit on the number of project groups to return. Defaults to 20.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "description": "Cursor for pagination. Provide the ID of the last group from the previous response to fetch the next page.", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order for the returned groups.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "Project groups listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectGroupListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List project groups", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc123/groups?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"project.group\",\n \"project_id\": \"proj_abc123\",\n \"group_id\": \"group_01J1F8ABCDXYZ\",\n \"group_name\": \"Support Team\",\n \"created_at\": 1711471533\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Grants a group access to a project.", "operationId": "add-project-group", "tags": [ "Project groups" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Identifies the group and role to assign to the project.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteProjectGroupBody" } } } }, "responses": { "200": { "description": "Group granted access to the project successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectGroup" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Add project group", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc123/groups \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"group_id\": \"group_01J1F8ABCDXYZ\",\n \"role\": \"role_01J1F8PROJ\"\n }'\n" }, "response": "{\n \"object\": \"project.group\",\n \"project_id\": \"proj_abc123\",\n \"group_id\": \"group_01J1F8ABCDXYZ\",\n \"group_name\": \"Support Team\",\n \"created_at\": 1711471533\n}\n" } } } }, "/organization/projects/{project_id}/groups/{group_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves a project's group.", "operationId": "retrieve-project-group", "tags": [ "Project groups" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "path", "description": "The ID of the group to retrieve.", "required": true, "schema": { "type": "string" } }, { "name": "group_type", "in": "query", "description": "The type of group to retrieve.", "required": false, "schema": { "type": "string", "enum": [ "group", "tenant_group" ], "default": "group" } } ], "responses": { "200": { "description": "Project group retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectGroup" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve project group", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc123/groups/group_01J1F8ABCDXYZ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"project.group\",\n \"project_id\": \"proj_abc123\",\n \"group_id\": \"group_01J1F8ABCDXYZ\",\n \"group_name\": \"Support Team\",\n \"group_type\": \"group\",\n \"created_at\": 1711471533\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Revokes a group's access to a project.", "operationId": "remove-project-group", "tags": [ "Project groups" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "path", "description": "The ID of the group to remove from the project.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Group removed from the project successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectGroupDeletedResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Remove project group", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc123/groups/group_01J1F8ABCDXYZ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"project.group.deleted\",\n \"deleted\": true\n}\n" } } } }, "/organization/projects/{project_id}/hosted_tool_permissions": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Returns hosted tool permissions for a project.", "operationId": "retrieve-project-hosted-tool-permissions", "tags": [ "Hosted tools" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project hosted tool permissions retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectHostedToolPermissions" } } } } }, "x-oaiMeta": { "name": "Retrieve project hosted tool permissions", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/hosted_tool_permissions \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"file_search\": {\n \"enabled\": true\n },\n \"web_search\": {\n \"enabled\": true\n },\n \"image_generation\": {\n \"enabled\": true\n },\n \"mcp\": {\n \"enabled\": true\n },\n \"code_interpreter\": {\n \"enabled\": true\n }\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates hosted tool permissions for a project.", "operationId": "update-project-hosted-tool-permissions", "tags": [ "Hosted tools" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The project hosted tool permissions update request payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectHostedToolPermissionsUpdateRequest" } } } }, "responses": { "200": { "description": "Project hosted tool permissions updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectHostedToolPermissions" } } } } }, "x-oaiMeta": { "name": "Modify project hosted tool permissions", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/hosted_tool_permissions \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"file_search\": {\n \"enabled\": true\n },\n \"image_generation\": {\n \"enabled\": false\n }\n }'\n" }, "response": "{\n \"file_search\": {\n \"enabled\": true\n },\n \"web_search\": {\n \"enabled\": true\n },\n \"image_generation\": {\n \"enabled\": false\n },\n \"mcp\": {\n \"enabled\": true\n },\n \"code_interpreter\": {\n \"enabled\": true\n }\n}\n" } } } }, "/organization/projects/{project_id}/model_permissions": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Returns model permissions for a project.", "operationId": "retrieve-project-model-permissions", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project model permissions retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectModelPermissions" } } } } }, "x-oaiMeta": { "name": "Retrieve project model permissions", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"project.model_permissions\",\n \"mode\": \"allow_list\",\n \"model_ids\": [\n \"gpt-4.1\",\n \"o3\"\n ]\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates model permissions for a project.", "operationId": "update-project-model-permissions", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The project model permissions update request payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectModelPermissionsUpdateRequest" } } } }, "responses": { "200": { "description": "Project model permissions updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectModelPermissions" } } } } }, "x-oaiMeta": { "name": "Modify project model permissions", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"mode\": \"deny_list\",\n \"model_ids\": [\n \"o3\"\n ]\n }'\n" }, "response": "{\n \"object\": \"project.model_permissions\",\n \"mode\": \"deny_list\",\n \"model_ids\": [\n \"o3\"\n ]\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deletes model permissions for a project.", "operationId": "delete-project-model-permissions", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project model permissions deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectModelPermissionsDeleteResponse" } } } } }, "x-oaiMeta": { "name": "Delete project model permissions", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/model_permissions \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"project.model_permissions.deleted\",\n \"deleted\": true\n}\n" } } } }, "/organization/projects/{project_id}/rate_limits": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Returns the rate limits per model for a project.", "operationId": "list-project-rate-limits", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "A limit on the number of objects to be returned. The default is 100.\n", "required": false, "schema": { "type": "integer", "default": 100 } }, { "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.\n", "required": false, "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, beginning with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.\n", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project rate limits listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRateLimitListResponse" } } } } }, "x-oaiMeta": { "name": "List project rate limits", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/rate_limits?after=rl_xxx&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"project.rate_limit\",\n \"id\": \"rl-ada\",\n \"model\": \"ada\",\n \"max_requests_per_1_minute\": 600,\n \"max_tokens_per_1_minute\": 150000,\n \"max_images_per_1_minute\": 10\n }\n ],\n \"first_id\": \"rl-ada\",\n \"last_id\": \"rl-ada\",\n \"has_more\": false\n}\n", "error_response": "{\n \"code\": 404,\n \"message\": \"The project {project_id} was not found\"\n}\n" } } } }, "/organization/projects/{project_id}/rate_limits/{rate_limit_id}": { "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates a project rate limit.", "operationId": "update-project-rate-limits", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "rate_limit_id", "in": "path", "description": "The ID of the rate limit.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The project rate limit update request payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRateLimitUpdateRequest" } } } }, "responses": { "200": { "description": "Project rate limit updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRateLimit" } } } }, "400": { "description": "Error response for various conditions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "name": "Modify project rate limit", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/rate_limits/rl_xxx \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"max_requests_per_1_minute\": 500\n }'\n" }, "response": "{\n \"object\": \"project.rate_limit\",\n \"id\": \"rl-ada\",\n \"model\": \"ada\",\n \"max_requests_per_1_minute\": 600,\n \"max_tokens_per_1_minute\": 150000,\n \"max_images_per_1_minute\": 10\n }\n", "error_response": "{\n \"code\": 404,\n \"message\": \"The project {project_id} was not found\"\n}\n" } } } }, "/organization/projects/{project_id}/service_accounts": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Returns a list of service accounts in the project.", "operationId": "list-project-service-accounts", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } }, { "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.\n", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project service accounts listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectServiceAccountListResponse" } } } }, "400": { "description": "Error response when project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "name": "List project service accounts", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts?after=custom_id&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.project.service_account\",\n \"id\": \"svc_acct_abc\",\n \"name\": \"Service Account\",\n \"role\": \"owner\",\n \"created_at\": 1711471533\n }\n ],\n \"first_id\": \"svc_acct_abc\",\n \"last_id\": \"svc_acct_xyz\",\n \"has_more\": false\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Creates a new service account in the project. By default, this also returns an unredacted API key for the service account.", "operationId": "create-project-service-account", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The project service account create request payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectServiceAccountCreateRequest" } } } }, "responses": { "200": { "description": "Project service account created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectServiceAccountCreateResponse" } } } }, "400": { "description": "Error response when project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "name": "Create project service account", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Production App\"\n }'\n" }, "response": "{\n \"object\": \"organization.project.service_account\",\n \"id\": \"svc_acct_abc\",\n \"name\": \"Production App\",\n \"role\": \"member\",\n \"created_at\": 1711471533,\n \"api_key\": {\n \"object\": \"organization.project.service_account.api_key\",\n \"value\": \"sk-abcdefghijklmnop123\",\n \"name\": \"Secret Key\",\n \"created_at\": 1711471533,\n \"id\": \"key_abc\"\n }\n}\n" } } } }, "/organization/projects/{project_id}/service_accounts/{service_account_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves a service account in the project.", "operationId": "retrieve-project-service-account", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "service_account_id", "in": "path", "description": "The ID of the service account.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project service account retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectServiceAccount" } } } } }, "x-oaiMeta": { "name": "Retrieve project service account", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.project.service_account\",\n \"id\": \"svc_acct_abc\",\n \"name\": \"Service Account\",\n \"role\": \"owner\",\n \"created_at\": 1711471533\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates a service account in the project.", "operationId": "update-project-service-account", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "service_account_id", "in": "path", "description": "The ID of the service account.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update on the service account.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectServiceAccountBody" } } } }, "responses": { "200": { "description": "Project service account updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectServiceAccount" } } } } }, "x-oaiMeta": { "name": "Update project service account", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Updated service account\",\n \"role\": \"member\"\n }'\n" }, "response": "{\n \"object\": \"organization.project.service_account\",\n \"id\": \"svc_acct_abc\",\n \"name\": \"Updated service account\",\n \"role\": \"member\",\n \"created_at\": 1711471533\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deletes a service account from the project.\n\nReturns confirmation of service account deletion, or an error if the project\nis archived (archived projects have no service accounts).\n", "operationId": "delete-project-service-account", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "service_account_id", "in": "path", "description": "The ID of the service account.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project service account deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectServiceAccountDeleteResponse" } } } } }, "x-oaiMeta": { "name": "Delete project service account", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/service_accounts/svc_acct_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.project.service_account.deleted\",\n \"id\": \"svc_acct_abc\",\n \"deleted\": true\n}\n" } } } }, "/organization/projects/{project_id}/spend_alerts": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists project spend alerts.", "operationId": "list-project-spend-alerts", "tags": [ "Spend alerts" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "A limit on the number of spend alerts to return. Defaults to 20.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "order", "in": "query", "description": "Sort order for the returned spend alerts.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "after", "in": "query", "description": "Cursor for pagination. Provide the ID of the last spend alert from the previous response to fetch the next page.", "required": false, "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Cursor for pagination. Provide the ID of the first spend alert from the previous response to fetch the previous page.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project spend alerts listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectSpendAlertListResource" } } } } }, "x-oaiMeta": { "name": "List project spend alerts", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts?limit=20&order=asc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"alert_abc123\",\n \"object\": \"project.spend_alert\",\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }\n ],\n \"first_id\": \"alert_abc123\",\n \"last_id\": \"alert_abc123\",\n \"has_more\": false\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Creates a project spend alert.", "operationId": "create-project-spend-alert", "tags": [ "Spend alerts" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Parameters for the project spend alert you want to create.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpendAlertBody" } } } }, "responses": { "200": { "description": "Project spend alert created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectSpendAlert" } } } } }, "x-oaiMeta": { "name": "Create project spend alert", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }'\n" }, "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"project.spend_alert\",\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" } } } }, "/organization/projects/{project_id}/spend_alerts/{alert_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves a project spend alert.", "operationId": "retrieve-project-spend-alert", "tags": [ "Spend alerts" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "alert_id", "in": "path", "description": "The ID of the spend alert to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project spend alert retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectSpendAlert" } } } } }, "x-oaiMeta": { "name": "Retrieve project spend alert", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"project.spend_alert\",\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates a project spend alert.", "operationId": "update-project-spend-alert", "tags": [ "Spend alerts" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } }, { "name": "alert_id", "in": "path", "description": "The ID of the spend alert to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update on the project spend alert.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpendAlertBody" } } } }, "responses": { "200": { "description": "Project spend alert updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectSpendAlert" } } } } }, "x-oaiMeta": { "name": "Update project spend alert", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }'\n" }, "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"project.spend_alert\",\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deletes a project spend alert.", "operationId": "delete-project-spend-alert", "tags": [ "Spend alerts" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } }, { "name": "alert_id", "in": "path", "description": "The ID of the spend alert to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project spend alert deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectSpendAlertDeletedResource" } } } } }, "x-oaiMeta": { "name": "Delete project spend alert", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"project.spend_alert.deleted\",\n \"deleted\": true\n}\n" } } } }, "/organization/projects/{project_id}/users": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Returns a list of users in the project.", "operationId": "list-project-users", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } }, { "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.\n", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project users listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUserListResponse" } } } }, "400": { "description": "Error response when project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "name": "List project users", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/users?after=user_abc&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.project.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n }\n ],\n \"first_id\": \"user-abc\",\n \"last_id\": \"user-xyz\",\n \"has_more\": false\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Adds a user to the project. Users must already be members of the organization to be added to a project.", "operationId": "create-project-user", "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } } ], "tags": [ "Projects" ], "requestBody": { "description": "The project user create request payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUserCreateRequest" } } } }, "responses": { "200": { "description": "User added to project successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUser" } } } }, "400": { "description": "Error response for various conditions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "name": "Create project user", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"user_id\": \"user_abc\",\n \"role\": \"member\"\n }'\n" }, "response": "{\n \"object\": \"organization.project.user\",\n \"id\": \"user_abc\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n" } } } }, "/organization/projects/{project_id}/users/{user_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves a user in the project.", "operationId": "retrieve-project-user", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project user retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUser" } } } } }, "x-oaiMeta": { "name": "Retrieve project user", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.project.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Modifies a user's role in the project.", "operationId": "modify-project-user", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The project user update request payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUserUpdateRequest" } } } }, "responses": { "200": { "description": "Project user's role updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUser" } } } }, "400": { "description": "Error response for various conditions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "name": "Modify project user", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role\": \"owner\"\n }'\n" }, "response": "{\n \"object\": \"organization.project.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deletes a user from the project.\n\nReturns confirmation of project user deletion, or an error if the project is\narchived (archived projects have no users).\n", "operationId": "delete-project-user", "tags": [ "Projects" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project user deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUserDeleteResponse" } } } }, "400": { "description": "Error response for various conditions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "name": "Delete project user", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.project.user.deleted\",\n \"id\": \"user_abc\",\n \"deleted\": true\n}\n" } } } }, "/organization/roles": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists the roles configured for the organization.", "operationId": "list-roles", "tags": [ "Roles" ], "parameters": [ { "name": "limit", "in": "query", "description": "A limit on the number of roles to return. Defaults to 1000.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 1000 } }, { "name": "after", "in": "query", "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles.", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order for the returned roles.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "Roles listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRoleListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List organization roles", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/roles?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Creates a custom role for the organization.", "operationId": "create-role", "tags": [ "Roles" ], "requestBody": { "description": "Parameters for the role you want to create.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCreateOrganizationRoleBody" } } } }, "responses": { "200": { "description": "Role created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create organization role", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"description\": \"Allows managing organization groups\"\n }'\n" }, "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n}\n" } } } }, "/organization/roles/{role_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves an organization role.", "operationId": "retrieve-role", "tags": [ "Roles" ], "parameters": [ { "name": "role_id", "in": "path", "description": "The ID of the role to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Role retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve organization role", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates an existing organization role.", "operationId": "update-role", "tags": [ "Roles" ], "parameters": [ { "name": "role_id", "in": "path", "description": "The ID of the role to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update on the role.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicUpdateOrganizationRoleBody" } } } }, "responses": { "200": { "description": "Role updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Update organization role", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"description\": \"Allows managing organization groups\"\n }'\n" }, "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deletes a custom role from the organization.", "operationId": "delete-role", "tags": [ "Roles" ], "parameters": [ { "name": "role_id", "in": "path", "description": "The ID of the role to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Role deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDeletedResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Delete organization role", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"role.deleted\",\n \"id\": \"role_01J1F8ROLE01\",\n \"deleted\": true\n}\n" } } } }, "/organization/spend_alerts": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists organization spend alerts.", "operationId": "list-organization-spend-alerts", "tags": [ "Spend alerts" ], "parameters": [ { "name": "limit", "in": "query", "description": "A limit on the number of spend alerts to return. Defaults to 20.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100 } }, { "name": "order", "in": "query", "description": "Sort order for the returned spend alerts.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "after", "in": "query", "description": "Cursor for pagination. Provide the ID of the last spend alert from the previous response to fetch the next page.", "required": false, "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "Cursor for pagination. Provide the ID of the first spend alert from the previous response to fetch the previous page.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization spend alerts listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSpendAlertListResource" } } } } }, "x-oaiMeta": { "name": "List organization spend alerts", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/spend_alerts?limit=20&order=asc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"alert_abc123\",\n \"object\": \"organization.spend_alert\",\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }\n ],\n \"first_id\": \"alert_abc123\",\n \"last_id\": \"alert_abc123\",\n \"has_more\": false\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Creates an organization spend alert.", "operationId": "create-organization-spend-alert", "tags": [ "Spend alerts" ], "requestBody": { "description": "Parameters for the organization spend alert you want to create.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpendAlertBody" } } } }, "responses": { "200": { "description": "Organization spend alert created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSpendAlert" } } } } }, "x-oaiMeta": { "name": "Create organization spend alert", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/spend_alerts \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }'\n" }, "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"organization.spend_alert\",\n \"threshold_amount\": 100000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" } } } }, "/organization/spend_alerts/{alert_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves an organization spend alert.", "operationId": "retrieve-organization-spend-alert", "tags": [ "Spend alerts" ], "parameters": [ { "name": "alert_id", "in": "path", "description": "The ID of the spend alert to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization spend alert retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSpendAlert" } } } } }, "x-oaiMeta": { "name": "Retrieve organization spend alert", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"organization.spend_alert\",\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates an organization spend alert.", "operationId": "update-organization-spend-alert", "tags": [ "Spend alerts" ], "parameters": [ { "name": "alert_id", "in": "path", "description": "The ID of the spend alert to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update on the organization spend alert.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpendAlertBody" } } } }, "responses": { "200": { "description": "Organization spend alert updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSpendAlert" } } } } }, "x-oaiMeta": { "name": "Update organization spend alert", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n }'\n" }, "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"organization.spend_alert\",\n \"threshold_amount\": 150000,\n \"currency\": \"USD\",\n \"interval\": \"month\",\n \"notification_channel\": {\n \"type\": \"email\",\n \"recipients\": [\"finance@example.com\"],\n \"subject_prefix\": \"OpenAI spend alert\"\n }\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deletes an organization spend alert.", "operationId": "delete-organization-spend-alert", "tags": [ "Spend alerts" ], "parameters": [ { "name": "alert_id", "in": "path", "description": "The ID of the spend alert to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization spend alert deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSpendAlertDeletedResource" } } } } }, "x-oaiMeta": { "name": "Delete organization spend alert", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/spend_alerts/alert_abc123 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"alert_abc123\",\n \"object\": \"organization.spend_alert.deleted\",\n \"deleted\": true\n}\n" } } } }, "/organization/usage/audio_speeches": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get audio speeches usage details for the organization.", "operationId": "usage-audio-speeches", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1m", "1h", "1d" ], "default": "1d" } }, { "name": "project_ids", "in": "query", "description": "Return only usage for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "user_ids", "in": "query", "description": "Return only usage for these users.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "api_key_ids", "in": "query", "description": "Return only usage for these API keys.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "models", "in": "query", "description": "Return only usage for these models.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "group_by", "in": "query", "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "api_key_id", "model" ] } } }, { "name": "limit", "in": "query", "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Audio speeches", "group": "usage-audio-speeches", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.audio_speeches.result\",\n \"characters\": 45,\n \"num_model_requests\": 1,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/usage/audio_transcriptions": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get audio transcriptions usage details for the organization.", "operationId": "usage-audio-transcriptions", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1m", "1h", "1d" ], "default": "1d" } }, { "name": "project_ids", "in": "query", "description": "Return only usage for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "user_ids", "in": "query", "description": "Return only usage for these users.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "api_key_ids", "in": "query", "description": "Return only usage for these API keys.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "models", "in": "query", "description": "Return only usage for these models.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "group_by", "in": "query", "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "api_key_id", "model" ] } } }, { "name": "limit", "in": "query", "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Audio transcriptions", "group": "usage-audio-transcriptions", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.audio_transcriptions.result\",\n \"seconds\": 20,\n \"num_model_requests\": 1,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/usage/code_interpreter_sessions": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get code interpreter sessions usage details for the organization.", "operationId": "usage-code-interpreter-sessions", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1m", "1h", "1d" ], "default": "1d" } }, { "name": "project_ids", "in": "query", "description": "Return only usage for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "group_by", "in": "query", "description": "Group the usage data by the specified fields. Support fields include `project_id`.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id" ] } } }, { "name": "limit", "in": "query", "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Code interpreter sessions", "group": "usage-code-interpreter-sessions", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.code_interpreter_sessions.result\",\n \"num_sessions\": 1,\n \"project_id\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/usage/completions": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get completions usage details for the organization.", "operationId": "usage-completions", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1m", "1h", "1d" ], "default": "1d" } }, { "name": "project_ids", "in": "query", "description": "Return only usage for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "user_ids", "in": "query", "description": "Return only usage for these users.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "api_key_ids", "in": "query", "description": "Return only usage for these API keys.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "models", "in": "query", "description": "Return only usage for these models.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "batch", "in": "query", "description": "If `true`, return batch jobs only. If `false`, return non-batch jobs only. By default, return both.\n", "required": false, "schema": { "type": "boolean" } }, { "name": "group_by", "in": "query", "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `batch`, `service_tier` or any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "api_key_id", "model", "batch", "service_tier" ] } } }, { "name": "limit", "in": "query", "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Completions", "group": "usage-completions", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.completions.result\",\n \"input_tokens\": 1000,\n \"input_cached_tokens\": 400,\n \"input_cache_write_tokens\": 100,\n \"input_uncached_tokens\": 500,\n \"output_tokens\": 500,\n \"input_text_tokens\": 400,\n \"output_text_tokens\": 400,\n \"input_cached_text_tokens\": 300,\n \"input_audio_tokens\": 50,\n \"input_cached_audio_tokens\": 50,\n \"output_audio_tokens\": 50,\n \"input_image_tokens\": 50,\n \"input_cached_image_tokens\": 50,\n \"output_image_tokens\": 50,\n \"num_model_requests\": 5,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null,\n \"batch\": null,\n \"service_tier\": null\n }\n ]\n }\n ],\n \"has_more\": true,\n \"next_page\": \"page_AAAAAGdGxdEiJdKOAAAAAGcqsYA=\"\n}\n" } } } }, "/organization/usage/embeddings": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get embeddings usage details for the organization.", "operationId": "usage-embeddings", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1m", "1h", "1d" ], "default": "1d" } }, { "name": "project_ids", "in": "query", "description": "Return only usage for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "user_ids", "in": "query", "description": "Return only usage for these users.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "api_key_ids", "in": "query", "description": "Return only usage for these API keys.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "models", "in": "query", "description": "Return only usage for these models.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "group_by", "in": "query", "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "api_key_id", "model" ] } } }, { "name": "limit", "in": "query", "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Embeddings", "group": "usage-embeddings", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.embeddings.result\",\n \"input_tokens\": 16,\n \"num_model_requests\": 2,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/usage/file_search_calls": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get file search calls usage details for the organization.", "operationId": "usage-file-search-calls", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1m", "1h", "1d" ], "default": "1d" } }, { "name": "project_ids", "in": "query", "description": "Return only usage for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "user_ids", "in": "query", "description": "Return only usage for these users.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "api_key_ids", "in": "query", "description": "Return only usage for these API keys.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "vector_store_ids", "in": "query", "description": "Return only usage for these vector stores.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "group_by", "in": "query", "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `vector_store_id` or any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "api_key_id", "vector_store_id" ] } } }, { "name": "limit", "in": "query", "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "File search calls", "group": "usage-file-search-calls", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/usage/file_search_calls?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.file_searches.result\",\n \"num_requests\": 2,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"vector_store_id\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/usage/images": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get images usage details for the organization.", "operationId": "usage-images", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1m", "1h", "1d" ], "default": "1d" } }, { "name": "sources", "in": "query", "description": "Return only usages for these sources. Possible values are `image.generation`, `image.edit`, `image.variation` or any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "image.generation", "image.edit", "image.variation" ] } } }, { "name": "sizes", "in": "query", "description": "Return only usages for these image sizes. Possible values are `256x256`, `512x512`, `1024x1024`, `1792x1792`, `1024x1792` or any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "256x256", "512x512", "1024x1024", "1792x1792", "1024x1792" ] } } }, { "name": "project_ids", "in": "query", "description": "Return only usage for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "user_ids", "in": "query", "description": "Return only usage for these users.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "api_key_ids", "in": "query", "description": "Return only usage for these API keys.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "models", "in": "query", "description": "Return only usage for these models.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "group_by", "in": "query", "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `size`, `source` or any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "api_key_id", "model", "size", "source" ] } } }, { "name": "limit", "in": "query", "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Images", "group": "usage-images", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.images.result\",\n \"images\": 2,\n \"num_model_requests\": 2,\n \"size\": null,\n \"source\": null,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/usage/moderations": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get moderations usage details for the organization.", "operationId": "usage-moderations", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1m", "1h", "1d" ], "default": "1d" } }, { "name": "project_ids", "in": "query", "description": "Return only usage for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "user_ids", "in": "query", "description": "Return only usage for these users.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "api_key_ids", "in": "query", "description": "Return only usage for these API keys.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "models", "in": "query", "description": "Return only usage for these models.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "group_by", "in": "query", "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "api_key_id", "model" ] } } }, { "name": "limit", "in": "query", "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Moderations", "group": "usage-moderations", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/usage/moderations?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.moderations.result\",\n \"input_tokens\": 16,\n \"num_model_requests\": 2,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/usage/vector_stores": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get vector stores usage details for the organization.", "operationId": "usage-vector-stores", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1m", "1h", "1d" ], "default": "1d" } }, { "name": "project_ids", "in": "query", "description": "Return only usage for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "group_by", "in": "query", "description": "Group the usage data by the specified fields. Support fields include `project_id`.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id" ] } } }, { "name": "limit", "in": "query", "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Vector stores", "group": "usage-vector-stores", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/usage/vector_stores?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.vector_stores.result\",\n \"usage_bytes\": 1024,\n \"project_id\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/usage/web_search_calls": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Get web search calls usage details for the organization.", "operationId": "usage-web-search-calls", "tags": [ "Usage" ], "parameters": [ { "name": "start_time", "in": "query", "description": "Start time (Unix seconds) of the query time range, inclusive.", "required": true, "schema": { "type": "integer" } }, { "name": "end_time", "in": "query", "description": "End time (Unix seconds) of the query time range, exclusive.", "required": false, "schema": { "type": "integer" } }, { "name": "bucket_width", "in": "query", "description": "Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`.", "required": false, "schema": { "type": "string", "enum": [ "1m", "1h", "1d" ], "default": "1d" } }, { "name": "project_ids", "in": "query", "description": "Return only usage for these projects.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "user_ids", "in": "query", "description": "Return only usage for these users.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "api_key_ids", "in": "query", "description": "Return only usage for these API keys.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "models", "in": "query", "description": "Return only usage for these models.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "context_levels", "in": "query", "description": "Return only web search usage for these context levels.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "low", "medium", "high" ] } } }, { "name": "group_by", "in": "query", "description": "Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `context_level` or any combination of them.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "api_key_id", "model", "context_level" ] } } }, { "name": "limit", "in": "query", "description": "Specifies the number of buckets to return.\n- `bucket_width=1d`: default: 7, max: 31\n- `bucket_width=1h`: default: 24, max: 168\n- `bucket_width=1m`: default: 60, max: 1440\n", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage data retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Web search calls", "group": "usage-web-search-calls", "examples": { "request": { "curl": "curl \"https://api.openai.com/v1/organization/usage/web_search_calls?start_time=1730419200&limit=1\" \\\n-H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n-H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"page\",\n \"data\": [\n {\n \"object\": \"bucket\",\n \"start_time\": 1730419200,\n \"end_time\": 1730505600,\n \"results\": [\n {\n \"object\": \"organization.usage.web_searches.result\",\n \"num_model_requests\": 2,\n \"num_requests\": 2,\n \"project_id\": null,\n \"user_id\": null,\n \"api_key_id\": null,\n \"model\": null,\n \"context_level\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/users": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists all of the users in the organization.", "operationId": "list-users", "tags": [ "Users" ], "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.\n", "required": false, "schema": { "type": "integer", "default": 20 } }, { "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.\n", "required": false, "schema": { "type": "string" } }, { "name": "emails", "in": "query", "description": "Filter by the email address of users.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Users listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserListResponse" } } } } }, "x-oaiMeta": { "name": "List users", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/users?after=user_abc&limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"organization.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n }\n ],\n \"first_id\": \"user-abc\",\n \"last_id\": \"user-xyz\",\n \"has_more\": false\n}\n" } } } }, "/organization/users/{user_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves a user by their identifier.", "operationId": "retrieve-user", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } } }, "x-oaiMeta": { "name": "Retrieve user", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Modifies a user's role in the organization.", "operationId": "modify-user", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The new user role to modify. This must be one of `owner` or `member`.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRoleUpdateRequest" } } } }, "responses": { "200": { "description": "User role updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } } }, "x-oaiMeta": { "name": "Modify user", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role\": \"owner\"\n }'\n" }, "response": "{\n \"object\": \"organization.user\",\n \"id\": \"user_abc\",\n \"name\": \"First Last\",\n \"email\": \"user@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711471533\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deletes a user from the organization.", "operationId": "delete-user", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDeleteResponse" } } } } }, "x-oaiMeta": { "name": "Delete user", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/users/user_abc \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"organization.user.deleted\",\n \"id\": \"user_abc\",\n \"deleted\": true\n}\n" } } } }, "/organization/users/{user_id}/roles": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists the organization roles assigned to a user within the organization.", "operationId": "list-user-role-assignments", "tags": [ "User organization role assignments" ], "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "A limit on the number of organization role assignments to return.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000 } }, { "name": "after", "in": "query", "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing organization roles.", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order for the returned organization roles.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "User organization role assignments listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List user organization role assignments", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/users/user_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {}\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Assigns an organization role to a user within the organization.", "operationId": "assign-user-role", "tags": [ "User organization role assignments" ], "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user that should receive the organization role.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Identifies the organization role to assign to the user.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAssignOrganizationGroupRoleBody" } } } }, "responses": { "200": { "description": "Organization role assigned to the user successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRoleAssignment" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Assign organization role to user", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/organization/users/user_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_id\": \"role_01J1F8ROLE01\"\n }'\n" }, "response": "{\n \"object\": \"user.role\",\n \"user\": {\n \"object\": \"organization.user\",\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711470000\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"description\": \"Allows managing organization groups\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false\n }\n}\n" } } } }, "/organization/users/{user_id}/roles/{role_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves an organization role assigned to a user.", "operationId": "retrieve-user-role", "tags": [ "User organization role assignments" ], "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the organization role to retrieve for the user.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization role retrieved for the user successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignedRoleDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve user organization role", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"role_01J1F8ROLE01\",\n \"name\": \"API Group Manager\",\n \"permissions\": [\n \"api.groups.read\",\n \"api.groups.write\"\n ],\n \"resource_type\": \"api.organization\",\n \"predefined_role\": false,\n \"description\": \"Allows managing organization groups\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": null,\n \"metadata\": {},\n \"assignment_sources\": null\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Unassigns an organization role from a user within the organization.", "operationId": "unassign-user-role", "tags": [ "User organization role assignments" ], "parameters": [ { "name": "user_id", "in": "path", "description": "The ID of the user to modify.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the organization role to remove from the user.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization role unassigned from the user successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedRoleAssignmentResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Unassign organization role from user", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/organization/users/user_abc123/roles/role_01J1F8ROLE01 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"user.role.deleted\",\n \"deleted\": true\n}\n" } } } }, "/projects/{project_id}/groups/{group_id}/roles": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists the project roles assigned to a group within a project.", "operationId": "list-project-group-role-assignments", "tags": [ "Project group role assignments" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "path", "description": "The ID of the group to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "A limit on the number of project role assignments to return.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000 } }, { "name": "after", "in": "query", "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing project roles.", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order for the returned project roles.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Project group role assignments listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List project group role assignments", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false,\n \"description\": \"Allows managing API keys for the project\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {}\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Assigns a project role to a group within a project.", "operationId": "assign-project-group-role", "tags": [ "Project group role assignments" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "path", "description": "The ID of the group that should receive the project role.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Identifies the project role to assign to the group.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAssignOrganizationGroupRoleBody" } } } }, "responses": { "200": { "description": "Project role assigned to the group successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupRoleAssignment" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Assign project role to group", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_id\": \"role_01J1F8PROJ\"\n }'\n" }, "response": "{\n \"object\": \"group.role\",\n \"group\": {\n \"object\": \"group\",\n \"id\": \"group_01J1F8ABCDXYZ\",\n \"name\": \"Support Team\",\n \"created_at\": 1711471533,\n \"scim_managed\": false\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n }\n}\n" } } } }, "/projects/{project_id}/groups/{group_id}/roles/{role_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves a project role assigned to a group.", "operationId": "retrieve-project-group-role", "tags": [ "Project group role assignments" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "path", "description": "The ID of the group to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the project role to retrieve for the group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project role retrieved for the group successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignedRoleDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve project group role", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false,\n \"description\": \"Allows managing API keys for the project\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": null,\n \"metadata\": {},\n \"assignment_sources\": null\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Unassigns a project role from a group within a project.", "operationId": "unassign-project-group-role", "tags": [ "Project group role assignments" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to modify.", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "path", "description": "The ID of the group whose project role assignment should be removed.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the project role to remove from the group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project role unassigned from the group successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedRoleAssignmentResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Unassign project role from group", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/groups/group_01J1F8ABCDXYZ/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"group.role.deleted\",\n \"deleted\": true\n}\n" } } } }, "/projects/{project_id}/roles": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists the roles configured for a project.", "operationId": "list-project-roles", "tags": [ "Roles" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "A limit on the number of roles to return. Defaults to 1000.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 1000 } }, { "name": "after", "in": "query", "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing roles.", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order for the returned roles.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "Project roles listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRoleListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List project roles", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/projects/proj_abc123/roles?limit=20 \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Creates a custom role for a project.", "operationId": "create-project-role", "tags": [ "Roles" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Parameters for the project role you want to create.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCreateOrganizationRoleBody" } } } }, "responses": { "200": { "description": "Project role created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Create project role", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"description\": \"Allows managing API keys for the project\"\n }'\n" }, "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n}\n" } } } }, "/projects/{project_id}/roles/{role_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves a project role.", "operationId": "retrieve-project-role", "tags": [ "Roles" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the role to retrieve.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project role retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve project role", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Updates an existing project role.", "operationId": "update-project-role", "tags": [ "Roles" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the role to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Fields to update on the project role.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicUpdateOrganizationRoleBody" } } } }, "responses": { "200": { "description": "Project role updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Role" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Update project role", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"description\": \"Allows managing API keys for the project\"\n }'\n" }, "response": "{\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Deletes a custom role from a project.", "operationId": "delete-project-role", "tags": [ "Roles" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the role to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project role deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDeletedResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Delete project role", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"role.deleted\",\n \"id\": \"role_01J1F8PROJ\",\n \"deleted\": true\n}\n" } } } }, "/projects/{project_id}/users/{user_id}/roles": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Lists the project roles assigned to a user within a project.", "operationId": "list-project-user-role-assignments", "tags": [ "Project user role assignments" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "The ID of the user to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "A limit on the number of project role assignments to return.", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000 } }, { "name": "after", "in": "query", "description": "Cursor for pagination. Provide the value from the previous response's `next` field to continue listing project roles.", "required": false, "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Sort order for the returned project roles.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Project user role assignments listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleListResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "List project user role assignments", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false,\n \"description\": \"Allows managing API keys for the project\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": {\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\"\n },\n \"metadata\": {}\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Assigns a project role to a user within a project.", "operationId": "assign-project-user-role", "tags": [ "Project user role assignments" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to update.", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "The ID of the user that should receive the project role.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Identifies the project role to assign to the user.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAssignOrganizationGroupRoleBody" } } } }, "responses": { "200": { "description": "Project role assigned to the user successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRoleAssignment" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Assign project role to user", "group": "administration", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"role_id\": \"role_01J1F8PROJ\"\n }'\n" }, "response": "{\n \"object\": \"user.role\",\n \"user\": {\n \"object\": \"organization.user\",\n \"id\": \"user_abc123\",\n \"name\": \"Ada Lovelace\",\n \"email\": \"ada@example.com\",\n \"role\": \"owner\",\n \"added_at\": 1711470000\n },\n \"role\": {\n \"object\": \"role\",\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"description\": \"Allows managing API keys for the project\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false\n }\n}\n" } } } }, "/projects/{project_id}/users/{user_id}/roles/{role_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieves a project role assigned to a user.", "operationId": "retrieve-project-user-role", "tags": [ "Project user role assignments" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "The ID of the user to inspect.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the project role to retrieve for the user.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project role retrieved for the user successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignedRoleDetails" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Retrieve project user role", "group": "administration", "examples": { "request": { "curl": "curl https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"id\": \"role_01J1F8PROJ\",\n \"name\": \"API Project Key Manager\",\n \"permissions\": [\n \"api.organization.projects.api_keys.read\",\n \"api.organization.projects.api_keys.write\"\n ],\n \"resource_type\": \"api.project\",\n \"predefined_role\": false,\n \"description\": \"Allows managing API keys for the project\",\n \"created_at\": 1711471533,\n \"updated_at\": 1711472599,\n \"created_by\": \"user_abc123\",\n \"created_by_user_obj\": null,\n \"metadata\": {},\n \"assignment_sources\": null\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Unassigns a project role from a user within a project.", "operationId": "unassign-project-user-role", "tags": [ "Project user role assignments" ], "parameters": [ { "name": "project_id", "in": "path", "description": "The ID of the project to modify.", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "The ID of the user whose project role assignment should be removed.", "required": true, "schema": { "type": "string" } }, { "name": "role_id", "in": "path", "description": "The ID of the project role to remove from the user.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project role unassigned from the user successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedRoleAssignmentResource" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "name": "Unassign project role from user", "group": "administration", "examples": { "request": { "curl": "curl -X DELETE https://api.openai.com/v1/projects/proj_abc123/users/user_abc123/roles/role_01J1F8PROJ \\\n -H \"Authorization: Bearer $OPENAI_ADMIN_KEY\" \\\n -H \"Content-Type: application/json\"\n" }, "response": "{\n \"object\": \"user.role.deleted\",\n \"deleted\": true\n}\n" } } } }, "/realtime/calls": { "post": { "summary": "Create a new Realtime API call over WebRTC and receive the SDP answer needed\nto complete the peer connection.", "operationId": "create-realtime-call", "tags": [ "Realtime" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RealtimeCallCreateRequest" }, "encoding": { "sdp": { "contentType": "application/sdp" }, "session": { "contentType": "application/json" } } }, "application/sdp": { "schema": { "type": "string", "description": "WebRTC SDP offer. Use this variant when you have previously created an\nephemeral **session token** and are authenticating the request with it.\nRealtime session parameters will be retrieved from the session token." } } } }, "responses": { "201": { "description": "Realtime call created successfully.", "headers": { "Location": { "description": "Relative URL containing the call ID for subsequent control requests.", "schema": { "type": "string" } } }, "content": { "application/sdp": { "schema": { "type": "string", "description": "SDP answer produced by OpenAI for the peer connection." } } } } }, "x-oaiMeta": { "name": "Create call", "group": "realtime", "returns": "Returns `201 Created` with the SDP answer in the response body. The\n`Location` response header includes the call ID for follow-up requests,\ne.g., establishing a monitoring WebSocket or hanging up the call.", "examples": { "request": { "curl": "curl -X POST https://api.openai.com/v1/realtime/calls \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F \"sdp=