{ "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": "Responses", "description": "Create and manage model responses." }, { "name": "Audit Logs", "description": "List user actions and configuration changes within this organization." } ], "paths": { "/assistants": { "get": { "operationId": "listAssistants", "tags": [ "Assistants" ], "summary": "List assistants", "description": "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": { "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-4.1\",\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-4.1\",\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-4.1\",\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 assistant", "description": "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": { "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-4.1\"\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nmy_assistant = client.beta.assistants.create(\n instructions=\"You are a personal math tutor. When asked a question, write and run Python code to answer the question.\",\n name=\"Math Tutor\",\n tools=[{\"type\": \"code_interpreter\"}],\n model=\"gpt-4.1\",\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-4.1\",\n });\n\n console.log(myAssistant);\n}\n\nmain();" }, "response": "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1698984975,\n \"name\": \"Math Tutor\",\n \"description\": null,\n \"model\": \"gpt-4.1\",\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-4.1\"\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-4.1\"\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-4.1\"\n });\n\n console.log(myAssistant);\n}\n\nmain();" }, "response": "{\n \"id\": \"asst_abc123\",\n \"object\": \"assistant\",\n \"created_at\": 1699009403,\n \"name\": \"HR Helper\",\n \"description\": null,\n \"model\": \"gpt-4.1\",\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": "Retrieve assistant", "description": "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": { "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-4.1\",\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": "Modify assistant", "description": "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": { "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-4.1\"\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-4.1\"\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-4.1\"\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-4.1\",\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 assistant", "description": "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": { "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": "Create speech", "description": "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" } }, "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/opus": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/CreateSpeechResponseStreamEvent" } } } }, "400": { "description": "Invalid speech request, input, output format, or voice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed because the API key is missing or revoked, or the client IP is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "403": { "description": "Access to a personal API organization is blocked by the organization policy.", "content": { "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "429": { "$ref": "#/components/responses/InferenceRateLimited" }, "500": { "description": "The voice or speech audio could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/InferenceServiceUnavailable" } }, "x-oaiMeta": { "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": "Create transcription", "description": "Transcribes audio into the input language.\n\nReturns a transcription object in `json`, `diarized_json`, or `verbose_json`\nformat, plain text in `text`, `srt`, or `vtt` format, or a stream of\ntranscript events. Supported formats depend on the model.\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateTranscriptionRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateTranscriptionResponseJson" }, { "$ref": "#/components/schemas/CreateTranscriptionResponseDiarizedJson" }, { "$ref": "#/components/schemas/CreateTranscriptionResponseVerboseJson" } ] } }, "text/plain": { "schema": { "type": "string" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/CreateTranscriptionResponseStreamEvent" } } } }, "400": { "description": "Invalid audio input or request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed because the API key is missing or revoked, or the client IP is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "403": { "description": "Access to a personal API organization is blocked by the organization policy.", "content": { "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "413": { "description": "The audio request exceeds the supported size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/InferenceRateLimited" }, "500": { "description": "The audio could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream audio service connection failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/InferenceServiceUnavailable" } }, "x-oaiMeta": { "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\": 0.5,\n \"text\": \"Hello.\",\n \"words\": [\n {\n \"word\": \"Hello\",\n \"start\": 0.0,\n \"end\": 0.5\n }\n ],\n \"usage\": {\n \"type\": \"duration\",\n \"seconds\": 1\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\": 3.32,\n \"text\": \"The beach was a popular spot on a hot summer day.\",\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 \"usage\": {\n \"type\": \"duration\",\n \"seconds\": 4\n }\n}\n" } ] } } }, "/audio/translations": { "post": { "operationId": "createTranslation", "tags": [ "Audio" ], "summary": "Create translation", "description": "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" } ] } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid audio input or request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed because the API key is missing or revoked, or the client IP is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "403": { "description": "Access to a personal API organization is blocked by the organization policy.", "content": { "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "413": { "description": "The audio request exceeds the supported size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/InferenceRateLimited" }, "500": { "description": "The audio could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream audio service connection failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/InferenceServiceUnavailable" } }, "x-oaiMeta": { "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": "Create voice consent", "description": "Upload a voice consent recording.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateVoiceConsentRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceConsentResource" } } } }, "400": { "description": "Invalid consent recording or consent phrase.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List voice consents", "description": "Returns a list of voice consent recordings.", "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" } } } }, "400": { "description": "Invalid pagination parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or the pagination cursor was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve voice consent", "description": "Retrieves a voice consent recording.", "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" } } } }, "400": { "description": "Invalid consent recording ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or the consent recording was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Update voice consent", "description": "Updates a voice consent recording (metadata only).", "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" } } } }, "400": { "description": "Invalid consent recording ID or update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or the consent recording was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Delete voice consent", "description": "Deletes a voice consent recording.", "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" } } } }, "400": { "description": "Invalid consent recording ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or the consent recording was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Create voice", "description": "Creates a voice from a text prompt or from a consent recording and an audio sample.\n\nFor prompt-based creation, send `type: \"prompt\"` with a `name` and `prompt` as JSON or multipart form data. For creation from an audio sample, send `type: \"audio_sample\"` with a `name`, `audio_sample`, and `consent` recording ID as multipart form data. The type defaults to `audio_sample` when omitted.\n\nReturns the saved voice's metadata. Voices created from text prompts are supported only in Live, not in Realtime or the speech endpoint. The response does not include preview audio.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVoicePromptRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateVoiceRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceResource" } } } }, "400": { "description": "Invalid voice request, prompt, script hint, model, consent recording, or audio sample.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or the consent recording was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The audio sample could not be processed or the voice could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "group": "audio", "examples": { "request": { "curl": "curl https://api.openai.com/v1/audio/voices \\\n -X POST \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"type\": \"prompt\",\n \"name\": \"Warm narrator\",\n \"prompt\": \"A warm, calm narrator with a clear, measured delivery.\",\n \"model\": \"auto\"\n }'\n" } } } } }, "/audio/voices/{voice_id}": { "delete": { "operationId": "deleteVoice", "tags": [ "Audio" ], "summary": "Delete voice", "description": "Deletes a voice created from a text prompt or an audio sample.\n\nRequires voice write permission and access to the voice's project. Access to voices created from recordings is limited to eligible customers. See the [custom voices guide](https://developers.openai.com/api/docs/guides/custom-voices).\n\nDeleting a voice does not delete its consent recording. Deleting an already deleted voice returns a 404 error.\n", "parameters": [ { "in": "path", "name": "voice_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the voice to delete." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceDeletedResource" } } } }, "400": { "description": "Invalid voice ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or the voice was not found in the requested project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "group": "audio", "examples": { "request": { "curl": "curl https://api.openai.com/v1/audio/voices/voice_1234 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n" }, "response": "{\n \"id\": \"voice_1234\",\n \"object\": \"audio.voice.deleted\",\n \"deleted\": true\n}\n" } } } }, "/batches": { "post": { "summary": "Create batch", "description": "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" } } } }, "400": { "description": "The request is invalid or the account cannot create a batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request was rejected because a rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An internal error prevented the batch from being created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The batch could not be created because the service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 batches", "description": "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" } } } }, "400": { "description": "Invalid pagination parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No batch was found with the specified pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request was rejected because a rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"first_id\": \"batch_abc123\",\n \"last_id\": \"batch_abc123\",\n \"has_more\": false\n}\n" } } } }, "/batches/{batch_id}": { "get": { "operationId": "retrieveBatch", "tags": [ "Batch" ], "summary": "Retrieve batch", "description": "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" } } } }, "400": { "description": "Invalid batch ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No batch was found with the specified ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request was rejected because a rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Cancel batch", "description": "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" } } } }, "400": { "description": "Invalid batch ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No batch was found with the specified ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The batch's current status does not allow cancellation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request was rejected because a rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 Chat Completions", "description": "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" } } } }, "400": { "description": "Invalid pagination or filter parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "An internal error prevented the request from being completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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-6-astra\",\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": "Create chat completion", "description": "**Starting a new project?** We recommend trying [Responses](https://developers.openai.com/api/reference/resources/responses)\nto take advantage of the latest OpenAI platform features. Compare\n[Chat Completions with Responses](https://developers.openai.com/api/docs/guides/migrate-to-responses?api-mode=responses).\n\n---\n\nCreates a model response for the given chat conversation. Learn more in the\n[text generation](https://developers.openai.com/api/docs/guides/text), [vision](https://developers.openai.com/api/docs/guides/images-vision),\nand [audio](https://developers.openai.com/api/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](https://developers.openai.com/api/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": "Returns a Chat Completion object for a non-streaming request.\n\nIf `stream` is `true`, returns server-sent events (`text/event-stream`).\nSuccessful chunk frames contain a JSON Chat Completion chunk matching\n`CreateChatCompletionStreamResponse`. On normal completion, the final\nframe is:\n\n```text\ndata: [DONE]\n\n```\n\nThe final frame ends with a blank line. `[DONE]` is literal text, not a\nJSON chunk, and this frame has no `event: done` field.\n\nIf a failure occurs after streaming has started, a data frame may\ncontain a JSON object with an `error` field instead of a completion\nchunk. The streaming schema describes successful JSON chunks, not\nerror frames or the completion marker. An interrupted stream may end\nwithout the marker.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/CreateChatCompletionStreamResponse" } } } }, "400": { "description": "Invalid chat completion request or incompatible request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed because the API key is missing or revoked, or the client IP is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "403": { "description": "Access to a personal API organization is blocked by the organization policy.", "content": { "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "404": { "description": "The requested model or a referenced resource was not found or is unavailable to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/InferenceRateLimited" }, "500": { "description": "The chat completion could not be processed due to an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/InferenceServiceUnavailable" } }, "x-oaiMeta": { "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\": \"gpt-6-astra\",\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=\"gpt-6-astra\",\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: \"gpt-6-astra\",\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-6-astra\",\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-6-astra\",\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-6-astra\",\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-6-astra\",\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-6-astra\",\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-6-astra\",\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-6-astra\",\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\": \"gpt-6-astra\",\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=\"gpt-6-astra\",\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: \"gpt-6-astra\",\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-6-astra\",\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": "data: {\"id\":\"chatcmpl-123\",\"object\":\"chat.completion.chunk\",\"created\":1694268190,\"model\":\"gpt-6-astra\", \"system_fingerprint\": \"fp_44709d6fcb\", \"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"\"},\"logprobs\":null,\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-123\",\"object\":\"chat.completion.chunk\",\"created\":1694268190,\"model\":\"gpt-6-astra\", \"system_fingerprint\": \"fp_44709d6fcb\", \"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\"},\"logprobs\":null,\"finish_reason\":null}]}\n\n: Intermediate chat completion chunks omitted.\n\ndata: {\"id\":\"chatcmpl-123\",\"object\":\"chat.completion.chunk\",\"created\":1694268190,\"model\":\"gpt-6-astra\", \"system_fingerprint\": \"fp_44709d6fcb\", \"choices\":[{\"index\":0,\"delta\":{},\"logprobs\":null,\"finish_reason\":\"stop\"}]}\n\ndata: [DONE]\n\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-6-astra\",\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=\"gpt-6-astra\",\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-6-astra\",\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-6-astra\",\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-6-astra\",\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\": \"gpt-6-sol\",\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello!\"\n }\n ],\n \"reasoning_effort\": \"none\",\n \"logprobs\": true,\n \"top_logprobs\": 2\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\ncompletion = client.chat.completions.create(\n model=\"gpt-6-sol\",\n messages=[\n {\"role\": \"user\", \"content\": \"Hello!\"}\n ],\n reasoning_effort=\"none\",\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: \"gpt-6-sol\",\n reasoning_effort: \"none\",\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-6-sol\",\n apiKey: Environment.GetEnvironmentVariable(\"OPENAI_API_KEY\")\n);\n\nList messages =\n[\n new UserChatMessage(\"Hello!\")\n];\n\nChatCompletionOptions options = new()\n{\n ReasoningEffortLevel = ChatReasoningEffortLevel.None,\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-6-sol\",\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 \"refusal\": null\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}\n" } ] } } }, "/chat/completions/{completion_id}": { "get": { "operationId": "getChatCompletion", "tags": [ "Chat" ], "summary": "Get chat completion", "description": "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" } } } }, "404": { "description": "No stored chat completion was found with the specified ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "An internal error prevented the request from being completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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-6-astra\",\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": "Update chat completion", "description": "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" } } } }, "400": { "description": "Invalid metadata update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No stored chat completion was found with the specified ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "An internal error prevented the request from being completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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-6-astra\",\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 chat completion", "description": "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" } } } }, "404": { "description": "No stored chat completion was found with the specified ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "An internal error prevented the request from being completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 chat messages", "description": "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" } } } }, "400": { "description": "Invalid message pagination parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No stored chat completion was found with the specified ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "An internal error prevented the request from being completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Create completion", "description": "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" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/CreateCompletionResponse" } } } }, "400": { "description": "Invalid completion request or incompatible request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed because the API key is missing or revoked, or the client IP is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "403": { "description": "Access to a personal API organization is blocked by the organization policy.", "content": { "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "404": { "description": "The requested model was not found, is unavailable, or does not support this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/InferenceRateLimited" }, "500": { "description": "The completion could not be processed due to an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/InferenceServiceUnavailable" } }, "x-oaiMeta": { "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\": \"gpt-3.5-turbo-instruct\",\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=\"gpt-3.5-turbo-instruct\",\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: \"gpt-3.5-turbo-instruct\",\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\": \"gpt-3.5-turbo-instruct\",\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\": \"gpt-3.5-turbo-instruct\",\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=\"gpt-3.5-turbo-instruct\",\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: \"gpt-3.5-turbo-instruct\",\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": "List 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" } } } }, "404": { "description": "The container specified by `after` was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Create 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" } } } }, "400": { "description": "The container configuration or supplied skill is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve 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" } } } }, "404": { "description": "The container was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 a container", "description": "Delete Container", "parameters": [ { "name": "container_id", "in": "path", "description": "The ID of the container to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "container.deleted" ] }, "deleted": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "object", "deleted", "id" ] } } } }, "404": { "description": "The container was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 container file", "description": "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", "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" } } } }, "400": { "description": "The file input is invalid, or the container file limit would be exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The container was not found or has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "List 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" } } } }, "404": { "description": "The container was not found or has expired, or the file specified by `after` was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve 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" } } } }, "404": { "description": "The container was not found or has expired, or the file was not found in the container.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 a container file", "description": "Delete 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", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "container.file.deleted" ] }, "deleted": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "object", "deleted", "id" ] } } } }, "404": { "description": "The container was not found or has expired, or the file was not found in the container.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve 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", "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "The container was not found or has expired, or the file was not found in the container.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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", "description": "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](https://developers.openai.com/api/reference/resources/conversations/subresources/items/methods/list#%28resource%29%20conversations.items%20%3E%20%28method%29%20list%20%3E%20%28params%29%20default%20%3E%20%28param%29%20include%20%3E%20%28schema%29) 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" } } } }, "400": { "description": "The items are invalid, are already in the conversation, or the conversation is locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The conversation was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The conversation update could not be finalized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 items", "description": "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" } } } }, "400": { "description": "The stored encrypted item content could not be validated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The conversation or the item specified by `after` was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve an item", "description": "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](https://developers.openai.com/api/reference/resources/conversations/subresources/items/methods/list#%28resource%29%20conversations.items%20%3E%20%28method%29%20list%20%3E%20%28params%29%20default%20%3E%20%28param%29%20include%20%3E%20%28schema%29) for more information.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationItem" } } } }, "404": { "description": "The conversation or the item in that conversation was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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", "description": "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" } } } }, "400": { "description": "The item cannot be removed while the conversation is locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The conversation or the item in that conversation was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The conversation update could not be finalized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Create embeddings", "description": "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" } } } }, "400": { "description": "Invalid embedding input or request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed because the API key is missing or revoked, or the client IP is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "403": { "description": "Access to a personal API organization is blocked by the organization policy.", "content": { "text/plain": { "schema": { "type": "string", "description": "JSON-encoded error text containing an error object and the HTTP status." } } } }, "429": { "$ref": "#/components/responses/InferenceRateLimited" }, "500": { "description": "The embedding request could not be processed due to an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/InferenceServiceUnavailable" } }, "x-oaiMeta": { "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\": \"Hello world\",\n \"model\": \"text-embedding-3-small\",\n \"encoding_format\": \"float\",\n \"dimensions\": 3\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.embeddings.create(\n model=\"text-embedding-3-small\",\n input=\"Hello world\",\n encoding_format=\"float\",\n dimensions=3\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-3-small\",\n input: \"Hello world\",\n encoding_format: \"float\",\n dimensions: 3,\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\nEmbeddingGenerationOptions options = new() { Dimensions = 3 };\nOpenAIEmbedding embedding = client.GenerateEmbedding(input: \"Hello world\", options: options);\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.26726124,\n 0.53452248,\n 0.80178373\n ],\n \"index\": 0\n }\n ],\n \"model\": \"text-embedding-3-small\",\n \"usage\": {\n \"prompt_tokens\": 2,\n \"total_tokens\": 2\n }\n}\n" } } } }, "/evals": { "get": { "operationId": "listEvals", "tags": [ "Evals" ], "summary": "List evals", "description": "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": { "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 eval", "description": "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](https://developers.openai.com/api/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" } } } }, "400": { "description": "The evaluation input or grader configuration is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 },\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 eval", "description": "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" } } } }, "404": { "description": "The evaluation was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 an eval", "description": "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" } } } }, "400": { "description": "The evaluation name or metadata is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The evaluation was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 eval", "description": "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" ] } } } }, "400": { "description": "The evaluation cannot be deleted while it has unfinished runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Evaluation not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 eval runs", "description": "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" } } } }, "400": { "description": "The run list parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The evaluation or the run specified by `after` was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 },\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": "Create eval run", "description": "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/ErrorResponse" } } } }, "404": { "description": "The evaluation or a referenced resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The evaluation run could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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-6-astra\",\"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\":{\"max_completions_tokens\":2048},\"model\":\"gpt-6-astra\",\"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-6-astra\",\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 \"max_completions_tokens\": 2048\n },\n \"model\": \"gpt-6-astra\",\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-6-astra\",\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 max_completions_tokens: 2048\n },\n model: \"gpt-6-astra\",\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-6-astra\",\n \"name\": \"gpt-6-astra\",\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-6-astra\",\n \"sampling_params\": {\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 eval run", "description": "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" } } } }, "400": { "description": "The evaluation run does not belong to the specified evaluation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The evaluation or evaluation run was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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-6-astra\",\n \"name\": \"gpt-6-astra\",\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-6-astra\",\n \"sampling_params\": {\n \"max_completions_tokens\": 2048\n }\n },\n \"error\": null,\n \"metadata\": {}\n}\n" } } }, "delete": { "operationId": "deleteEvalRun", "tags": [ "Evals" ], "summary": "Delete eval run", "description": "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" } } } } } }, "400": { "description": "The evaluation run cannot be deleted until it is finished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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}/cancel": { "post": { "operationId": "cancelEvalRun", "tags": [ "Evals" ], "summary": "Cancel eval run", "description": "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": { "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 \"evalrun_67abd54d60ec8190832b46859da808f7\",\n eval_id=\"eval_67abd54d9b0081909a86353f6fb9317a\"\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-6-astra\",\n \"name\": \"gpt-6-astra\",\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-6-astra\",\n \"sampling_params\": {\n \"max_completions_tokens\": 2048\n }\n },\n \"error\": null,\n \"metadata\": {}\n}\n" } } } }, "/evals/{eval_id}/runs/{run_id}/output_items": { "get": { "operationId": "getEvalRunOutputItems", "tags": [ "Evals" ], "summary": "Get eval run output items", "description": "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" } } } }, "400": { "description": "The output item list parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The evaluation or evaluation run was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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-6-astra\",\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 output item of an eval run", "description": "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" } } } }, "400": { "description": "The output item was not found, its identifier is invalid, or the run does not belong to the evaluation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The evaluation or evaluation run was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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-6-astra\",\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": "List files", "description": "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" } } } }, "400": { "description": "The file listing parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The file specified by the after cursor was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many file requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"status\": \"processed\"\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 \"status\": \"processed\"\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 file", "description": "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](https://developers.openai.com/api/docs/guides/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](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#formatting-your-data) or\n [completions](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#formatting-your-data) 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](https://developers.openai.com/api/docs/guides/batch#1-prepare-your-batch-file).\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`](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create)\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" } } } }, "400": { "description": "The file upload request is invalid or exceeds a file size or storage quota limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many file requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The file could not be uploaded because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "group": "files", "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\": 1680202602,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n \"status\": \"processed\"\n}\n" } } } }, "/files/{file_id}": { "delete": { "operationId": "deleteFile", "tags": [ "Files" ], "summary": "Delete file", "description": "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" } } } }, "404": { "description": "The file was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many file requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve file", "description": "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" } } } }, "404": { "description": "The file was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many file requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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\": 1680202602,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n \"status\": \"processed\"\n}\n" } } } }, "/files/{file_id}/content": { "get": { "operationId": "downloadFile", "tags": [ "Files" ], "summary": "Retrieve file content", "description": "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/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The file cannot be downloaded for its purpose or the account does not have permission to download it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The file was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many file requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The file could not be downloaded because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 grader", "description": "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" } } } }, "400": { "description": "The grader definition or request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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-5-mini\"\n },\n \"sub_rewards\": {},\n \"model_grader_token_usage_per_model\": {\n \"gpt-5-mini\": {\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 grader", "description": "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" } } } }, "400": { "description": "The grader definition or request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List checkpoint permissions", "description": "**NOTE:** This endpoint requires an [admin API key](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/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" } } } }, "400": { "description": "The query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Create checkpoint permissions", "description": "**NOTE:** Calling this endpoint requires an [admin API key](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/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" } } } }, "400": { "description": "The request is invalid or checkpoint permissions cannot be changed for the requested projects or job state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The checkpoint or its fine-tuning job was not found, or the checkpoint cannot be shared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Delete checkpoint permission", "description": "**NOTE:** This endpoint requires an [admin API key](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/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" } } } }, "400": { "description": "The checkpoint permission cannot be removed for the requested project or job state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The checkpoint, permission, associated project, or fine-tuning job was not found, or the checkpoint cannot be shared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Create fine-tuning job", "description": "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](https://developers.openai.com/api/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" } } } }, "400": { "description": "The request is invalid or the organization does not meet the requirements to create a fine-tuning job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A request or fine-tuning job limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"error\": {},\n \"finished_at\": null,\n \"seed\": null,\n \"trained_tokens\": null,\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\"\n }\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 \"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 \"finished_at\": 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 \"trained_tokens\": null\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 \"error\": {},\n \"finished_at\": null,\n \"seed\": null,\n \"trained_tokens\": null,\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\"\n }\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\": null,\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 \"error\": {},\n \"finished_at\": null,\n \"seed\": null,\n \"trained_tokens\": null,\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\"\n }\n}\n" } ] } }, "get": { "operationId": "listPaginatedFineTuningJobs", "tags": [ "Fine-tuning" ], "summary": "List fine-tuning jobs", "description": "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", "null" ], "additionalProperties": { "type": "string" } }, "style": "deepObject", "explode": true, "description": "Optional metadata filter. To filter, use the syntax `metadata[k]=v`. Omitting the parameter or passing an empty object applies no metadata filter. An empty value, such as `metadata[k]=`, filters for that key with an empty string value.\nTo select jobs with null metadata, send the literal query string `metadata=null`. Nullable caller types do not specify how a client serializes null for a deep-object parameter. Use a raw query parameter if the client omits null. Do not combine the two query forms.\n" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPaginatedFineTuningJobsResponse" } } } }, "400": { "description": "The query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"error\": null,\n \"finished_at\": null,\n \"trained_tokens\": null,\n \"seed\": 42,\n \"hyperparameters\": {\n \"batch_size\": \"auto\",\n \"learning_rate_multiplier\": \"auto\",\n \"n_epochs\": \"auto\"\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\": {\n \"key\": \"value\"\n }\n }\n ],\n \"has_more\": false\n}\n" } } } }, "/fine_tuning/jobs/{fine_tuning_job_id}": { "get": { "operationId": "retrieveFineTuningJob", "tags": [ "Fine-tuning" ], "summary": "Retrieve fine-tuning job", "description": "Get info about a fine-tuning job.\n\n[Learn more about fine-tuning](https://developers.openai.com/api/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" } } } }, "404": { "description": "The fine-tuning job was not found or is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"error\": {}\n}\n" } } } }, "/fine_tuning/jobs/{fine_tuning_job_id}/cancel": { "post": { "operationId": "cancelFineTuningJob", "tags": [ "Fine-tuning" ], "summary": "Cancel fine-tuning", "description": "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" } } } }, "400": { "description": "The fine-tuning job cannot be cancelled in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The fine-tuning job was not found or is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"error\": {},\n \"finished_at\": null,\n \"seed\": null,\n \"trained_tokens\": null,\n \"hyperparameters\": null\n}\n" } } } }, "/fine_tuning/jobs/{fine_tuning_job_id}/checkpoints": { "get": { "operationId": "listFineTuningJobCheckpoints", "tags": [ "Fine-tuning" ], "summary": "List fine-tuning checkpoints", "description": "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" } } } }, "400": { "description": "The query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The fine-tuning job was not found or is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List fine-tuning events", "description": "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" } } } }, "400": { "description": "The query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The fine-tuning job was not found or is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 fine-tuning", "description": "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" } } } }, "400": { "description": "The fine-tuning job cannot be paused in its current state or does not support pausing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The fine-tuning job was not found or is not accessible, or this operation is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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\": \"o4-mini\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"pausing\",\n \"validation_file\": \"file-123\",\n \"training_file\": \"file-abc\",\n \"error\": {},\n \"finished_at\": null,\n \"seed\": null,\n \"trained_tokens\": null,\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" } } } }, "/fine_tuning/jobs/{fine_tuning_job_id}/resume": { "post": { "operationId": "resumeFineTuningJob", "tags": [ "Fine-tuning" ], "summary": "Resume fine-tuning", "description": "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" } } } }, "400": { "description": "The fine-tuning job cannot be resumed in its current state or does not support resuming.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The fine-tuning job was not found or is not accessible, or this operation is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A request or fine-tuning job limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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\": \"o4-mini\",\n \"created_at\": 1721764800,\n \"fine_tuned_model\": null,\n \"organization_id\": \"org-123\",\n \"result_files\": [],\n \"status\": \"queued\",\n \"validation_file\": \"file-123\",\n \"training_file\": \"file-abc\",\n \"error\": {},\n \"finished_at\": null,\n \"seed\": null,\n \"trained_tokens\": null,\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" } } } }, "/images/edits": { "post": { "operationId": "createImageEdit", "tags": [ "Images" ], "summary": "Create image edit", "description": "Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models.", "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" } } } }, "400": { "description": "Invalid image request, including invalid parameters or input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The project does not have access to the requested model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The requested DALL-E image endpoint is unavailable because it has been retired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/InferenceRateLimited" }, "500": { "description": "The image could not be generated or processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/InferenceServiceUnavailable" } }, "x-oaiMeta": { "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": "Create image", "description": "Creates an image given a prompt using a GPT Image model. [Learn more](https://developers.openai.com/api/docs/guides/images-vision).\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" } } } }, "400": { "description": "Invalid image request, including invalid parameters or input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The project does not have access to the requested model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The requested DALL-E image endpoint is unavailable because it has been retired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/InferenceRateLimited" }, "500": { "description": "The image could not be generated or processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/InferenceServiceUnavailable" } }, "x-oaiMeta": { "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-2.5-flare\",\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-2.5-flare\",\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-2.5-flare\",\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-2.5-flare\",\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-2.5-flare\",\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-2.5-flare\",\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": "Create image variation", "deprecated": true, "description": "This endpoint is retired and no longer available. Use the image edits endpoint with a GPT Image model and a prompt to create a variation of an image. The request and response schemas below describe the legacy contract.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateImageVariationRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImagesResponse" } } } }, "400": { "description": "Invalid image or request, or the request cannot be processed for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The project does not have access to the requested model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The image variations endpoint is no longer available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The image rate limit was exceeded.", "headers": { "X-RateLimit-Limit-Images": { "description": "The image limit for the rate-limit window.", "schema": { "type": "number" } }, "X-RateLimit-Remaining-Images": { "description": "The number of images remaining in the rate-limit window.", "schema": { "type": "number", "minimum": 0 } }, "X-RateLimit-Reset-Images": { "description": "The number of seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The image variation could not be generated or processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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" } } } }, "/live/sessions": { "post": { "operationId": "create-live", "summary": "Create session", "description": "Create a Live WebRTC session or place an outbound SIP call. Start with the\n[Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) for session configuration\nand [Telephony and SIP](https://developers.openai.com/api/docs/guides/voice-sip?api=live#place-an-outbound-call)\nfor trunk setup and call monitoring.\n\nSet transport.type to `webrtc` and supply an SDP offer, or set it to `sip`\nand supply an E.164 destination and trunk credentials. Outbound SIP calling\nmust be enabled for your organization.\nRinging is limited to 3 minutes and connected calls to 2 hours; these limits\nare not configurable in the request.\n\nReturns `201 Created` after session initialization. WebRTC responses include an\nSDP answer. SIP responses do not wait for the callee to answer. Attach a\nsideband connection using session.id to monitor SIP call progress.\n\nEach SIP request creates a new call. If a request times out or the connection\nfails, retry with caution: the original request may have succeeded, and a\nretry can place another call.", "tags": [ "Live" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveSessionCreateRequest" } } } }, "responses": { "201": { "description": "Returns 201 Created with a WebRTC answer or an initialized outbound SIP session. A SIP response does not mean the callee has answered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveSessionCreateResponse" }, "examples": { "webrtc": { "summary": "WebRTC session created (201 Created)", "value": { "session": { "id": "live_123" }, "transport": { "type": "webrtc", "sdp": "" } } }, "sip": { "summary": "Outbound SIP session initialized (201 Created)", "value": { "session": { "id": "live_123" }, "transport": { "type": "sip" } } } } } } }, "400": { "description": "Invalid Live session request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "The Live session request exceeds the supported size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The session could not start because a rate or quota limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An internal error occurred. The response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "502": { "description": "The SIP gateway could not initialize the outbound call.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "The session is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/plain": { "schema": { "type": "string" } } } }, "504": { "description": "SIP session initialization timed out. The error code is sip_setup_timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "group": "live", "returns": "For WebRTC, returns 201 Created with the session identifier in session.id and SDP answer in transport.sdp. For SIP, returns 201 Created after session initialization with session.id and transport.type set to sip, without SDP or trunk credentials. This does not wait for the callee to answer. Attach to /v1/live/sessions/{session_id}/attach to monitor call progress.", "examples": [ { "title": "Create a WebRTC session", "request": { "curl": "curl https://api.openai.com/v1/live/sessions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"session\":{\"model\":\"gpt-live-1\",\"instructions\":\"Be concise. Ask for clarification when needed.\"},\"transport\":{\"type\":\"webrtc\",\"sdp\":\"\"}}'" }, "response": "{\"session\":{\"id\":\"live_123\"},\"transport\":{\"type\":\"webrtc\",\"sdp\":\"\"}}" }, { "title": "Place an outbound SIP call", "request": { "curl": "# Export SIP_USERNAME and SIP_PASSWORD in your environment first.\njq -n '{\n \"session\": {\n \"model\": \"gpt-live-1\",\n \"instructions\": \"Help the user schedule an appointment.\",\n \"audio\": { \"output\": { \"voice\": \"marin\" } },\n \"delegation\": { \"type\": \"client\" }\n },\n \"transport\": {\n \"type\": \"sip\",\n \"destination\": \"+14155550123\",\n \"trunk\": {\n \"provider_url\": \"sips:sip.example.com:5061\",\n \"auth\": {\n \"type\": \"digest\",\n \"username\": env.SIP_USERNAME,\n \"password\": env.SIP_PASSWORD\n },\n \"caller_number\": \"+14155550100\"\n }\n }\n }' | curl https://api.openai.com/v1/live/sessions \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @-" }, "response": "{\"session\":{\"id\":\"live_123\"},\"transport\":{\"type\":\"sip\"}}" } ] } } }, "/live/sessions/{session_id}/accept": { "post": { "operationId": "accept-live-session", "summary": "Accept call", "description": "Accept an incoming SIP call. Supply session with type live, the model, and startup configuration. Before accepting calls, follow the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) to write frontend conversation instructions and a separate backend prompt. SIP media format is negotiated; omit audio.format.", "tags": [ "Live" ], "parameters": [ { "in": "path", "name": "session_id", "required": true, "description": "Opaque Live session identifier from the creation response or incoming-call webhook. Preserve the returned value unchanged, including its prefix.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveCallAcceptRequest" } } } }, "responses": { "200": { "description": "Session accept request accepted." }, "400": { "description": "Invalid request body or headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The session or call was not found or is unavailable for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The session or call can no longer accept this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The session could not start because a rate or quota limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An internal error occurred. The response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "The session is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "group": "live-sessions", "returns": "Returns 200 OK when the control request succeeds." } } }, "/live/sessions/{session_id}/fork": { "post": { "operationId": "fork-live-session", "summary": "Fork session", "description": "Fork a stored Live session onto a new WebRTC connection.", "tags": [ "Live" ], "parameters": [ { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the stored Live session to fork." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveForkRequest" } } } }, "responses": { "201": { "description": "Forked Live session created with a WebRTC answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveCreateResponse" } } } }, "400": { "description": "Invalid Live session request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Invalid session ID.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "413": { "description": "The Live session request exceeds the supported size limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The session could not start because a rate or quota limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An internal error occurred. The response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "503": { "description": "The session is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "group": "live", "returns": "The new session identifier in session.id and SDP answer in transport.sdp.", "examples": { "request": { "curl": "curl https://api.openai.com/v1/live/sessions/live_123/fork \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"session\":{},\"transport\":{\"type\":\"webrtc\",\"sdp\":\"\"}}'" } } } } }, "/live/sessions/{session_id}/hangup": { "post": { "operationId": "hangup-live-session", "summary": "Hang up session", "description": "End a SIP call identified by session_id.", "tags": [ "Live" ], "parameters": [ { "in": "path", "name": "session_id", "required": true, "description": "Opaque Live session identifier from the creation response or incoming-call webhook. Preserve the returned value unchanged, including its prefix.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session hangup request accepted." }, "404": { "description": "The session or call was not found or is unavailable for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "group": "live-sessions", "returns": "Returns 200 OK when the control request succeeds." } } }, "/live/sessions/{session_id}/refer": { "post": { "operationId": "refer-live-session", "summary": "Transfer call", "description": "Transfer a SIP call to another destination. Supply a nonblank target_uri for the SIP Refer-To header.", "tags": [ "Live" ], "parameters": [ { "in": "path", "name": "session_id", "required": true, "description": "Opaque Live session identifier from the creation response or incoming-call webhook. Preserve the returned value unchanged, including its prefix.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveCallReferRequest" } } } }, "responses": { "200": { "description": "Session refer request accepted." }, "400": { "description": "Invalid request body or headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The session or call was not found or is unavailable for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An internal error occurred. The response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-oaiMeta": { "group": "live-sessions", "returns": "Returns 200 OK when the control request succeeds." } } }, "/live/sessions/{session_id}/reject": { "post": { "operationId": "reject-live-session", "summary": "Reject call", "description": "Reject an incoming SIP call. Send a required SIP rejection status_code between 300 and 699.", "tags": [ "Live" ], "parameters": [ { "in": "path", "name": "session_id", "required": true, "description": "Opaque Live session identifier from the creation response or incoming-call webhook. Preserve the returned value unchanged, including its prefix.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveCallRejectRequest" } } } }, "responses": { "200": { "description": "Session reject request accepted." }, "400": { "description": "Invalid request body or headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The session or call was not found or is unavailable for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The session or call can no longer accept this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "An internal error occurred. The response body is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } } }, "x-oaiMeta": { "group": "live-sessions", "returns": "Returns 200 OK when the control request succeeds." } } }, "/models": { "get": { "operationId": "listModels", "tags": [ "Models" ], "summary": "List models", "description": "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" } } } }, "403": { "description": "The API credential does not have permission to list models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve model", "description": "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-6-astra" }, "description": "The ID of the model to use for this request" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "403": { "description": "The API credential does not have permission to retrieve models.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The model was not found or is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "group": "models", "examples": { "request": { "curl": "curl https://api.openai.com/v1/models/gpt-6-astra \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.models.retrieve(\"gpt-6-astra\")\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const model = await openai.models.retrieve(\"gpt-6-astra\");\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\": \"gpt-6-astra\",\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", "description": "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" } } } }, "403": { "description": "Insufficient permissions to delete the model. Model deletion requires the Owner role in the organization and a credential that permits deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The model was not found, is not accessible, or cannot be deleted through this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Create moderation", "description": "Classifies if text and/or image inputs are potentially harmful. Learn\nmore in the [moderation guide](https://developers.openai.com/api/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" } } } }, "400": { "description": "Invalid moderation input or unsupported request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access to the requested moderation model was denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/InferenceRateLimited" }, "500": { "description": "The moderation request could not be processed due to an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "$ref": "#/components/responses/InferenceServiceUnavailable" } }, "x-oaiMeta": { "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 \"model\": \"omni-moderation-latest\",\n \"input\": \"...text to classify goes here...\"\n }'\n", "python": "from openai import OpenAI\nclient = OpenAI()\n\nmoderation = client.moderations.create(\n model=\"omni-moderation-latest\",\n input=\"...text to classify goes here...\",\n)\nprint(moderation)\n", "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const moderation = await openai.moderations.create({\n model: \"omni-moderation-latest\",\n input: \"...text to classify goes here...\",\n });\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(\"...text to classify goes here...\");\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 all organization and project API keys.", "description": "List organization API keys", "operationId": "admin-api-keys-list", "parameters": [ { "in": "query", "name": "after", "required": false, "schema": { "type": [ "string", "null" ], "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" } } } }, "400": { "description": "The API key listing parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } } }, "x-oaiMeta": { "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 admin API key", "description": "Create an organization admin API key", "operationId": "admin-api-keys-create", "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" } } } }, "400": { "description": "The API key creation request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The created API key could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 admin API key", "description": "Retrieve a single organization API key", "operationId": "admin-api-keys-get", "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The API key was not found or is not available to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"expires_at\": null,\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 admin API key", "description": "Delete an organization admin API key", "operationId": "admin-api-keys-delete", "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" ] } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The API key was not found or is not available to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 audit logs", "description": "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](https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/audit_logs).", "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No audit log was found with the specified pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 organization certificates", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 certificate", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 for organization", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A certificate was not found in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The certificate update could not be completed because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 for organization", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A certificate was not found in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The certificate update could not be completed because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 certificate", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A certificate was not found in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 certificate", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A certificate was not found in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The certificate update could not be completed because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 certificate", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A certificate was not found in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Costs", "description": "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": "line_items", "in": "query", "description": "Return only costs for these exact line item names. Each value must match the complete `line_item` value, for example `gpt-6-astra, input_tokens`.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "group_by", "in": "query", "description": "Group the costs by the specified fields. Supported fields include `project_id`, `user_id`, `line_item`, `api_key_id`, and `api_source`. Support for combining `user_id` with `project_id` grouping or the `project_ids` filter depends on the organization and requested time range. Unsupported combinations return HTTP 400. When grouped by `api_source`, results use `agents_api` for attributed Agents API activity and `unlabeled` for all other activity. Without source grouping, `api_source` is null.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "line_item", "api_key_id", "api_source" ] } } }, { "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 \"quantity_unit\": null\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next_page\": null\n}\n" } } } }, "/organization/data_retention": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieve organization data retention", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The organization was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Update organization data retention", "description": "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" } } } }, "400": { "description": "The requested data retention setting or transition is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The organization was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List groups", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested group, user, or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 \"group_type\": \"group\",\n \"is_scim_managed\": false\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Create group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested group, user, or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The organization has reached its maximum number of groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The group operation could not be completed because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"group_type\": \"group\",\n \"is_scim_managed\": false\n}\n" } } } }, "/organization/groups/{group_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieve group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested group, user, or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The group operation could not be completed because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Update group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested group, user, or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The group operation could not be completed because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Delete group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "List group organization role assignments", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 \"assignment_sources\": [\n {\n \"principal_id\": \"group_01J1F8ABCDXYZ\",\n \"principal_type\": \"group\"\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Assign organization role to group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve group organization role", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Unassign organization role from group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "List group users", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested group, user, or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "502": { "description": "The upstream group service returned an invalid pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Add group user", "description": "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" } } } }, "400": { "description": "The request contains invalid parameters or an invalid body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller lacks the required permissions or is not using an admin API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The group or user was not found in the organization, or this endpoint is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current state of the group.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve group user", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested group, user, or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Remove group user", "description": "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" } } } }, "400": { "description": "The request contains invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller lacks the required permissions or is not using an admin API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The group or user was not found in the organization, or this endpoint is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current state of the group.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "List invites", "description": "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" } } } }, "400": { "description": "The invite listing parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The invite specified by the after cursor was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"projects\": []\n }\n ],\n \"first_id\": \"invite-abc\",\n \"last_id\": \"invite-abc\",\n \"has_more\": false\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Create invite", "description": "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" } } } }, "201": { "description": "User invited successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "400": { "description": "The invite request is invalid or the user has already joined or been invited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve invite", "description": "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" } } } }, "400": { "description": "The invite request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The invite was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The invite could not be retrieved because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"projects\": []\n}\n" } } }, "delete": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Delete invite", "description": "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" } } } }, "400": { "description": "The request is invalid or the invite cannot be deleted in its current state.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller is not permitted to delete the invite.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The invite was not found in the organization.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit was exceeded.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List projects", "description": "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" } } } }, "400": { "description": "The project listing parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project specified by the after cursor was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 project", "description": "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" } } } }, "201": { "description": "Project created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "The project creation request is invalid or contains incompatible settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve project", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "group": "administration", "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": "Modify project", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A requested project, user, service account, or API key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List project API keys", "description": "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" } } } }, "400": { "description": "The listing parameters are invalid or the project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve project API key", "description": "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" } } } }, "400": { "description": "The project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or API key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Delete project API key", "description": "Deletes an API key from the project, including keys owned by service accounts.\n\nRequires permission to write project API keys. Deleting a service-account key\ndoes not delete the service account or its other keys.\n\nReturns confirmation of the key deletion.\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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A requested project, user, service account, or API key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Update project API key", "description": "Updates the scopes and/or expiration of an existing API key in the project, including a\nservice-account-owned key. Requires permission to write project API keys.\n\nProvide at least one of `scopes` or `expires_in_seconds`. Omitted fields stay\nunchanged; neither field accepts `null`. Both changes are saved together.\n\n`scopes` replaces the key's scope restrictions using the same scope identifiers\nas the dashboard. An empty array means All permissions, subject to the owner's\neffective access; it does not mean no access. Use `[\"api.all.read\"]` for read-only\naccess or specific scopes such as `[\"api.files.read\"]` for restricted access.\nThis does not change user or service-account roles or grant admin permissions.\nScope changes follow the same authentication-cache propagation as dashboard edits.\n\nProvide `expires_in_seconds` to set the expiration relative to this request.\nThe value must satisfy the organization's and project's expiry policies.\nExpired keys cannot be updated. Retrying resets the expiration relative to\nthe new request. The response contains only the redacted key, not its secret.\n", "operationId": "update-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" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectApiKeyBody" }, "example": { "scopes": [ "api.all.read" ] } } } }, "responses": { "200": { "description": "Project API key updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectApiKey" } } } }, "400": { "description": "The project is archived, the key is expired, or the requested scopes or expiration are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to update this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or API key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "group": "administration", "examples": { "request": { "curl": "curl -X POST 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 -d '{\"scopes\": [\"api.all.read\"], \"expires_in_seconds\": 86400}'\n" }, "response": "{\n \"object\": \"organization.project.api_key\",\n \"redacted_value\": \"sk-abc...def\",\n \"name\": \"My API Key\",\n \"created_at\": 1711471533,\n \"expires_at\": 1711557933,\n \"last_used_at\": null,\n \"id\": \"key_abc\",\n \"owner_project_access\": \"active\",\n \"owner\": {\n \"type\": \"service_account\",\n \"service_account\": {\n \"id\": \"svc_acct_abc\",\n \"name\": \"My Service Account\",\n \"role\": \"member\",\n \"created_at\": 1711471533\n }\n }\n}\n" } } } }, "/organization/projects/{project_id}/archive": { "post": { "summary": "Archive project", "description": "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" } } } }, "400": { "description": "The project is already archived or is the default project and cannot be archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 project certificates", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 for project", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A certificate was not found in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The certificate update could not be completed because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 for project", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A certificate was not found in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The certificate update could not be completed because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve project data retention", "description": "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" } } } }, "400": { "description": "The project ID is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The organization or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Update project data retention", "description": "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" } } } }, "400": { "description": "The requested data retention setting or transition is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The organization or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List project groups", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested group, user, or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 \"group_type\": \"group\",\n \"created_at\": 1711471533\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Add project group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested group, user, or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The group operation could not be completed because of a server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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 \"group_type\": \"group\",\n \"created_at\": 1711471533\n}\n" } } } }, "/organization/projects/{project_id}/groups/{group_id}": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Retrieve project group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested group, user, or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Remove project group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested group, user, or project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve project hosted tool permissions", "description": "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" } } } }, "400": { "description": "The project ID is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Modify project hosted tool permissions", "description": "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" } } } }, "400": { "description": "The hosted tool permission request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The requested project setting conflicts with the organization policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve project model permissions", "description": "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" } } } }, "400": { "description": "The project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or model permission settings were not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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-6-astra\",\n \"o3\"\n ]\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Modify project model permissions", "description": "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" } } } }, "400": { "description": "The model permission request is invalid or the project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Delete project model permissions", "description": "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" } } } }, "400": { "description": "The project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or model permission settings were not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List project rate limits", "description": "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" } } } }, "400": { "description": "The rate limit listing parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or pagination cursor was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "project_not_found", "message": "The project proj_abc was not found", "type": "invalid_request_error", "param": null } } } } } }, "x-oaiMeta": { "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" } } } }, "/organization/projects/{project_id}/rate_limits/{rate_limit_id}": { "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Modify project rate limit", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "project_not_found", "message": "The project proj_abc was not found", "type": "invalid_request_error", "param": null } } } } } }, "x-oaiMeta": { "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" } } } }, "/organization/projects/{project_id}/service_accounts": { "get": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "List project service accounts", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A requested project, user, service account, or API key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Create project service account", "description": "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" } } } }, "201": { "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A requested project, user, service account, or API key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve project service account", "description": "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" } } } }, "400": { "description": "The project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or service account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Update project service account", "description": "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" } } } }, "400": { "description": "The service account update is invalid or the project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or service account was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Delete project service account", "description": "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" } } } }, "400": { "description": "The request is invalid or the service account cannot be deleted in its current state.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller is not permitted to delete the service account.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or service account was not found in the organization.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit was exceeded.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List project spend alerts", "description": "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" } } } }, "400": { "description": "The spend alert listing parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or spend alert pagination cursor was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Create project spend alert", "description": "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" } } } }, "400": { "description": "The spend alert request is invalid or conflicts with the hard spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve project spend alert", "description": "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" } } } }, "400": { "description": "The project ID is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or spend alert was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Update project spend alert", "description": "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" } } } }, "400": { "description": "The spend alert update is invalid or conflicts with the hard spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or spend alert was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Delete project spend alert", "description": "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" } } } }, "400": { "description": "The project ID is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or spend alert was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List project users", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A requested project, user, service account, or API key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Create project user", "description": "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" } } } }, "201": { "description": "User added to project successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUser" } } } }, "400": { "description": "The request is invalid or the user cannot be added to the project in its current state.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller lacks the required permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or user was not found in the organization.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current state of the resource.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request exceeded the rate limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve project user", "description": "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" } } } }, "400": { "description": "The project is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The project or user was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Modify project user", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A requested project, user, service account, or API key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Delete project user", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "A requested project, user, service account, or API key was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List organization roles", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Create organization role", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve organization role", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Update organization role", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Delete organization role", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "List organization spend alerts", "description": "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" } } } }, "400": { "description": "The spend alert listing parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The spend alert specified by the after cursor was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Create organization spend alert", "description": "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" } } } }, "400": { "description": "The spend alert request is invalid or conflicts with the hard spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve organization spend alert", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The spend alert was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Update organization spend alert", "description": "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" } } } }, "400": { "description": "The spend alert update is invalid or conflicts with the hard spend limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The spend alert was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Delete organization spend alert", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The spend alert was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Audio speeches", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Audio transcriptions", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Code interpreter sessions", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Completions", "description": "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`, `api_source` or any combination of them. When grouped by `api_source`, results use `agents_api` for attributed Agents API activity and `unlabeled` for all other activity. Without source grouping, `api_source` is null.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "api_key_id", "model", "batch", "service_tier", "api_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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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_cache_write_30m_tokens\": 75,\n \"input_cache_write_12h_tokens\": 25,\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": "Embeddings", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "File search calls", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Images", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Moderations", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Vector stores", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Web search calls", "description": "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`, `api_source` or any combination of them. When grouped by `api_source`, results use `agents_api` for attributed Agents API activity and `unlabeled` for all other activity. Without source grouping, `api_source` is null.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "project_id", "user_id", "api_key_id", "model", "context_level", "api_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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "List users", "description": "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" } } } }, "400": { "description": "The user listing parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Retrieve user", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The user was not found in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Modify user", "description": "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" } } } }, "400": { "description": "The requested user role is invalid or the update is not permitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The user was not found in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many management requests. Reduce the request rate and try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "Delete user", "description": "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" } } } }, "400": { "description": "The request is invalid or the user cannot be removed in their current state.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller is not permitted to delete the user.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The user was not found in the organization.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The request rate limit was exceeded.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-oaiMeta": { "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": "List user organization role assignments", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 \"assignment_sources\": [\n {\n \"principal_id\": \"user_abc123\",\n \"principal_type\": \"user\"\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Assign organization role to user", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve user organization role", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Unassign organization role from user", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "List project group role assignments", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 \"assignment_sources\": [\n {\n \"principal_id\": \"group_01J1F8ABCDXYZ\",\n \"principal_type\": \"group\"\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Assign project role to group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve project group role", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Unassign project role from group", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "List project roles", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Create project role", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve project role", "description": "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" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Update project role", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Delete project role", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "List project user role assignments", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 \"assignment_sources\": [\n {\n \"principal_id\": \"user_abc123\",\n \"principal_type\": \"user\"\n }\n ]\n }\n ],\n \"has_more\": false,\n \"next\": null\n}\n" } } }, "post": { "security": [ { "AdminApiKeyAuth": [] } ], "summary": "Assign project role to user", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Retrieve project user role", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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": "Unassign project role from user", "description": "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" } } } }, "400": { "description": "The request parameters are invalid or the requested operation cannot be performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller does not have permission to perform this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "The endpoint is unavailable or a requested resource was not found in this organization or project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-oaiMeta": { "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 call", "description": "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": { "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=