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. required: false schema: type: integer default: 20 - name: order in: query description: | Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. schema: type: string default: desc enum: - asc - desc - name: after in: query description: | A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. schema: type: string - name: before in: query description: | A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListAssistantsResponse' '429': $ref: '#/components/responses/TooManyRequests' x-oaiMeta: group: assistants examples: request: curl: | curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" python: | from openai import OpenAI client = OpenAI() my_assistants = client.beta.assistants.list( order="desc", limit="20", ) print(my_assistants.data) javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const myAssistants = await openai.beta.assistants.list({ order: "desc", limit: "20", }); console.log(myAssistants.data); } main(); response: | { "object": "list", "data": [ { "id": "asst_abc123", "object": "assistant", "created_at": 1698982736, "name": "Coding Tutor", "description": null, "model": "gpt-5", "instructions": "You are a helpful assistant designed to make me better at coding!", "tools": [], "tool_resources": {}, "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" }, { "id": "asst_abc456", "object": "assistant", "created_at": 1698982718, "name": "My Assistant", "description": null, "model": "gpt-5", "instructions": "You are a helpful assistant designed to make me better at coding!", "tools": [], "tool_resources": {}, "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" }, { "id": "asst_abc789", "object": "assistant", "created_at": 1698982643, "name": null, "description": null, "model": "gpt-5", "instructions": null, "tools": [], "tool_resources": {}, "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" } ], "first_id": "asst_abc123", "last_id": "asst_abc789", "has_more": false } 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" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", "name": "Math Tutor", "tools": [{"type": "code_interpreter"}], "model": "gpt-5" }' python: | from openai import OpenAI client = OpenAI() my_assistant = client.beta.assistants.create( instructions="You are a personal math tutor. When asked a question, write and run Python code to answer the question.", name="Math Tutor", tools=[{"type": "code_interpreter"}], model="gpt-5", ) print(my_assistant) javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const myAssistant = await openai.beta.assistants.create({ instructions: "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", name: "Math Tutor", tools: [{ type: "code_interpreter" }], model: "gpt-5", }); console.log(myAssistant); } main(); response: | { "id": "asst_abc123", "object": "assistant", "created_at": 1698984975, "name": "Math Tutor", "description": null, "model": "gpt-5", "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", "tools": [ { "type": "code_interpreter" } ], "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" } - title: Files request: curl: | curl https://api.openai.com/v1/assistants \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", "tools": [{"type": "file_search"}], "tool_resources": {"file_search": {"vector_store_ids": ["vs_123"]}}, "model": "gpt-5" }' python: | from openai import OpenAI client = OpenAI() my_assistant = client.beta.assistants.create( instructions="You are an HR bot, and you have access to files to answer employee questions about company policies.", name="HR Helper", tools=[{"type": "file_search"}], tool_resources={"file_search": {"vector_store_ids": ["vs_123"]}}, model="gpt-5" ) print(my_assistant) javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const myAssistant = await openai.beta.assistants.create({ instructions: "You are an HR bot, and you have access to files to answer employee questions about company policies.", name: "HR Helper", tools: [{ type: "file_search" }], tool_resources: { file_search: { vector_store_ids: ["vs_123"] } }, model: "gpt-5" }); console.log(myAssistant); } main(); response: | { "id": "asst_abc123", "object": "assistant", "created_at": 1699009403, "name": "HR Helper", "description": null, "model": "gpt-5", "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", "tools": [ { "type": "file_search" } ], "tool_resources": { "file_search": { "vector_store_ids": ["vs_123"] } }, "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" } /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 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" python: | from openai import OpenAI client = OpenAI() my_assistant = client.beta.assistants.retrieve("asst_abc123") print(my_assistant) javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const myAssistant = await openai.beta.assistants.retrieve( "asst_abc123" ); console.log(myAssistant); } main(); response: | { "id": "asst_abc123", "object": "assistant", "created_at": 1699009709, "name": "HR Helper", "description": null, "model": "gpt-5", "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", "tools": [ { "type": "file_search" } ], "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" } 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 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", "tools": [{"type": "file_search"}], "model": "gpt-5" }' python: | from openai import OpenAI client = OpenAI() my_updated_assistant = client.beta.assistants.update( "asst_abc123", instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", name="HR Helper", tools=[{"type": "file_search"}], model="gpt-5" ) print(my_updated_assistant) javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const myUpdatedAssistant = await openai.beta.assistants.update( "asst_abc123", { instructions: "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", name: "HR Helper", tools: [{ type: "file_search" }], model: "gpt-5" } ); console.log(myUpdatedAssistant); } main(); response: | { "id": "asst_123", "object": "assistant", "created_at": 1699009709, "name": "HR Helper", "description": null, "model": "gpt-5", "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", "tools": [ { "type": "file_search" } ], "tool_resources": { "file_search": { "vector_store_ids": [] } }, "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" } 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 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -X DELETE python: | from openai import OpenAI client = OpenAI() response = client.beta.assistants.delete("asst_abc123") print(response) javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const response = await openai.beta.assistants.delete("asst_abc123"); console.log(response); } main(); response: | { "id": "asst_abc123", "object": "assistant.deleted", "deleted": true } /audio/speech: post: operationId: createSpeech tags: - Audio summary: Create speech description: | Generates audio from the input text. Returns the audio file content, or a stream of audio events. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini-tts", "input": "The quick brown fox jumped over the lazy dog.", "voice": "alloy" }' \ --output speech.mp3 python: | from pathlib import Path import openai speech_file_path = Path(__file__).parent / "speech.mp3" with openai.audio.speech.with_streaming_response.create( model="gpt-4o-mini-tts", voice="alloy", input="The quick brown fox jumped over the lazy dog." ) as response: response.stream_to_file(speech_file_path) javascript: | import fs from "fs"; import path from "path"; import OpenAI from "openai"; const openai = new OpenAI(); const speechFile = path.resolve("./speech.mp3"); async function main() { const mp3 = await openai.audio.speech.create({ model: "gpt-4o-mini-tts", voice: "alloy", input: "Today is a wonderful day to build something people love!", }); console.log(speechFile); const buffer = Buffer.from(await mp3.arrayBuffer()); await fs.promises.writeFile(speechFile, buffer); } main(); csharp: | using System; using System.IO; using OpenAI.Audio; AudioClient client = new( model: "gpt-4o-mini-tts", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); BinaryData speech = client.GenerateSpeech( text: "The quick brown fox jumped over the lazy dog.", voice: GeneratedSpeechVoice.Alloy ); using FileStream stream = File.OpenWrite("speech.mp3"); speech.ToStream().CopyTo(stream); - title: SSE Stream Format request: curl: | curl https://api.openai.com/v1/audio/speech \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini-tts", "input": "The quick brown fox jumped over the lazy dog.", "voice": "alloy", "stream_format": "sse" }' /audio/transcriptions: post: operationId: createTranscription tags: - Audio summary: Create transcription description: | Transcribes audio into the input language. Returns a transcription object in `json`, `diarized_json`, or `verbose_json` format, plain text in `text`, `srt`, or `vtt` format, or a stream of transcript events. Supported formats depend on the model. 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' x-stainless-skip: - go - $ref: '#/components/schemas/CreateTranscriptionResponseVerboseJson' discriminator: propertyName: task 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F model="gpt-4o-transcribe" python: | from openai import OpenAI client = OpenAI() audio_file = open("speech.mp3", "rb") transcript = client.audio.transcriptions.create( model="gpt-4o-transcribe", file=audio_file ) javascript: | import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const transcription = await openai.audio.transcriptions.create({ file: fs.createReadStream("audio.mp3"), model: "gpt-4o-transcribe", }); console.log(transcription.text); } main(); csharp: | using System; using OpenAI.Audio; string audioFilePath = "audio.mp3"; AudioClient client = new( model: "gpt-4o-transcribe", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); AudioTranscription transcription = client.TranscribeAudio(audioFilePath); Console.WriteLine($"{transcription.Text}"); response: | { "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.", "usage": { "type": "tokens", "input_tokens": 14, "input_token_details": { "text_tokens": 0, "audio_tokens": 14 }, "output_tokens": 45, "total_tokens": 59 } } - title: Diarization request: curl: | curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/meeting.wav" \ -F model="gpt-4o-transcribe-diarize" \ -F response_format="diarized_json" \ -F chunking_strategy=auto \ -F 'known_speaker_names[]=agent' \ -F 'known_speaker_references[]=data:audio/wav;base64,AAA...' python: | import base64 from openai import OpenAI client = OpenAI() def to_data_url(path: str) -> str: with open(path, "rb") as fh: return "data:audio/wav;base64," + base64.b64encode(fh.read()).decode("utf-8") with open("meeting.wav", "rb") as audio_file: transcript = client.audio.transcriptions.create( model="gpt-4o-transcribe-diarize", file=audio_file, response_format="diarized_json", chunking_strategy="auto", extra_body={ "known_speaker_names": ["agent"], "known_speaker_references": [to_data_url("agent.wav")], }, ) print(transcript.segments) javascript: | import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); const speakerRef = fs.readFileSync("agent.wav").toString("base64"); const transcript = await openai.audio.transcriptions.create({ file: fs.createReadStream("meeting.wav"), model: "gpt-4o-transcribe-diarize", response_format: "diarized_json", chunking_strategy: "auto", extra_body: { known_speaker_names: ["agent"], known_speaker_references: [`data:audio/wav;base64,${speakerRef}`], }, }); console.log(transcript.segments); response: | { "task": "transcribe", "duration": 27.4, "text": "Agent: Thanks for calling OpenAI support.\nA: Hi, I'm trying to enable diarization.\nAgent: Happy to walk you through the steps.", "segments": [ { "type": "transcript.text.segment", "id": "seg_001", "start": 0.0, "end": 4.7, "text": "Thanks for calling OpenAI support.", "speaker": "agent" }, { "type": "transcript.text.segment", "id": "seg_002", "start": 4.7, "end": 11.8, "text": "Hi, I'm trying to enable diarization.", "speaker": "A" }, { "type": "transcript.text.segment", "id": "seg_003", "start": 12.1, "end": 18.5, "text": "Happy to walk you through the steps.", "speaker": "agent" } ], "usage": { "type": "duration", "seconds": 27 } } - title: Streaming request: curl: | curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F model="gpt-4o-mini-transcribe" \ -F stream=true python: | from openai import OpenAI client = OpenAI() audio_file = open("speech.mp3", "rb") stream = client.audio.transcriptions.create( file=audio_file, model="gpt-4o-mini-transcribe", stream=True ) for event in stream: print(event) javascript: | import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); const stream = await openai.audio.transcriptions.create({ file: fs.createReadStream("audio.mp3"), model: "gpt-4o-mini-transcribe", stream: true, }); for await (const event of stream) { console.log(event); } response: | data: {"type":"transcript.text.delta","delta":"I","logprobs":[{"token":"I","logprob":-0.00007588794,"bytes":[73]}]} data: {"type":"transcript.text.delta","delta":" see","logprobs":[{"token":" see","logprob":-3.1281633e-7,"bytes":[32,115,101,101]}]} data: {"type":"transcript.text.delta","delta":" skies","logprobs":[{"token":" skies","logprob":-2.3392786e-6,"bytes":[32,115,107,105,101,115]}]} data: {"type":"transcript.text.delta","delta":" of","logprobs":[{"token":" of","logprob":-3.1281633e-7,"bytes":[32,111,102]}]} data: {"type":"transcript.text.delta","delta":" blue","logprobs":[{"token":" blue","logprob":-1.0280384e-6,"bytes":[32,98,108,117,101]}]} data: {"type":"transcript.text.delta","delta":" and","logprobs":[{"token":" and","logprob":-0.0005108566,"bytes":[32,97,110,100]}]} data: {"type":"transcript.text.delta","delta":" clouds","logprobs":[{"token":" clouds","logprob":-1.9361265e-7,"bytes":[32,99,108,111,117,100,115]}]} data: {"type":"transcript.text.delta","delta":" of","logprobs":[{"token":" of","logprob":-1.9361265e-7,"bytes":[32,111,102]}]} data: {"type":"transcript.text.delta","delta":" white","logprobs":[{"token":" white","logprob":-7.89631e-7,"bytes":[32,119,104,105,116,101]}]} data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.0014890312,"bytes":[44]}]} data: {"type":"transcript.text.delta","delta":" the","logprobs":[{"token":" the","logprob":-0.0110956915,"bytes":[32,116,104,101]}]} data: {"type":"transcript.text.delta","delta":" bright","logprobs":[{"token":" bright","logprob":0.0,"bytes":[32,98,114,105,103,104,116]}]} data: {"type":"transcript.text.delta","delta":" blessed","logprobs":[{"token":" blessed","logprob":-0.000045848617,"bytes":[32,98,108,101,115,115,101,100]}]} data: {"type":"transcript.text.delta","delta":" days","logprobs":[{"token":" days","logprob":-0.000010802739,"bytes":[32,100,97,121,115]}]} data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.00001700133,"bytes":[44]}]} data: {"type":"transcript.text.delta","delta":" the","logprobs":[{"token":" the","logprob":-0.0000118755715,"bytes":[32,116,104,101]}]} data: {"type":"transcript.text.delta","delta":" dark","logprobs":[{"token":" dark","logprob":-5.5122365e-7,"bytes":[32,100,97,114,107]}]} data: {"type":"transcript.text.delta","delta":" sacred","logprobs":[{"token":" sacred","logprob":-5.4385737e-6,"bytes":[32,115,97,99,114,101,100]}]} data: {"type":"transcript.text.delta","delta":" nights","logprobs":[{"token":" nights","logprob":-4.00813e-6,"bytes":[32,110,105,103,104,116,115]}]} data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.0036910512,"bytes":[44]}]} data: {"type":"transcript.text.delta","delta":" and","logprobs":[{"token":" and","logprob":-0.0031903093,"bytes":[32,97,110,100]}]} data: {"type":"transcript.text.delta","delta":" I","logprobs":[{"token":" I","logprob":-1.504853e-6,"bytes":[32,73]}]} data: {"type":"transcript.text.delta","delta":" think","logprobs":[{"token":" think","logprob":-4.3202e-7,"bytes":[32,116,104,105,110,107]}]} data: {"type":"transcript.text.delta","delta":" to","logprobs":[{"token":" to","logprob":-1.9361265e-7,"bytes":[32,116,111]}]} data: {"type":"transcript.text.delta","delta":" myself","logprobs":[{"token":" myself","logprob":-1.7432603e-6,"bytes":[32,109,121,115,101,108,102]}]} data: {"type":"transcript.text.delta","delta":",","logprobs":[{"token":",","logprob":-0.29254505,"bytes":[44]}]} data: {"type":"transcript.text.delta","delta":" what","logprobs":[{"token":" what","logprob":-0.016815351,"bytes":[32,119,104,97,116]}]} data: {"type":"transcript.text.delta","delta":" a","logprobs":[{"token":" a","logprob":-3.1281633e-7,"bytes":[32,97]}]} data: {"type":"transcript.text.delta","delta":" wonderful","logprobs":[{"token":" wonderful","logprob":-2.1008714e-6,"bytes":[32,119,111,110,100,101,114,102,117,108]}]} data: {"type":"transcript.text.delta","delta":" world","logprobs":[{"token":" world","logprob":-8.180258e-6,"bytes":[32,119,111,114,108,100]}]} data: {"type":"transcript.text.delta","delta":".","logprobs":[{"token":".","logprob":-0.014231676,"bytes":[46]}]} data: {"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}} - title: Logprobs request: curl: | curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F "include[]=logprobs" \ -F model="gpt-4o-transcribe" \ -F response_format="json" python: | from openai import OpenAI client = OpenAI() audio_file = open("speech.mp3", "rb") transcript = client.audio.transcriptions.create( file=audio_file, model="gpt-4o-transcribe", response_format="json", include=["logprobs"] ) print(transcript) javascript: | import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const transcription = await openai.audio.transcriptions.create({ file: fs.createReadStream("audio.mp3"), model: "gpt-4o-transcribe", response_format: "json", include: ["logprobs"] }); console.log(transcription); } main(); response: | { "text": "Hey, my knee is hurting and I want to see the doctor tomorrow ideally.", "logprobs": [ { "token": "Hey", "logprob": -1.0415299, "bytes": [72, 101, 121] }, { "token": ",", "logprob": -9.805982e-5, "bytes": [44] }, { "token": " my", "logprob": -0.00229799, "bytes": [32, 109, 121] }, { "token": " knee", "logprob": -4.7159858e-5, "bytes": [32, 107, 110, 101, 101] }, { "token": " is", "logprob": -0.043909557, "bytes": [32, 105, 115] }, { "token": " hurting", "logprob": -1.1041146e-5, "bytes": [32, 104, 117, 114, 116, 105, 110, 103] }, { "token": " and", "logprob": -0.011076359, "bytes": [32, 97, 110, 100] }, { "token": " I", "logprob": -5.3193703e-6, "bytes": [32, 73] }, { "token": " want", "logprob": -0.0017156356, "bytes": [32, 119, 97, 110, 116] }, { "token": " to", "logprob": -7.89631e-7, "bytes": [32, 116, 111] }, { "token": " see", "logprob": -5.5122365e-7, "bytes": [32, 115, 101, 101] }, { "token": " the", "logprob": -0.0040786397, "bytes": [32, 116, 104, 101] }, { "token": " doctor", "logprob": -2.3392786e-6, "bytes": [32, 100, 111, 99, 116, 111, 114] }, { "token": " tomorrow", "logprob": -7.89631e-7, "bytes": [32, 116, 111, 109, 111, 114, 114, 111, 119] }, { "token": " ideally", "logprob": -0.5800861, "bytes": [32, 105, 100, 101, 97, 108, 108, 121] }, { "token": ".", "logprob": -0.00011093382, "bytes": [46] } ], "usage": { "type": "tokens", "input_tokens": 14, "input_token_details": { "text_tokens": 0, "audio_tokens": 14 }, "output_tokens": 45, "total_tokens": 59 } } - title: Word timestamps request: curl: | curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F "timestamp_granularities[]=word" \ -F model="whisper-1" \ -F response_format="verbose_json" python: | from openai import OpenAI client = OpenAI() audio_file = open("speech.mp3", "rb") transcript = client.audio.transcriptions.create( file=audio_file, model="whisper-1", response_format="verbose_json", timestamp_granularities=["word"] ) print(transcript.words) javascript: | import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const transcription = await openai.audio.transcriptions.create({ file: fs.createReadStream("audio.mp3"), model: "whisper-1", response_format: "verbose_json", timestamp_granularities: ["word"] }); console.log(transcription.text); } main(); csharp: | using System; using OpenAI.Audio; string audioFilePath = "audio.mp3"; AudioClient client = new( model: "whisper-1", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); AudioTranscriptionOptions options = new() { ResponseFormat = AudioTranscriptionFormat.Verbose, TimestampGranularities = AudioTimestampGranularities.Word, }; AudioTranscription transcription = client.TranscribeAudio(audioFilePath, options); Console.WriteLine($"{transcription.Text}"); response: | { "task": "transcribe", "language": "english", "duration": 0.5, "text": "Hello.", "words": [ { "word": "Hello", "start": 0.0, "end": 0.5 } ], "usage": { "type": "duration", "seconds": 1 } } - title: Segment timestamps request: curl: | curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F "timestamp_granularities[]=segment" \ -F model="whisper-1" \ -F response_format="verbose_json" python: | from openai import OpenAI client = OpenAI() audio_file = open("speech.mp3", "rb") transcript = client.audio.transcriptions.create( file=audio_file, model="whisper-1", response_format="verbose_json", timestamp_granularities=["segment"] ) print(transcript.words) javascript: | import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const transcription = await openai.audio.transcriptions.create({ file: fs.createReadStream("audio.mp3"), model: "whisper-1", response_format: "verbose_json", timestamp_granularities: ["segment"] }); console.log(transcription.text); } main(); csharp: | using System; using OpenAI.Audio; string audioFilePath = "audio.mp3"; AudioClient client = new( model: "whisper-1", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); AudioTranscriptionOptions options = new() { ResponseFormat = AudioTranscriptionFormat.Verbose, TimestampGranularities = AudioTimestampGranularities.Segment, }; AudioTranscription transcription = client.TranscribeAudio(audioFilePath, options); Console.WriteLine($"{transcription.Text}"); response: | { "task": "transcribe", "language": "english", "duration": 3.32, "text": "The beach was a popular spot on a hot summer day.", "segments": [ { "id": 0, "seek": 0, "start": 0.0, "end": 3.319999933242798, "text": " The beach was a popular spot on a hot summer day.", "tokens": [ 50364, 440, 7534, 390, 257, 3743, 4008, 322, 257, 2368, 4266, 786, 13, 50530 ], "temperature": 0.0, "avg_logprob": -0.2860786020755768, "compression_ratio": 1.2363636493682861, "no_speech_prob": 0.00985979475080967 } ], "usage": { "type": "duration", "seconds": 4 } } /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: anyOf: - $ref: '#/components/schemas/CreateTranslationResponseJson' - $ref: '#/components/schemas/CreateTranslationResponseVerboseJson' x-stainless-skip: - go 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/german.m4a" \ -F model="whisper-1" python: | from openai import OpenAI client = OpenAI() audio_file = open("speech.mp3", "rb") transcript = client.audio.translations.create( model="whisper-1", file=audio_file ) javascript: | import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const translation = await openai.audio.translations.create({ file: fs.createReadStream("speech.mp3"), model: "whisper-1", }); console.log(translation.text); } main(); csharp: | using System; using OpenAI.Audio; string audioFilePath = "audio.mp3"; AudioClient client = new( model: "whisper-1", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); AudioTranscription transcription = client.TranscribeAudio(audioFilePath); Console.WriteLine($"{transcription.Text}"); response: | { "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?" } /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 \ -X POST \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F "name=John Doe" \ -F "language=en-US" \ -F "recording=@$HOME/consent_recording.wav;type=audio/x-wav" 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. - name: limit in: query description: | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. required: false schema: type: integer default: 20 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" 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 \ -X POST \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "John Doe" }' 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 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY" /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. For 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. Returns 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. requestBody: required: true content: 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 \ -X POST \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "prompt", "name": "Warm narrator", "prompt": "A warm, calm narrator with a clear, measured delivery.", "model": "auto" }' /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input_file_id": "file-abc123", "endpoint": "/v1/chat/completions", "completion_window": "24h" }' python: | from openai import OpenAI client = OpenAI() client.batches.create( input_file_id="file-abc123", endpoint="/v1/chat/completions", completion_window="24h" ) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const batch = await openai.batches.create({ input_file_id: "file-abc123", endpoint: "/v1/chat/completions", completion_window: "24h" }); console.log(batch); } main(); response: | { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/chat/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "validating", "output_file_id": null, "error_file_id": null, "created_at": 1711471533, "in_progress_at": null, "expires_at": null, "finalizing_at": null, "completed_at": null, "failed_at": null, "expired_at": null, "cancelling_at": null, "cancelled_at": null, "request_counts": { "total": 0, "completed": 0, "failed": 0 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly eval job" } } 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. - name: limit in: query description: | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. required: false schema: type: integer default: 20 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() client.batches.list() javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const list = await openai.batches.list(); for await (const batch of list) { console.log(batch); } } main(); response: | { "object": "list", "data": [ { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/chat/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "completed", "output_file_id": "file-cvaTdG", "error_file_id": "file-HOWS94", "created_at": 1711471533, "in_progress_at": 1711471538, "expires_at": 1711557933, "finalizing_at": 1711493133, "completed_at": 1711493163, "failed_at": null, "expired_at": null, "cancelling_at": null, "cancelled_at": null, "request_counts": { "total": 100, "completed": 95, "failed": 5 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly job" } } ], "first_id": "batch_abc123", "last_id": "batch_abc123", "has_more": false } /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ python: | from openai import OpenAI client = OpenAI() client.batches.retrieve("batch_abc123") javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const batch = await openai.batches.retrieve("batch_abc123"); console.log(batch); } main(); response: | { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "completed", "output_file_id": "file-cvaTdG", "error_file_id": "file-HOWS94", "created_at": 1711471533, "in_progress_at": 1711471538, "expires_at": 1711557933, "finalizing_at": 1711493133, "completed_at": 1711493163, "failed_at": null, "expired_at": null, "cancelling_at": null, "cancelled_at": null, "request_counts": { "total": 100, "completed": 95, "failed": 5 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly eval job" } } /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -X POST python: | from openai import OpenAI client = OpenAI() client.batches.cancel("batch_abc123") javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const batch = await openai.batches.cancel("batch_abc123"); console.log(batch); } main(); response: | { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/chat/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "cancelling", "output_file_id": null, "error_file_id": null, "created_at": 1711471533, "in_progress_at": 1711471538, "expires_at": 1711557933, "finalizing_at": null, "completed_at": null, "failed_at": null, "expired_at": null, "cancelling_at": 1711475133, "cancelled_at": null, "request_counts": { "total": 100, "completed": 23, "failed": 1 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly eval job" } } /chat/completions: get: operationId: listChatCompletions tags: - Chat summary: List Chat Completions description: | List stored Chat Completions. Only Chat Completions that have been stored with the `store` parameter set to `true` will be returned. 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: `metadata[key1]=value1&metadata[key2]=value2` 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() completions = client.chat.completions.list() print(completions) response: | { "object": "list", "data": [ { "object": "chat.completion", "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", "model": "gpt-6-astra", "created": 1738960610, "request_id": "req_ded8ab984ec4bf840f37566c1011c417", "tool_choice": null, "usage": { "total_tokens": 31, "completion_tokens": 18, "prompt_tokens": 13 }, "seed": 4944116822809979520, "top_p": 1.0, "temperature": 1.0, "presence_penalty": 0.0, "frequency_penalty": 0.0, "system_fingerprint": "fp_50cad350e4", "input_user": null, "service_tier": "default", "tools": null, "metadata": {}, "choices": [ { "index": 0, "message": { "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", "role": "assistant", "tool_calls": null, "function_call": null }, "finish_reason": "stop", "logprobs": null } ], "response_format": null } ], "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", "has_more": false } 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) to take advantage of the latest OpenAI platform features. Compare [Chat Completions with Responses](https://developers.openai.com/api/docs/guides/migrate-to-responses?api-mode=responses). --- Creates a model response for the given chat conversation. Learn more in the [text generation](https://developers.openai.com/api/docs/guides/text), [vision](https://developers.openai.com/api/docs/guides/images-vision), and [audio](https://developers.openai.com/api/docs/guides/audio) guides. Parameter support can differ depending on the model used to generate the response, particularly for newer reasoning models. Parameters that are only supported for reasoning models are noted below. For the current state of unsupported parameters in reasoning models, [refer to the reasoning guide](https://developers.openai.com/api/docs/guides/reasoning). Returns a chat completion object, or a streamed sequence of chat completion chunk objects if the request is streamed. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateChatCompletionRequest' responses: '200': description: | Returns a Chat Completion object for a non-streaming request. If `stream` is `true`, returns server-sent events (`text/event-stream`). Successful chunk frames contain a JSON Chat Completion chunk matching `CreateChatCompletionStreamResponse`. On normal completion, the final frame is: ```text data: [DONE] ``` The final frame ends with a blank line. `[DONE]` is literal text, not a JSON chunk, and this frame has no `event: done` field. If a failure occurs after streaming has started, a data frame may contain a JSON object with an `error` field instead of a completion chunk. The streaming schema describes successful JSON chunks, not error frames or the completion marker. An interrupted stream may end without the marker. 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 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-6-astra", "messages": [ { "role": "developer", "content": "You are a helpful assistant." }, { "role": "user", "content": "Hello!" } ] }' python: | from openai import OpenAI client = OpenAI() completion = client.chat.completions.create( model="gpt-6-astra", messages=[ {"role": "developer", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ] ) print(completion.choices[0].message) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const completion = await openai.chat.completions.create({ messages: [{ role: "developer", content: "You are a helpful assistant." }], model: "gpt-6-astra", store: true, }); console.log(completion.choices[0]); } main(); csharp: | using System; using System.Collections.Generic; using OpenAI.Chat; ChatClient client = new( model: "gpt-6-astra", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); List messages = [ new SystemChatMessage("You are a helpful assistant."), new UserChatMessage("Hello!") ]; ChatCompletion completion = client.CompleteChat(messages); Console.WriteLine(completion.Content[0].Text); response: | { "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT", "object": "chat.completion", "created": 1741569952, "model": "gpt-6-astra", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I assist you today?", "refusal": null, "annotations": [] }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 19, "completion_tokens": 10, "total_tokens": 29, "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } }, "service_tier": "default" } - title: Image input request: curl: | curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-6-astra", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is in this image?" }, { "type": "image_url", "image_url": { "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" } } ] } ], "max_tokens": 300 }' python: | from openai import OpenAI client = OpenAI() response = client.chat.completions.create( model="gpt-6-astra", messages=[ { "role": "user", "content": [ {"type": "text", "text": "What's in this image?"}, { "type": "image_url", "image_url": { "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", } }, ], } ], max_tokens=300, ) print(response.choices[0]) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const response = await openai.chat.completions.create({ model: "gpt-6-astra", messages: [ { role: "user", content: [ { type: "text", text: "What's in this image?" }, { type: "image_url", image_url: { "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", }, } ], }, ], }); console.log(response.choices[0]); } main(); csharp: | using System; using System.Collections.Generic; using OpenAI.Chat; ChatClient client = new( model: "gpt-6-astra", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); List messages = [ new UserChatMessage( [ ChatMessageContentPart.CreateTextPart("What's in this image?"), 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")) ]) ]; ChatCompletion completion = client.CompleteChat(messages); Console.WriteLine(completion.Content[0].Text); response: | { "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG", "object": "chat.completion", "created": 1741570283, "model": "gpt-6-astra", "choices": [ { "index": 0, "message": { "role": "assistant", "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.", "refusal": null, "annotations": [] }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 1117, "completion_tokens": 46, "total_tokens": 1163, "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } }, "service_tier": "default" } - title: Streaming request: curl: | curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-6-astra", "messages": [ { "role": "developer", "content": "You are a helpful assistant." }, { "role": "user", "content": "Hello!" } ], "stream": true }' python: | from openai import OpenAI client = OpenAI() completion = client.chat.completions.create( model="gpt-6-astra", messages=[ {"role": "developer", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ], stream=True ) for chunk in completion: print(chunk.choices[0].delta) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const completion = await openai.chat.completions.create({ model: "gpt-6-astra", messages: [ {"role": "developer", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ], stream: true, }); for await (const chunk of completion) { console.log(chunk.choices[0].delta.content); } } main(); csharp: | using System; using System.ClientModel; using System.Collections.Generic; using System.Threading.Tasks; using OpenAI.Chat; ChatClient client = new( model: "gpt-6-astra", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); List messages = [ new SystemChatMessage("You are a helpful assistant."), new UserChatMessage("Hello!") ]; AsyncCollectionResult completionUpdates = client.CompleteChatStreamingAsync(messages); await foreach (StreamingChatCompletionUpdate completionUpdate in completionUpdates) { if (completionUpdate.ContentUpdate.Count > 0) { Console.Write(completionUpdate.ContentUpdate[0].Text); } } 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}]} data: {"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}]} : Intermediate chat completion chunks omitted. data: {"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"}]} data: [DONE] - title: Functions request: curl: | curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-6-astra", "messages": [ { "role": "user", "content": "What is the weather like in Boston today?" } ], "tools": [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] } } } ], "tool_choice": "auto" }' python: | from openai import OpenAI client = OpenAI() tools = [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, }, "required": ["location"], }, } } ] messages = [{"role": "user", "content": "What's the weather like in Boston today?"}] completion = client.chat.completions.create( model="gpt-6-astra", messages=messages, tools=tools, tool_choice="auto" ) print(completion) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const messages = [{"role": "user", "content": "What's the weather like in Boston today?"}]; const tools = [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA", }, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}, }, "required": ["location"], }, } } ]; const response = await openai.chat.completions.create({ model: "gpt-6-astra", messages: messages, tools: tools, tool_choice: "auto", }); console.log(response); } main(); csharp: | using System; using System.Collections.Generic; using OpenAI.Chat; ChatClient client = new( model: "gpt-6-astra", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ChatTool getCurrentWeatherTool = ChatTool.CreateFunctionTool( functionName: "get_current_weather", functionDescription: "Get the current weather in a given location", functionParameters: BinaryData.FromString(""" { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA" }, "unit": { "type": "string", "enum": [ "celsius", "fahrenheit" ] } }, "required": [ "location" ] } """) ); List messages = [ new UserChatMessage("What's the weather like in Boston today?"), ]; ChatCompletionOptions options = new() { Tools = { getCurrentWeatherTool }, ToolChoice = ChatToolChoice.CreateAutoChoice(), }; ChatCompletion completion = client.CompleteChat(messages, options); response: | { "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1699896916, "model": "gpt-6-astra", "choices": [ { "index": 0, "message": { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "name": "get_current_weather", "arguments": "{\n\"location\": \"Boston, MA\"\n}" } } ] }, "logprobs": null, "finish_reason": "tool_calls" } ], "usage": { "prompt_tokens": 82, "completion_tokens": 17, "total_tokens": 99, "completion_tokens_details": { "reasoning_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } } } - title: Logprobs request: curl: | curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-6-sol", "messages": [ { "role": "user", "content": "Hello!" } ], "reasoning_effort": "none", "logprobs": true, "top_logprobs": 2 }' python: | from openai import OpenAI client = OpenAI() completion = client.chat.completions.create( model="gpt-6-sol", messages=[ {"role": "user", "content": "Hello!"} ], reasoning_effort="none", logprobs=True, top_logprobs=2 ) print(completion.choices[0].message) print(completion.choices[0].logprobs) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const completion = await openai.chat.completions.create({ messages: [{ role: "user", content: "Hello!" }], model: "gpt-6-sol", reasoning_effort: "none", logprobs: true, top_logprobs: 2, }); console.log(completion.choices[0]); } main(); csharp: | using System; using System.Collections.Generic; using OpenAI.Chat; ChatClient client = new( model: "gpt-6-sol", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); List messages = [ new UserChatMessage("Hello!") ]; ChatCompletionOptions options = new() { ReasoningEffortLevel = ChatReasoningEffortLevel.None, IncludeLogProbabilities = true, TopLogProbabilityCount = 2 }; ChatCompletion completion = client.CompleteChat(messages, options); Console.WriteLine(completion.Content[0].Text); response: | { "id": "chatcmpl-123", "object": "chat.completion", "created": 1702685778, "model": "gpt-6-sol", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I assist you today?" }, "logprobs": { "content": [ { "token": "Hello", "logprob": -0.31725305, "bytes": [72, 101, 108, 108, 111], "top_logprobs": [ { "token": "Hello", "logprob": -0.31725305, "bytes": [72, 101, 108, 108, 111] }, { "token": "Hi", "logprob": -1.3190403, "bytes": [72, 105] } ] }, { "token": "!", "logprob": -0.02380986, "bytes": [ 33 ], "top_logprobs": [ { "token": "!", "logprob": -0.02380986, "bytes": [33] }, { "token": " there", "logprob": -3.787621, "bytes": [32, 116, 104, 101, 114, 101] } ] }, { "token": " How", "logprob": -0.000054669687, "bytes": [32, 72, 111, 119], "top_logprobs": [ { "token": " How", "logprob": -0.000054669687, "bytes": [32, 72, 111, 119] }, { "token": "<|end|>", "logprob": -10.953937, "bytes": null } ] }, { "token": " can", "logprob": -0.015801601, "bytes": [32, 99, 97, 110], "top_logprobs": [ { "token": " can", "logprob": -0.015801601, "bytes": [32, 99, 97, 110] }, { "token": " may", "logprob": -4.161023, "bytes": [32, 109, 97, 121] } ] }, { "token": " I", "logprob": -3.7697225e-6, "bytes": [ 32, 73 ], "top_logprobs": [ { "token": " I", "logprob": -3.7697225e-6, "bytes": [32, 73] }, { "token": " assist", "logprob": -13.596657, "bytes": [32, 97, 115, 115, 105, 115, 116] } ] }, { "token": " assist", "logprob": -0.04571125, "bytes": [32, 97, 115, 115, 105, 115, 116], "top_logprobs": [ { "token": " assist", "logprob": -0.04571125, "bytes": [32, 97, 115, 115, 105, 115, 116] }, { "token": " help", "logprob": -3.1089056, "bytes": [32, 104, 101, 108, 112] } ] }, { "token": " you", "logprob": -5.4385737e-6, "bytes": [32, 121, 111, 117], "top_logprobs": [ { "token": " you", "logprob": -5.4385737e-6, "bytes": [32, 121, 111, 117] }, { "token": " today", "logprob": -12.807695, "bytes": [32, 116, 111, 100, 97, 121] } ] }, { "token": " today", "logprob": -0.0040071653, "bytes": [32, 116, 111, 100, 97, 121], "top_logprobs": [ { "token": " today", "logprob": -0.0040071653, "bytes": [32, 116, 111, 100, 97, 121] }, { "token": "?", "logprob": -5.5247097, "bytes": [63] } ] }, { "token": "?", "logprob": -0.0008108172, "bytes": [63], "top_logprobs": [ { "token": "?", "logprob": -0.0008108172, "bytes": [63] }, { "token": "?\n", "logprob": -7.184561, "bytes": [63, 10] } ] } ], "refusal": null }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 9, "completion_tokens": 9, "total_tokens": 18, "completion_tokens_details": { "reasoning_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } } } /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 with the `store` parameter set to `true` will be returned. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() completions = client.chat.completions.list() first_id = completions[0].id first_completion = client.chat.completions.retrieve(completion_id=first_id) print(first_completion) response: | { "object": "chat.completion", "id": "chatcmpl-abc123", "model": "gpt-6-astra", "created": 1738960610, "request_id": "req_ded8ab984ec4bf840f37566c1011c417", "tool_choice": null, "usage": { "total_tokens": 31, "completion_tokens": 18, "prompt_tokens": 13 }, "seed": 4944116822809979520, "top_p": 1.0, "temperature": 1.0, "presence_penalty": 0.0, "frequency_penalty": 0.0, "system_fingerprint": "fp_50cad350e4", "input_user": null, "service_tier": "default", "tools": null, "metadata": {}, "choices": [ { "index": 0, "message": { "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", "role": "assistant", "tool_calls": null, "function_call": null }, "finish_reason": "stop", "logprobs": null } ], "response_format": null } post: operationId: updateChatCompletion tags: - Chat summary: Update chat completion description: | Modify a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` can be modified. Currently, the only supported modification is to update the `metadata` field. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"metadata": {"foo": "bar"}}' python: | from openai import OpenAI client = OpenAI() completions = client.chat.completions.list() first_id = completions[0].id updated_completion = client.chat.completions.update(completion_id=first_id, request_body={"metadata": {"foo": "bar"}}) print(updated_completion) response: | { "object": "chat.completion", "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", "model": "gpt-6-astra", "created": 1738960610, "request_id": "req_ded8ab984ec4bf840f37566c1011c417", "tool_choice": null, "usage": { "total_tokens": 31, "completion_tokens": 18, "prompt_tokens": 13 }, "seed": 4944116822809979520, "top_p": 1.0, "temperature": 1.0, "presence_penalty": 0.0, "frequency_penalty": 0.0, "system_fingerprint": "fp_50cad350e4", "input_user": null, "service_tier": "default", "tools": null, "metadata": { "foo": "bar" }, "choices": [ { "index": 0, "message": { "content": "Mind of circuits hum, \nLearning patterns in silence— \nFuture's quiet spark.", "role": "assistant", "tool_calls": null, "function_call": null }, "finish_reason": "stop", "logprobs": null } ], "response_format": null } delete: operationId: deleteChatCompletion tags: - Chat summary: Delete chat completion description: | Delete a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` can be deleted. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() completions = client.chat.completions.list() first_id = completions[0].id delete_response = client.chat.completions.delete(completion_id=first_id) print(delete_response) response: | { "object": "chat.completion.deleted", "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", "deleted": true } /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 have been created with the `store` parameter set to `true` will be returned. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() completions = client.chat.completions.list() first_id = completions[0].id first_completion = client.chat.completions.retrieve(completion_id=first_id) messages = client.chat.completions.messages.list(completion_id=first_id) print(messages) response: | { "object": "list", "data": [ { "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", "role": "user", "content": "write a haiku about ai", "name": null, "content_parts": null } ], "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0", "has_more": false } /completions: post: operationId: createCompletion tags: - Completions summary: Create completion description: | Creates a completion for the provided prompt and parameters. Returns a completion object, or a sequence of completion objects if the request is streamed. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCompletionRequest' responses: '200': description: OK content: application/json: 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 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-3.5-turbo-instruct", "prompt": "Say this is a test", "max_tokens": 7, "temperature": 0 }' python: | from openai import OpenAI client = OpenAI() client.completions.create( model="gpt-3.5-turbo-instruct", prompt="Say this is a test", max_tokens=7, temperature=0 ) javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const completion = await openai.completions.create({ model: "gpt-3.5-turbo-instruct", prompt: "Say this is a test.", max_tokens: 7, temperature: 0, }); console.log(completion); } main(); response: | { "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", "object": "text_completion", "created": 1589478378, "model": "gpt-3.5-turbo-instruct", "system_fingerprint": "fp_44709d6fcb", "choices": [ { "text": "\n\nThis is indeed a test", "index": 0, "logprobs": null, "finish_reason": "length" } ], "usage": { "prompt_tokens": 5, "completion_tokens": 7, "total_tokens": 12 } } - title: Streaming request: curl: | curl https://api.openai.com/v1/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-3.5-turbo-instruct", "prompt": "Say this is a test", "max_tokens": 7, "temperature": 0, "stream": true }' python: | from openai import OpenAI client = OpenAI() for chunk in client.completions.create( model="gpt-3.5-turbo-instruct", prompt="Say this is a test", max_tokens=7, temperature=0, stream=True ): print(chunk.choices[0].text) javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const stream = await openai.completions.create({ model: "gpt-3.5-turbo-instruct", prompt: "Say this is a test.", stream: true, }); for await (const chunk of stream) { console.log(chunk.choices[0].text) } } main(); response: | { "id": "cmpl-7iA7iJjj8V2zOkCGvWF2hAkDWBQZe", "object": "text_completion", "created": 1690759702, "choices": [ { "text": "This", "index": 0, "logprobs": null, "finish_reason": null } ], "model": "gpt-3.5-turbo-instruct", "system_fingerprint": "fp_44709d6fcb" } /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. required: false schema: type: integer default: 20 - name: order in: query description: | Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. schema: type: string default: desc enum: - asc - desc - name: after in: query description: | A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. schema: type: string - name: 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" response: | { "object": "list", "data": [ { "id": "cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863", "object": "container", "created_at": 1747844794, "status": "running", "expires_after": { "anchor": "last_active_at", "minutes": 20 }, "last_active_at": 1747844794, "memory_limit": "4g", "name": "My Container" } ], "first_id": "container_123", "last_id": "container_123", "has_more": false } 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "My Container", "memory_limit": "4g", "skills": [ { "type": "skill_reference", "skill_id": "skill_4db6f1a2c9e73508b41f9da06e2c7b5f" }, { "type": "skill_reference", "skill_id": "openai-spreadsheets", "version": "latest" } ], "network_policy": { "type": "allowlist", "allowed_domains": ["api.buildkite.com"] } }' response: | { "id": "cntr_682e30645a488191b6363a0cbefc0f0a025ec61b66250591", "object": "container", "created_at": 1747857508, "status": "running", "expires_after": { "anchor": "last_active_at", "minutes": 20 }, "last_active_at": 1747857508, "network_policy": { "type": "allowlist", "allowed_domains": ["api.buildkite.com"] }, "memory_limit": "4g", "name": "My Container" } /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" response: | { "id": "cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863", "object": "container", "created_at": 1747844794, "status": "running", "expires_after": { "anchor": "last_active_at", "minutes": 20 }, "last_active_at": 1747844794, "memory_limit": "4g", "name": "My Container" } 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 '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 \ -H "Authorization: Bearer $OPENAI_API_KEY" response: | { "id": "cntr_682dfebaacac8198bbfe9c2474fb6f4a085685cbe3cb5863", "object": "container.deleted", "deleted": true } /containers/{container_id}/files: post: summary: Create container file description: | Create a Container File You can send either a multipart/form-data request with the raw file content, or a JSON request with a file ID. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F file="@example.txt" response: | { "id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "object": "container.file", "created_at": 1747848842, "bytes": 880, "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04", "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json", "source": "user" } 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. required: false schema: type: integer default: 20 - name: order in: query description: | Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. schema: type: string default: desc enum: - asc - desc - name: after in: query description: | A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. schema: type: string 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" response: | { "object": "list", "data": [ { "id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "object": "container.file", "created_at": 1747848842, "bytes": 880, "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04", "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json", "source": "user" } ], "first_id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "has_more": false, "last_id": "cfile_682e0e8a43c88191a7978f477a09bdf5" } /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" response: | { "id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "object": "container.file", "created_at": 1747848842, "bytes": 880, "container_id": "cntr_682e0e7318108198aa783fd921ff305e08e78805b9fdbb04", "path": "/mnt/data/88e12fa445d32636f190a0b33daed6cb-tsconfig.json", "source": "user" } 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 '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 \ -H "Authorization: Bearer $OPENAI_API_KEY" response: | { "id": "cfile_682e0e8a43c88191a7978f477a09bdf5", "object": "container.file.deleted", "deleted": true } /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 '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 \ -H "Authorization: Bearer $OPENAI_API_KEY" response: | /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` parameter 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. 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. 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 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "items": [ { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "Hello!"} ] }, { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "How are you?"} ] } ] }' javascript: | import OpenAI from "openai"; const client = new OpenAI(); const items = await client.conversations.items.create( "conv_123", { items: [ { type: "message", role: "user", content: [{ type: "input_text", text: "Hello!" }], }, { type: "message", role: "user", content: [{ type: "input_text", text: "How are you?" }], }, ], } ); console.log(items.data); python: | from openai import OpenAI client = OpenAI() items = client.conversations.items.create( "conv_123", items=[ { "type": "message", "role": "user", "content": [{"type": "input_text", "text": "Hello!"}], }, { "type": "message", "role": "user", "content": [{"type": "input_text", "text": "How are you?"}], } ], ) print(items.data) csharp: | using System; using System.Collections.Generic; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ConversationItemList created = client.ConversationItems.Create( conversationId: "conv_123", new CreateConversationItemsOptions { Items = new List { new ConversationMessage { Role = "user", Content = { new ConversationInputText { Text = "Hello!" } } }, new ConversationMessage { Role = "user", Content = { new ConversationInputText { Text = "How are you?" } } } } } ); Console.WriteLine(created.Data.Count); response: | { "object": "list", "data": [ { "type": "message", "id": "msg_abc", "status": "completed", "role": "user", "content": [ {"type": "input_text", "text": "Hello!"} ] }, { "type": "message", "id": "msg_def", "status": "completed", "role": "user", "content": [ {"type": "input_text", "text": "How are you?"} ] } ], "first_id": "msg_abc", "last_id": "msg_def", "has_more": false } 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 1 and 100, and the default is 20. 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`. - `asc`: Return the input items in ascending order. - `desc`: Return the input items in descending order. - in: query name: after schema: type: string description: | An item ID to list items after, used in pagination. - 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: - `web_search_call.action.sources`: Include the sources of the web search tool call. - `code_interpreter_call.outputs`: Includes the outputs of python code execution in code interpreter tool call items. - `computer_call_output.output.image_url`: Include image urls from the computer call output. - `file_search_call.results`: Include the search results of the file search tool call. - `message.input_image.image_url`: Include image urls from the input message. - `message.output_text.logprobs`: Include logprobs with assistant messages. - `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" \ -H "Authorization: Bearer $OPENAI_API_KEY" javascript: | import OpenAI from "openai"; const client = new OpenAI(); const items = await client.conversations.items.list("conv_123", { limit: 10 }); console.log(items.data); python: | from openai import OpenAI client = OpenAI() items = client.conversations.items.list("conv_123", limit=10) print(items.data) csharp: | using System; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ConversationItemList items = client.ConversationItems.List( conversationId: "conv_123", new ListConversationItemsOptions { Limit = 10 } ); Console.WriteLine(items.Data.Count); response: | { "object": "list", "data": [ { "type": "message", "id": "msg_abc", "status": "completed", "role": "user", "content": [ {"type": "input_text", "text": "Hello!"} ] } ], "first_id": "msg_abc", "last_id": "msg_abc", "has_more": false } /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` parameter 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. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" javascript: | import OpenAI from "openai"; const client = new OpenAI(); const item = await client.conversations.items.retrieve( "conv_123", "msg_abc" ); console.log(item); python: | from openai import OpenAI client = OpenAI() item = client.conversations.items.retrieve("conv_123", "msg_abc") print(item) csharp: | using System; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ConversationItem item = client.ConversationItems.Get( conversationId: "conv_123", itemId: "msg_abc" ); Console.WriteLine(item.Id); response: | { "type": "message", "id": "msg_abc", "status": "completed", "role": "user", "content": [ {"type": "input_text", "text": "Hello!"} ] } 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" javascript: | import OpenAI from "openai"; const client = new OpenAI(); const conversation = await client.conversations.items.delete( "conv_123", "msg_abc" ); console.log(conversation); python: | from openai import OpenAI client = OpenAI() conversation = client.conversations.items.delete("conv_123", "msg_abc") print(conversation) csharp: | using System; using OpenAI.Conversations; OpenAIConversationClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); Conversation conversation = client.ConversationItems.Delete( conversationId: "conv_123", itemId: "msg_abc" ); Console.WriteLine(conversation.Id); response: | { "id": "conv_123", "object": "conversation", "created_at": 1741900000, "metadata": {"topic": "demo"} } /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": "Hello world", "model": "text-embedding-3-small", "encoding_format": "float", "dimensions": 3 }' python: | from openai import OpenAI client = OpenAI() client.embeddings.create( model="text-embedding-3-small", input="Hello world", encoding_format="float", dimensions=3 ) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const embedding = await openai.embeddings.create({ model: "text-embedding-3-small", input: "Hello world", encoding_format: "float", dimensions: 3, }); console.log(embedding); } main(); csharp: | using System; using OpenAI.Embeddings; EmbeddingClient client = new( model: "text-embedding-3-small", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); EmbeddingGenerationOptions options = new() { Dimensions = 3 }; OpenAIEmbedding embedding = client.GenerateEmbedding(input: "Hello world", options: options); ReadOnlyMemory vector = embedding.ToFloats(); for (int i = 0; i < vector.Length; i++) { Console.WriteLine($" [{i,4}] = {vector.Span[i]}"); } response: | { "object": "list", "data": [ { "object": "embedding", "embedding": [ 0.26726124, 0.53452248, 0.80178373 ], "index": 0 } ], "model": "text-embedding-3-small", "usage": { "prompt_tokens": 2, "total_tokens": 2 } } /evals: get: operationId: listEvals tags: - Evals summary: List evals description: | List evaluations for a project. 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 `created_at` for creation time or `updated_at` for last updated time. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() evals = client.evals.list(limit=1) print(evals) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const evals = await openai.evals.list({ limit: 1 }); console.log(evals); response: | { "object": "list", "data": [ { "id": "eval_67abd54d9b0081909a86353f6fb9317a", "object": "eval", "data_source_config": { "type": "stored_completions", "metadata": { "usecase": "push_notifications_summarizer" }, "schema": { "type": "object", "properties": { "item": { "type": "object" }, "sample": { "type": "object" } }, "required": [ "item", "sample" ] } }, "testing_criteria": [ { "name": "Push Notification Summary Grader", "id": "Push Notification Summary Grader-9b876f24-4762-4be9-aff4-db7a9b31c673", "type": "label_model", "model": "o3-mini", "input": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "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" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "\nPush notifications: {{item.input}}\nSummary: {{sample.output_text}}\n" } } ], "passing_labels": [ "correct" ], "labels": [ "correct", "incorrect" ], "sampling_params": null } ], "name": "Push Notification Summary Grader", "created_at": 1739314509, "metadata": { "description": "A stored completions eval for push notification summaries" } } ], "first_id": "eval_67abd54d9b0081909a86353f6fb9317a", "last_id": "eval_67aa884cf6688190b58f657d4441c8b7", "has_more": true } 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. An 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. For more information, see the [Evals guide](https://developers.openai.com/api/docs/guides/evals). 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Sentiment", "data_source_config": { "type": "stored_completions", "metadata": { "usecase": "chatbot" } }, "testing_criteria": [ { "type": "label_model", "model": "o3-mini", "input": [ { "role": "developer", "content": "Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'" }, { "role": "user", "content": "Statement: {{item.input}}" } ], "passing_labels": [ "positive" ], "labels": [ "positive", "neutral", "negative" ], "name": "Example label grader" } ] }' python: | from openai import OpenAI client = OpenAI() eval_obj = client.evals.create( name="Sentiment", data_source_config={ "type": "stored_completions", "metadata": {"usecase": "chatbot"} }, testing_criteria=[ { "type": "label_model", "model": "o3-mini", "input": [ {"role": "developer", "content": "Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'"}, {"role": "user", "content": "Statement: {{item.input}}"} ], "passing_labels": ["positive"], "labels": ["positive", "neutral", "negative"], "name": "Example label grader" } ] ) print(eval_obj) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const evalObj = await openai.evals.create({ name: "Sentiment", data_source_config: { type: "stored_completions", metadata: { usecase: "chatbot" } }, testing_criteria: [ { type: "label_model", model: "o3-mini", input: [ { role: "developer", content: "Classify the sentiment of the following statement as one of 'positive', 'neutral', or 'negative'" }, { role: "user", content: "Statement: {{item.input}}" } ], passing_labels: ["positive"], labels: ["positive", "neutral", "negative"], name: "Example label grader" } ] }); console.log(evalObj); response: | { "object": "eval", "id": "eval_67b7fa9a81a88190ab4aa417e397ea21", "data_source_config": { "type": "stored_completions", "metadata": { "usecase": "chatbot" }, "schema": { "type": "object", "properties": { "item": { "type": "object" }, "sample": { "type": "object" } }, "required": [ "item", "sample" ] } }, "testing_criteria": [ { "name": "Example label grader", "type": "label_model", "model": "o3-mini", "input": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "text": "Classify the sentiment of the following statement as one of positive, neutral, or negative" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "Statement: {{item.input}}" } } ], "passing_labels": [ "positive" ], "labels": [ "positive", "neutral", "negative" ] } ], "name": "Sentiment", "created_at": 1740110490, "metadata": { "description": "An eval for sentiment analysis" } } /evals/{eval_id}: get: operationId: getEval tags: - Evals summary: Get an eval description: | Get an evaluation by ID. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() eval_obj = client.evals.retrieve("eval_67abd54d9b0081909a86353f6fb9317a") print(eval_obj) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const evalObj = await openai.evals.retrieve("eval_67abd54d9b0081909a86353f6fb9317a"); console.log(evalObj); response: | { "object": "eval", "id": "eval_67abd54d9b0081909a86353f6fb9317a", "data_source_config": { "type": "custom", "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "input": { "type": "string" }, "ground_truth": { "type": "string" } }, "required": [ "input", "ground_truth" ] } }, "required": [ "item" ] } }, "testing_criteria": [ { "name": "String check", "id": "String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2", "type": "string_check", "input": "{{item.input}}", "reference": "{{item.ground_truth}}", "operation": "eq" } ], "name": "External Data Eval", "created_at": 1739314509, "metadata": {} } post: operationId: updateEval tags: - Evals summary: Update an eval description: | Update certain properties of an evaluation. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Updated Eval", "metadata": {"description": "Updated description"}}' python: | from openai import OpenAI client = OpenAI() updated_eval = client.evals.update( "eval_67abd54d9b0081909a86353f6fb9317a", name="Updated Eval", metadata={"description": "Updated description"} ) print(updated_eval) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const updatedEval = await openai.evals.update( "eval_67abd54d9b0081909a86353f6fb9317a", { name: "Updated Eval", metadata: { description: "Updated description" } } ); console.log(updatedEval); response: | { "object": "eval", "id": "eval_67abd54d9b0081909a86353f6fb9317a", "data_source_config": { "type": "custom", "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "input": { "type": "string" }, "ground_truth": { "type": "string" } }, "required": [ "input", "ground_truth" ] } }, "required": [ "item" ] } }, "testing_criteria": [ { "name": "String check", "id": "String check-2eaf2d8d-d649-4335-8148-9535a7ca73c2", "type": "string_check", "input": "{{item.input}}", "reference": "{{item.ground_truth}}", "operation": "eq" } ], "name": "Updated Eval", "created_at": 1739314509, "metadata": {"description": "Updated description"} } delete: operationId: deleteEval tags: - Evals summary: Delete an eval description: | Delete an evaluation. 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 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() deleted = client.evals.delete("eval_abc123") print(deleted) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const deleted = await openai.evals.delete("eval_abc123"); console.log(deleted); response: | { "object": "eval.deleted", "deleted": true, "eval_id": "eval_abc123" } /evals/{eval_id}/runs: get: operationId: getEvalRuns tags: - Evals summary: Get eval runs description: | Get a list of runs for an evaluation. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() runs = client.evals.runs.list("egroup_67abd54d9b0081909a86353f6fb9317a") print(runs) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const runs = await openai.evals.runs.list("egroup_67abd54d9b0081909a86353f6fb9317a"); console.log(runs); response: | { "object": "list", "data": [ { "object": "eval.run", "id": "evalrun_67e0c7d31560819090d60c0780591042", "eval_id": "eval_67e0c726d560819083f19a957c4c640b", "report_url": "https://platform.openai.com/evaluations/eval_67e0c726d560819083f19a957c4c640b", "status": "completed", "model": "o3-mini", "name": "bulk_with_negative_examples_o3-mini", "created_at": 1742784467, "result_counts": { "total": 1, "errored": 0, "failed": 0, "passed": 1 }, "per_model_usage": [ { "model_name": "o3-mini", "invocation_count": 1, "prompt_tokens": 563, "completion_tokens": 874, "total_tokens": 1437, "cached_tokens": 0 } ], "per_testing_criteria_results": [ { "testing_criteria": "Push Notification Summary Grader-1808cd0b-eeec-4e0b-a519-337e79f4f5d1", "passed": 1, "failed": 0 } ], "data_source": { "type": "completions", "source": { "type": "file_content", "content": [ { "item": { "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" } } ] }, "input_messages": { "type": "template", "template": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "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" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "{{item.notifications}}" } } ] }, "model": "o3-mini" }, "error": null, "metadata": {} } ], "first_id": "evalrun_67e0c7d31560819090d60c0780591042", "last_id": "evalrun_67e0c7d31560819090d60c0780591042", "has_more": true } 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. 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 \ -X POST \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -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"}}]}}}' python: | from openai import OpenAI client = OpenAI() run = client.evals.runs.create( "eval_67e579652b548190aaa83ada4b125f47", 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" } } ] } } ) print(run) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const run = await openai.evals.runs.create( "eval_67e579652b548190aaa83ada4b125f47", { 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" } } ] } } } ); console.log(run); response: | { "object": "eval.run", "id": "evalrun_67e57965b480819094274e3a32235e4c", "eval_id": "eval_67e579652b548190aaa83ada4b125f47", "report_url": "https://platform.openai.com/evaluations/eval_67e579652b548190aaa83ada4b125f47&run_id=evalrun_67e57965b480819094274e3a32235e4c", "status": "queued", "model": "gpt-6-astra", "name": "gpt-6-astra", "created_at": 1743092069, "result_counts": { "total": 0, "errored": 0, "failed": 0, "passed": 0 }, "per_model_usage": null, "per_testing_criteria_results": null, "data_source": { "type": "completions", "source": { "type": "file_content", "content": [ { "item": { "input": "Tech Company Launches Advanced Artificial Intelligence Platform", "ground_truth": "Technology" } } ] }, "input_messages": { "type": "template", "template": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "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" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "{{item.input}}" } } ] }, "model": "gpt-6-astra", "sampling_params": { "max_completions_tokens": 2048 } }, "error": null, "metadata": {} } /evals/{eval_id}/runs/{run_id}: get: operationId: getEvalRun tags: - Evals summary: Get an eval run description: | Get an evaluation run by ID. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() run = client.evals.runs.retrieve( "eval_67abd54d9b0081909a86353f6fb9317a", "evalrun_67abd54d60ec8190832b46859da808f7" ) print(run) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const run = await openai.evals.runs.retrieve( "evalrun_67abd54d60ec8190832b46859da808f7", { eval_id: "eval_67abd54d9b0081909a86353f6fb9317a" } ); console.log(run); response: | { "object": "eval.run", "id": "evalrun_67abd54d60ec8190832b46859da808f7", "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", "report_url": "https://platform.openai.com/evaluations/eval_67abd54d9b0081909a86353f6fb9317a?run_id=evalrun_67abd54d60ec8190832b46859da808f7", "status": "queued", "model": "gpt-6-astra", "name": "gpt-6-astra", "created_at": 1743092069, "result_counts": { "total": 0, "errored": 0, "failed": 0, "passed": 0 }, "per_model_usage": null, "per_testing_criteria_results": null, "data_source": { "type": "completions", "source": { "type": "file_content", "content": [ { "item": { "input": "Tech Company Launches Advanced Artificial Intelligence Platform", "ground_truth": "Technology" } }, { "item": { "input": "Central Bank Increases Interest Rates Amid Inflation Concerns", "ground_truth": "Markets" } }, { "item": { "input": "International Summit Addresses Climate Change Strategies", "ground_truth": "World" } }, { "item": { "input": "Major Retailer Reports Record-Breaking Holiday Sales", "ground_truth": "Business" } }, { "item": { "input": "National Team Qualifies for World Championship Finals", "ground_truth": "Sports" } }, { "item": { "input": "Stock Markets Rally After Positive Economic Data Released", "ground_truth": "Markets" } }, { "item": { "input": "Global Manufacturer Announces Merger with Competitor", "ground_truth": "Business" } }, { "item": { "input": "Breakthrough in Renewable Energy Technology Unveiled", "ground_truth": "Technology" } }, { "item": { "input": "World Leaders Sign Historic Climate Agreement", "ground_truth": "World" } }, { "item": { "input": "Professional Athlete Sets New Record in Championship Event", "ground_truth": "Sports" } }, { "item": { "input": "Financial Institutions Adapt to New Regulatory Requirements", "ground_truth": "Business" } }, { "item": { "input": "Tech Conference Showcases Advances in Artificial Intelligence", "ground_truth": "Technology" } }, { "item": { "input": "Global Markets Respond to Oil Price Fluctuations", "ground_truth": "Markets" } }, { "item": { "input": "International Cooperation Strengthened Through New Treaty", "ground_truth": "World" } }, { "item": { "input": "Sports League Announces Revised Schedule for Upcoming Season", "ground_truth": "Sports" } } ] }, "input_messages": { "type": "template", "template": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "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" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "{{item.input}}" } } ] }, "model": "gpt-6-astra", "sampling_params": { "max_completions_tokens": 2048 } }, "error": null, "metadata": {} } delete: operationId: deleteEvalRun tags: - Evals summary: Delete eval run description: | Delete an eval run. 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 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() deleted = client.evals.runs.delete( "eval_123abc", "evalrun_abc456" ) print(deleted) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const deleted = await openai.evals.runs.delete( "eval_123abc", "evalrun_abc456" ); console.log(deleted); response: | { "object": "eval.run.deleted", "deleted": true, "run_id": "evalrun_abc456" } /evals/{eval_id}/runs/{run_id}/cancel: post: operationId: cancelEvalRun tags: - Evals summary: Cancel eval run description: | Cancel an ongoing evaluation run. 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 \ -X POST \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() canceled_run = client.evals.runs.cancel( "evalrun_67abd54d60ec8190832b46859da808f7", eval_id="eval_67abd54d9b0081909a86353f6fb9317a" ) print(canceled_run) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const canceledRun = await openai.evals.runs.cancel( "evalrun_67abd54d60ec8190832b46859da808f7", { eval_id: "eval_67abd54d9b0081909a86353f6fb9317a" } ); console.log(canceledRun); response: | { "object": "eval.run", "id": "evalrun_67abd54d60ec8190832b46859da808f7", "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", "report_url": "https://platform.openai.com/evaluations/eval_67abd54d9b0081909a86353f6fb9317a?run_id=evalrun_67abd54d60ec8190832b46859da808f7", "status": "canceled", "model": "gpt-6-astra", "name": "gpt-6-astra", "created_at": 1743092069, "result_counts": { "total": 0, "errored": 0, "failed": 0, "passed": 0 }, "per_model_usage": null, "per_testing_criteria_results": null, "data_source": { "type": "completions", "source": { "type": "file_content", "content": [ { "item": { "input": "Tech Company Launches Advanced Artificial Intelligence Platform", "ground_truth": "Technology" } }, { "item": { "input": "Central Bank Increases Interest Rates Amid Inflation Concerns", "ground_truth": "Markets" } }, { "item": { "input": "International Summit Addresses Climate Change Strategies", "ground_truth": "World" } }, { "item": { "input": "Major Retailer Reports Record-Breaking Holiday Sales", "ground_truth": "Business" } }, { "item": { "input": "National Team Qualifies for World Championship Finals", "ground_truth": "Sports" } }, { "item": { "input": "Stock Markets Rally After Positive Economic Data Released", "ground_truth": "Markets" } }, { "item": { "input": "Global Manufacturer Announces Merger with Competitor", "ground_truth": "Business" } }, { "item": { "input": "Breakthrough in Renewable Energy Technology Unveiled", "ground_truth": "Technology" } }, { "item": { "input": "World Leaders Sign Historic Climate Agreement", "ground_truth": "World" } }, { "item": { "input": "Professional Athlete Sets New Record in Championship Event", "ground_truth": "Sports" } }, { "item": { "input": "Financial Institutions Adapt to New Regulatory Requirements", "ground_truth": "Business" } }, { "item": { "input": "Tech Conference Showcases Advances in Artificial Intelligence", "ground_truth": "Technology" } }, { "item": { "input": "Global Markets Respond to Oil Price Fluctuations", "ground_truth": "Markets" } }, { "item": { "input": "International Cooperation Strengthened Through New Treaty", "ground_truth": "World" } }, { "item": { "input": "Sports League Announces Revised Schedule for Upcoming Season", "ground_truth": "Sports" } } ] }, "input_messages": { "type": "template", "template": [ { "type": "message", "role": "developer", "content": { "type": "input_text", "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" } }, { "type": "message", "role": "user", "content": { "type": "input_text", "text": "{{item.input}}" } } ] }, "model": "gpt-6-astra", "sampling_params": { "max_completions_tokens": 2048 } }, "error": null, "metadata": {} } /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. 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 items or `pass` to filter by passed output items. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() output_items = client.evals.runs.output_items.list( "egroup_67abd54d9b0081909a86353f6fb9317a", "erun_67abd54d60ec8190832b46859da808f7" ) print(output_items) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const outputItems = await openai.evals.runs.outputItems.list( "egroup_67abd54d9b0081909a86353f6fb9317a", "erun_67abd54d60ec8190832b46859da808f7" ); console.log(outputItems); response: | { "object": "list", "data": [ { "object": "eval.run.output_item", "id": "outputitem_67e5796c28e081909917bf79f6e6214d", "created_at": 1743092076, "run_id": "evalrun_67abd54d60ec8190832b46859da808f7", "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", "status": "pass", "datasource_item_id": 5, "datasource_item": { "input": "Stock Markets Rally After Positive Economic Data Released", "ground_truth": "Markets" }, "results": [ { "name": "String check-a2486074-d803-4445-b431-ad2262e85d47", "sample": null, "passed": true, "score": 1.0 } ], "sample": { "input": [ { "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", "tool_call_id": null, "tool_calls": null, "function_call": null }, { "role": "user", "content": "Stock Markets Rally After Positive Economic Data Released", "tool_call_id": null, "tool_calls": null, "function_call": null } ], "output": [ { "role": "assistant", "content": "Markets", "tool_call_id": null, "tool_calls": null, "function_call": null } ], "finish_reason": "stop", "model": "gpt-6-astra", "usage": { "total_tokens": 325, "completion_tokens": 2, "prompt_tokens": 323, "cached_tokens": 0 }, "error": null, "temperature": 1.0, "max_completion_tokens": 2048, "top_p": 1.0, "seed": 42 } } ], "first_id": "outputitem_67e5796c28e081909917bf79f6e6214d", "last_id": "outputitem_67e5796c28e081909917bf79f6e6214d", "has_more": true } /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. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" python: | from openai import OpenAI client = OpenAI() output_item = client.evals.runs.output_items.retrieve( "eval_67abd54d9b0081909a86353f6fb9317a", "evalrun_67abd54d60ec8190832b46859da808f7", "outputitem_67abd55eb6548190bb580745d5644a33" ) print(output_item) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const outputItem = await openai.evals.runs.outputItems.retrieve( "outputitem_67abd55eb6548190bb580745d5644a33", { eval_id: "eval_67abd54d9b0081909a86353f6fb9317a", run_id: "evalrun_67abd54d60ec8190832b46859da808f7", } ); console.log(outputItem); response: | { "object": "eval.run.output_item", "id": "outputitem_67e5796c28e081909917bf79f6e6214d", "created_at": 1743092076, "run_id": "evalrun_67abd54d60ec8190832b46859da808f7", "eval_id": "eval_67abd54d9b0081909a86353f6fb9317a", "status": "pass", "datasource_item_id": 5, "datasource_item": { "input": "Stock Markets Rally After Positive Economic Data Released", "ground_truth": "Markets" }, "results": [ { "name": "String check-a2486074-d803-4445-b431-ad2262e85d47", "sample": null, "passed": true, "score": 1.0 } ], "sample": { "input": [ { "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", "tool_call_id": null, "tool_calls": null, "function_call": null }, { "role": "user", "content": "Stock Markets Rally After Positive Economic Data Released", "tool_call_id": null, "tool_calls": null, "function_call": null } ], "output": [ { "role": "assistant", "content": "Markets", "tool_call_id": null, "tool_calls": null, "function_call": null } ], "finish_reason": "stop", "model": "gpt-6-astra", "usage": { "total_tokens": 325, "completion_tokens": 2, "prompt_tokens": 323, "cached_tokens": 0 }, "error": null, "temperature": 1.0, "max_completion_tokens": 2048, "top_p": 1.0, "seed": 42 } } /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. 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. schema: type: string default: desc enum: - asc - desc - name: after in: query description: | A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. schema: type: string 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.files.list() javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const list = await openai.files.list(); for await (const file of list) { console.log(file); } } main(); response: | { "object": "list", "data": [ { "id": "file-abc123", "object": "file", "bytes": 175, "created_at": 1613677385, "expires_at": 1677614202, "filename": "salesOverview.pdf", "purpose": "assistants", "status": "processed" }, { "id": "file-abc456", "object": "file", "bytes": 140, "created_at": 1613779121, "expires_at": 1677614202, "filename": "puppy.jsonl", "purpose": "fine-tune", "status": "processed" } ], "first_id": "file-abc123", "last_id": "file-abc456", "has_more": false } post: operationId: createFile tags: - Files summary: Upload file description: | Upload a file that can be used across various endpoints. Individual files can be up to 512 MB, and each project can store up to 2.5 TB of files in total. There is no organization-wide storage limit. Uploads to this endpoint are rate-limited to 1,000 requests per minute per authenticated user. - The Assistants API supports files up to 2 million tokens and of specific file types. See the [Assistants Tools guide](https://developers.openai.com/api/docs/guides/tools) for details. - The Fine-tuning API only supports `.jsonl` files. The input also has certain required formats for fine-tuning [chat](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#formatting-your-data) or [completions](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#formatting-your-data) models. - The Batch API only supports `.jsonl` files up to 200 MB in size. The input also has a specific required [format](https://developers.openai.com/api/docs/guides/batch#1-prepare-your-batch-file). - For Retrieval or `file_search` ingestion, upload files here first. If you need to attach multiple uploaded files to the same vector store, use [`/vector_stores/{vector_store_id}/file_batches`](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create) instead of attaching them one by one. Vector store attachment has separate limits from file upload, including 2,000 attached files per minute per organization. Please [contact us](https://help.openai.com/) if you need to increase these storage limits. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F purpose="fine-tune" \ -F file="@mydata.jsonl" \ -F 'expires_after[anchor]=created_at' \ -F 'expires_after[seconds]=2592000' python: | from openai import OpenAI client = OpenAI() client.files.create( file=open("mydata.jsonl", "rb"), purpose="fine-tune", expires_after={ "anchor": "created_at", "seconds": 2592000 } ) javascript: |- import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const file = await openai.files.create({ file: fs.createReadStream("mydata.jsonl"), purpose: "fine-tune", expires_after: { anchor: "created_at", seconds: 2592000 } }); console.log(file); } main(); response: | { "id": "file-abc123", "object": "file", "bytes": 120000, "created_at": 1677610602, "expires_at": 1680202602, "filename": "mydata.jsonl", "purpose": "fine-tune", "status": "processed" } /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 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.files.delete("file-abc123") javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const file = await openai.files.delete("file-abc123"); console.log(file); } main(); response: | { "id": "file-abc123", "object": "file", "deleted": true } 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.files.retrieve("file-abc123") javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const file = await openai.files.retrieve("file-abc123"); console.log(file); } main(); response: | { "id": "file-abc123", "object": "file", "bytes": 120000, "created_at": 1677610602, "expires_at": 1680202602, "filename": "mydata.jsonl", "purpose": "fine-tune", "status": "processed" } /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonl python: | from openai import OpenAI client = OpenAI() content = client.files.content("file-abc123") javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const response = await openai.files.content("file-abc123"); const content = await response.text(); console.log(content); } main(); /fine_tuning/alpha/graders/run: post: operationId: runGrader tags: - Fine-tuning summary: Run grader description: | Run a grader. 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 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "grader": { "type": "score_model", "name": "Example score model grader", "input": [ { "role": "user", "content": [ { "type": "input_text", "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}}" } ] } ], "model": "gpt-5-mini", "sampling_params": { "temperature": 1, "top_p": 1, "seed": 42 } }, "item": { "reference_answer": "fuzzy wuzzy was a bear" }, "model_sample": "fuzzy wuzzy was a bear" }' python: | from openai import OpenAI client = OpenAI() result = client.fine_tuning.alpha.graders.run( grader={ "type": "score_model", "name": "Example score model grader", "input": [ { "role": "user", "content": [ { "type": "input_text", "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}}", } ], } ], "model": "gpt-5-mini", "sampling_params": {"temperature": 1, "top_p": 1, "seed": 42}, }, item={"reference_answer": "fuzzy wuzzy was a bear"}, model_sample="fuzzy wuzzy was a bear", ) print(result) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const result = await openai.fineTuning.alpha.graders.run({ grader: { type: "score_model", name: "Example score model grader", input: [ { role: "user", content: [ { type: "input_text", 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}}", }, ], }, ], model: "gpt-5-mini", sampling_params: { temperature: 1, top_p: 1, seed: 42 }, }, item: { reference_answer: "fuzzy wuzzy was a bear" }, model_sample: "fuzzy wuzzy was a bear", }); console.log(result); response: | { "reward": 1.0, "metadata": { "name": "Example score model grader", "type": "score_model", "errors": { "formula_parse_error": false, "sample_parse_error": false, "truncated_observation_error": false, "unresponsive_reward_error": false, "invalid_variable_error": false, "other_error": false, "python_grader_server_error": false, "python_grader_server_error_type": null, "python_grader_runtime_error": false, "python_grader_runtime_error_details": null, "model_grader_server_error": false, "model_grader_refusal_error": false, "model_grader_parse_error": false, "model_grader_server_error_details": null }, "execution_time": 4.365238428115845, "scores": {}, "token_usage": { "prompt_tokens": 190, "total_tokens": 324, "completion_tokens": 134, "cached_tokens": 0 }, "sampled_model_name": "gpt-5-mini" }, "sub_rewards": {}, "model_grader_token_usage_per_model": { "gpt-5-mini": { "prompt_tokens": 190, "total_tokens": 324, "completion_tokens": 134, "cached_tokens": 0 } } } - title: Score an image caption request: curl: | curl -X POST https://api.openai.com/v1/fine_tuning/alpha/graders/run \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "grader": { "type": "score_model", "name": "Image caption grader", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "Score how well the provided caption matches the image on a 0-1 scale. Only return the score.\n\nCaption: {{sample.output_text}}" }, { "type": "input_image", "image_url": "https://example.com/dog-catching-ball.png", "file_id": null, "detail": "high" } ] } ], "model": "gpt-5-mini", "sampling_params": { "temperature": 0.2 } }, "item": { "expected_caption": "A golden retriever jumps to catch a tennis ball" }, "model_sample": "A dog leaps to grab a tennis ball mid-air" }' - title: Score an audio response request: curl: | curl -X POST https://api.openai.com/v1/fine_tuning/alpha/graders/run \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "grader": { "type": "score_model", "name": "Audio clarity grader", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "Listen to the clip and return a confidence score from 0 to 1 that the speaker said: {{item.target_phrase}}" }, { "type": "input_audio", "input_audio": { "data": "{{item.audio_clip_b64}}", "format": "mp3" } } ] } ], "model": "gpt-audio", "sampling_params": { "temperature": 0.2, "top_p": 1, "seed": 123 } }, "item": { "target_phrase": "Please deliver the package on Tuesday", "audio_clip_b64": "" }, "model_sample": "Please deliver the package on Tuesday" }' /fine_tuning/alpha/graders/validate: post: operationId: validateGrader tags: - Fine-tuning summary: Validate grader description: | Validate a grader. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "grader": { "type": "string_check", "name": "Example string check grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "operation": "eq" } }' response: | { "grader": { "type": "string_check", "name": "Example string check grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "operation": "eq" } } /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). Organization owners can use this endpoint to view all permissions for a fine-tuned model checkpoint. 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. - 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" response: | { "object": "list", "data": [ { "object": "checkpoint.permission", "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "created_at": 1721764867, "project_id": "proj_abGMw1llN8IrBb6SvvY5A1iH" }, { "object": "checkpoint.permission", "id": "cp_enQCFmOTGj3syEpYVhBRLTSy", "created_at": 1721764800, "project_id": "proj_iqGMw1llN8IrBb6SvvY5A1oF" } ], "first_id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "last_id": "cp_enQCFmOTGj3syEpYVhBRLTSy", "has_more": false } 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). This enables organization owners to share fine-tuned models with other projects in their organization. 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. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" -d '{"project_ids": ["proj_abGMw1llN8IrBb6SvvY5A1iH"]}' response: | { "object": "list", "data": [ { "object": "checkpoint.permission", "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "created_at": 1721764867, "project_id": "proj_abGMw1llN8IrBb6SvvY5A1iH" } ], "first_id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "last_id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "has_more": false } /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). Organization owners can use this endpoint to delete a permission for a fine-tuned model checkpoint. 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. - 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. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" response: | { "object": "checkpoint.permission", "id": "cp_zc4Q7MP6XxulcVzj4MZdwsAB", "deleted": true } /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. Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete. [Learn more about fine-tuning](https://developers.openai.com/api/docs/guides/model-optimization) 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 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-BK7bzQj3FfZFXr7DbL6xJwfo", "model": "gpt-4o-mini" }' python: | from openai import OpenAI client = OpenAI() client.fine_tuning.jobs.create( training_file="file-abc123", model="gpt-4o-mini" ) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const fineTune = await openai.fineTuning.jobs.create({ training_file: "file-abc123" }); console.log(fineTune); } main(); - title: Epochs request: curl: | curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc123", "model": "gpt-4o-mini", "method": { "type": "supervised", "supervised": { "hyperparameters": { "n_epochs": 2 } } } }' python: | from openai import OpenAI from openai.types.fine_tuning import SupervisedMethod, SupervisedHyperparameters client = OpenAI() client.fine_tuning.jobs.create( training_file="file-abc123", model="gpt-4o-mini", method={ "type": "supervised", "supervised": SupervisedMethod( hyperparameters=SupervisedHyperparameters( n_epochs=2 ) ) } ) javascript: | import OpenAI from "openai"; import { SupervisedMethod, SupervisedHyperparameters } from "openai/resources/fine-tuning/methods"; const openai = new OpenAI(); async function main() { const fineTune = await openai.fineTuning.jobs.create({ training_file: "file-abc123", model: "gpt-4o-mini", method: { type: "supervised", supervised: { hyperparameters: { n_epochs: 2 } } } }); console.log(fineTune); } main(); - title: DPO request: curl: | curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc123", "validation_file": "file-abc123", "model": "gpt-4o-mini", "method": { "type": "dpo", "dpo": { "hyperparameters": { "beta": 0.1 } } } }' python: | from openai import OpenAI from openai.types.fine_tuning import DpoMethod, DpoHyperparameters client = OpenAI() client.fine_tuning.jobs.create( training_file="file-abc", validation_file="file-123", model="gpt-4o-mini", method={ "type": "dpo", "dpo": DpoMethod( hyperparameters=DpoHyperparameters(beta=0.1) ) } ) - title: Reinforcement request: curl: | curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc", "validation_file": "file-123", "model": "o4-mini", "method": { "type": "reinforcement", "reinforcement": { "grader": { "type": "string_check", "name": "Example string check grader", "input": "{{sample.output_text}}", "reference": "{{item.label}}", "operation": "eq" }, "hyperparameters": { "reasoning_effort": "medium" } } } }' 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" - title: Validation file request: curl: | curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc123", "validation_file": "file-abc123", "model": "gpt-4o-mini" }' python: | from openai import OpenAI client = OpenAI() client.fine_tuning.jobs.create( training_file="file-abc123", validation_file="file-def456", model="gpt-4o-mini" ) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const fineTune = await openai.fineTuning.jobs.create({ training_file: "file-abc123", validation_file: "file-abc123" }); console.log(fineTune); } main(); - title: W&B Integration request: curl: | curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-abc123", "validation_file": "file-abc123", "model": "gpt-4o-mini", "integrations": [ { "type": "wandb", "wandb": { "project": "my-wandb-project", "name": "ft-run-display-name" "tags": [ "first-experiment", "v2" ] } } ] }' get: operationId: listPaginatedFineTuningJobs tags: - Fine-tuning summary: List fine-tuning jobs description: | List your organization's fine-tuning jobs parameters: - name: after in: query description: Identifier for the last job from the previous pagination request. required: false schema: type: string - name: limit in: query description: Number of fine-tuning jobs to retrieve. required: false schema: type: integer default: 20 - in: query name: metadata required: false schema: type: object nullable: true additionalProperties: type: string style: deepObject explode: true description: | Optional metadata filter. To filter, use the syntax `metadata[k]=v`. Alternatively, set `metadata=null` to indicate no metadata. 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" \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.fine_tuning.jobs.list() javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const list = await openai.fineTuning.jobs.list(); for await (const fineTune of list) { console.log(fineTune); } } main(); response: | { "object": "list", "data": [ { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-4o-mini-2024-07-18", "created_at": 1721764800, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "queued", "validation_file": null, "training_file": "file-abc123", "error": null, "finished_at": null, "trained_tokens": null, "seed": 42, "hyperparameters": { "batch_size": "auto", "learning_rate_multiplier": "auto", "n_epochs": "auto" }, "method": { "type": "supervised", "supervised": { "hyperparameters": { "batch_size": "auto", "learning_rate_multiplier": "auto", "n_epochs": "auto" } } }, "metadata": { "key": "value" } } ], "has_more": false } /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. [Learn more about fine-tuning](https://developers.openai.com/api/docs/guides/model-optimization) parameters: - in: path name: fine_tuning_job_id required: true schema: type: string example: ft-AF1WoRqd3aJAHsqc9NY7iL8F description: | The ID of the fine-tuning job. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.fine_tuning.jobs.retrieve("ftjob-abc123") javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const fineTune = await openai.fineTuning.jobs.retrieve("ftjob-abc123"); console.log(fineTune); } main(); /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. 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. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.fine_tuning.jobs.cancel("ftjob-abc123") javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const fineTune = await openai.fineTuning.jobs.cancel("ftjob-abc123"); console.log(fineTune); } main(); /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. 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. - 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" response: | { "object": "list", "data": [ { "object": "fine_tuning.job.checkpoint", "id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB", "created_at": 1721764867, "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:96olL566:ckpt-step-2000", "metrics": { "full_valid_loss": 0.134, "full_valid_mean_token_accuracy": 0.874 }, "fine_tuning_job_id": "ftjob-abc123", "step_number": 2000 }, { "object": "fine_tuning.job.checkpoint", "id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy", "created_at": 1721764800, "fine_tuned_model_checkpoint": "ft:gpt-4o-mini-2024-07-18:my-org:custom-suffix:7q8mpxmy:ckpt-step-1000", "metrics": { "full_valid_loss": 0.167, "full_valid_mean_token_accuracy": 0.781 }, "fine_tuning_job_id": "ftjob-abc123", "step_number": 1000 } ], "first_id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB", "last_id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy", "has_more": true } /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. 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. - 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.fine_tuning.jobs.list_events( fine_tuning_job_id="ftjob-abc123", limit=2 ) javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const list = await openai.fineTuning.list_events(id="ftjob-abc123", limit=2); for await (const fineTune of list) { console.log(fineTune); } } main(); response: | { "object": "list", "data": [ { "object": "fine_tuning.job.event", "id": "ft-event-ddTJfwuMVpfLXseO0Am0Gqjm", "created_at": 1721764800, "level": "info", "message": "Fine tuning job successfully completed", "data": null, "type": "message" }, { "object": "fine_tuning.job.event", "id": "ft-event-tyiGuB72evQncpH87xe505Sv", "created_at": 1721764800, "level": "info", "message": "New fine-tuned model created: ft:gpt-4o-mini:openai::7p4lURel", "data": null, "type": "message" } ], "has_more": true } /fine_tuning/jobs/{fine_tuning_job_id}/pause: post: operationId: pauseFineTuningJob tags: - Fine-tuning summary: Pause fine-tuning description: | Pause a fine-tune job. 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. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.fine_tuning.jobs.pause("ftjob-abc123") javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const fineTune = await openai.fineTuning.jobs.pause("ftjob-abc123"); console.log(fineTune); } main(); /fine_tuning/jobs/{fine_tuning_job_id}/resume: post: operationId: resumeFineTuningJob tags: - Fine-tuning summary: Resume fine-tuning description: | Resume a fine-tune job. 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. 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 \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.fine_tuning.jobs.resume("ftjob-abc123") javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const fineTune = await openai.fineTuning.jobs.resume("ftjob-abc123"); console.log(fineTune); } main(); /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' 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) \ -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \ -X POST "https://api.openai.com/v1/images/edits" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F "model=gpt-image-1.5" \ -F "image[]=@body-lotion.png" \ -F "image[]=@bath-bomb.png" \ -F "image[]=@incense-kit.png" \ -F "image[]=@soap.png" \ -F 'prompt=Create a lovely gift basket with these four items in it' python: | import base64 from openai import OpenAI client = OpenAI() prompt = """ Generate a photorealistic image of a gift basket on a white background labeled 'Relax & Unwind' with a ribbon and handwriting-like font, containing all the items in the reference pictures. """ result = client.images.edit( model="gpt-image-1.5", image=[ open("body-lotion.png", "rb"), open("bath-bomb.png", "rb"), open("incense-kit.png", "rb"), open("soap.png", "rb"), ], prompt=prompt ) image_base64 = result.data[0].b64_json image_bytes = base64.b64decode(image_base64) # Save the image to a file with open("gift-basket.png", "wb") as f: f.write(image_bytes) javascript: | import fs from "fs"; import OpenAI, { toFile } from "openai"; const client = new OpenAI(); const imageFiles = [ "bath-bomb.png", "body-lotion.png", "incense-kit.png", "soap.png", ]; const images = await Promise.all( imageFiles.map(async (file) => await toFile(fs.createReadStream(file), null, { type: "image/png", }) ), ); const rsp = await client.images.edit({ model: "gpt-image-1.5", image: images, prompt: "Create a lovely gift basket with these four items in it", }); // Save the image to a file const image_base64 = rsp.data[0].b64_json; const image_bytes = Buffer.from(image_base64, "base64"); fs.writeFileSync("basket.png", image_bytes); - title: Streaming request: curl: | curl -s -N -X POST "https://api.openai.com/v1/images/edits" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F "model=gpt-image-1.5" \ -F "image[]=@body-lotion.png" \ -F "image[]=@bath-bomb.png" \ -F "image[]=@incense-kit.png" \ -F "image[]=@soap.png" \ -F 'prompt=Create a lovely gift basket with these four items in it' \ -F "stream=true" python: | from openai import OpenAI client = OpenAI() prompt = """ Generate a photorealistic image of a gift basket on a white background labeled 'Relax & Unwind' with a ribbon and handwriting-like font, containing all the items in the reference pictures. """ stream = client.images.edit( model="gpt-image-1.5", image=[ open("body-lotion.png", "rb"), open("bath-bomb.png", "rb"), open("incense-kit.png", "rb"), open("soap.png", "rb"), ], prompt=prompt, stream=True ) for event in stream: print(event) javascript: | import fs from "fs"; import OpenAI, { toFile } from "openai"; const client = new OpenAI(); const imageFiles = [ "bath-bomb.png", "body-lotion.png", "incense-kit.png", "soap.png", ]; const images = await Promise.all( imageFiles.map(async (file) => await toFile(fs.createReadStream(file), null, { type: "image/png", }) ), ); const stream = await client.images.edit({ model: "gpt-image-1.5", image: images, prompt: "Create a lovely gift basket with these four items in it", stream: true, }); for await (const event of stream) { console.log(event); } response: | event: image_edit.partial_image data: {"type":"image_edit.partial_image","b64_json":"...","partial_image_index":0} event: image_edit.completed data: {"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}}} /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). 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 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-image-2.5-flare", "prompt": "A cute baby sea otter", "n": 1, "size": "1024x1024" }' python: | import base64 from openai import OpenAI client = OpenAI() img = client.images.generate( model="gpt-image-2.5-flare", prompt="A cute baby sea otter", n=1, size="1024x1024" ) image_bytes = base64.b64decode(img.data[0].b64_json) with open("output.png", "wb") as f: f.write(image_bytes) javascript: | import OpenAI from "openai"; import { writeFile } from "fs/promises"; const client = new OpenAI(); const img = await client.images.generate({ model: "gpt-image-2.5-flare", prompt: "A cute baby sea otter", n: 1, size: "1024x1024" }); const imageBuffer = Buffer.from(img.data[0].b64_json, "base64"); await writeFile("output.png", imageBuffer); response: | { "created": 1713833628, "data": [ { "b64_json": "..." } ], "usage": { "total_tokens": 100, "input_tokens": 50, "output_tokens": 50, "input_tokens_details": { "text_tokens": 10, "image_tokens": 40 } } } - title: Streaming request: curl: | curl https://api.openai.com/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-image-2.5-flare", "prompt": "A cute baby sea otter", "n": 1, "size": "1024x1024", "stream": true }' \ --no-buffer python: | from openai import OpenAI client = OpenAI() stream = client.images.generate( model="gpt-image-2.5-flare", prompt="A cute baby sea otter", n=1, size="1024x1024", stream=True ) for event in stream: print(event) javascript: | import OpenAI from "openai"; const client = new OpenAI(); const stream = await client.images.generate({ model: "gpt-image-2.5-flare", prompt: "A cute baby sea otter", n: 1, size: "1024x1024", stream: true, }); for await (const event of stream) { console.log(event); } response: | event: image_generation.partial_image data: {"type":"image_generation.partial_image","b64_json":"...","partial_image_index":0} event: image_generation.completed data: {"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}}} /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F image="@otter.png" \ -F n=2 \ -F size="1024x1024" python: | from openai import OpenAI client = OpenAI() response = client.images.create_variation( image=open("image_edit_original.png", "rb"), n=2, size="1024x1024" ) javascript: |- import fs from "fs"; import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const image = await openai.images.createVariation({ image: fs.createReadStream("otter.png"), }); console.log(image.data); } main(); csharp: | using System; using OpenAI.Images; ImageClient client = new( model: "dall-e-2", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); GeneratedImage image = client.GenerateImageVariation(imageFilePath: "otter.png"); Console.WriteLine(image.ImageUri); response: | { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] } /live/sessions: post: operationId: create-live summary: Create session description: Create a Live WebRTC session. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting). tags: - Live requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LiveCreateRequest' responses: '201': description: Returns 201 Created with the Live session identifier and WebRTC SDP answer. content: application/json: schema: $ref: '#/components/schemas/LiveCreateResponse' examples: webrtc: summary: WebRTC session created (201 Created) value: session: id: live_123 transport: type: webrtc sdp: '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 '503': description: The session is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' text/plain: schema: type: string x-oaiMeta: group: live returns: Returns a session identifier in session.id and a WebRTC SDP answer in transport.sdp. examples: - title: Create a WebRTC session request: curl: |- curl https://api.openai.com/v1/live/sessions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -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":""}}' /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -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 \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.models.list() javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const list = await openai.models.list(); for await (const model of list) { console.log(model); } } main(); csharp: | using System; using OpenAI.Models; OpenAIModelClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); foreach (var model in client.GetModels().Value) { Console.WriteLine(model.Id); } response: | { "object": "list", "data": [ { "id": "model-id-0", "object": "model", "created": 1686935002, "owned_by": "organization-owner", "shutdown_date": null }, { "id": "model-id-1", "object": "model", "created": 1686935002, "owned_by": "organization-owner", "shutdown_date": null }, { "id": "model-id-2", "object": "model", "created": 1686935002, "owned_by": "openai", "shutdown_date": "2026-10-23" } ] } /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 \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.models.retrieve("gpt-6-astra") javascript: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const model = await openai.models.retrieve("gpt-6-astra"); console.log(model); } main(); csharp: | using System; using System.ClientModel; using OpenAI.Models; OpenAIModelClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ClientResult model = client.GetModel("babbage-002"); Console.WriteLine(model.Value.Id); response: | { "id": "gpt-6-astra", "object": "model", "created": 1686935002, "owned_by": "openai", "shutdown_date": "2026-10-23" } 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 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() client.models.delete("ft:gpt-4o-mini:acemeco:suffix:abc123") 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; using System.ClientModel; using OpenAI.Models; OpenAIModelClient client = new( apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ClientResult success = client.DeleteModel("ft:gpt-4o-mini:acemeco:suffix:abc123"); Console.WriteLine(success); response: | { "id": "ft:gpt-4o-mini:acemeco:suffix:abc123", "object": "model", "deleted": true } /moderations: post: operationId: createModeration tags: - Moderations summary: Create moderation description: | Classifies if text and/or image inputs are potentially harmful. Learn more in the [moderation guide](https://developers.openai.com/api/docs/guides/moderation). 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 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "omni-moderation-latest", "input": "I want to kill them." }' python: | from openai import OpenAI client = OpenAI() moderation = client.moderations.create( model="omni-moderation-latest", input="I want to kill them.", ) print(moderation) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const moderation = await openai.moderations.create({ model: "omni-moderation-latest", input: "I want to kill them.", }); console.log(moderation); } main(); csharp: | using System; using System.ClientModel; using OpenAI.Moderations; ModerationClient client = new( model: "omni-moderation-latest", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY") ); ClientResult moderation = client.ClassifyText("I want to kill them."); response: | { "id": "modr-AB8CjOTu2jiq12hp1AQPfeqFWaORR", "model": "omni-moderation-latest", "results": [ { "flagged": true, "categories": { "sexual": false, "hate": false, "harassment": true, "self-harm": false, "sexual/minors": false, "hate/threatening": false, "violence/graphic": false, "self-harm/intent": false, "self-harm/instructions": false, "harassment/threatening": true, "violence": true, "illicit": false, "illicit/violent": false }, "category_scores": { "sexual": 1.1726012417057063e-05, "hate": 0.22706663608551025, "harassment": 0.5215635299682617, "self-harm": 2.227119921371923e-06, "sexual/minors": 7.107352217872176e-08, "hate/threatening": 0.023547329008579254, "violence/graphic": 3.391829886822961e-05, "self-harm/intent": 1.646940972932498e-06, "self-harm/instructions": 1.1198755256458526e-09, "harassment/threatening": 0.5694745779037476, "violence": 0.9971134662628174, "illicit": 0.001, "illicit/violent": 0.001 }, "category_applied_input_types": { "sexual": [ "text" ], "hate": [ "text" ], "harassment": [ "text" ], "self-harm": [ "text" ], "sexual/minors": [ "text" ], "hate/threatening": [ "text" ], "violence/graphic": [ "text" ], "self-harm/intent": [ "text" ], "self-harm/instructions": [ "text" ], "harassment/threatening": [ "text" ], "violence": [ "text" ], "illicit": [ "text" ], "illicit/violent": [ "text" ] } } ] } - title: Image and text request: curl: | curl https://api.openai.com/v1/moderations \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "omni-moderation-latest", "input": [ { "type": "text", "text": "...text to classify goes here..." }, { "type": "image_url", "image_url": { "url": "https://example.com/image.png" } } ] }' python: | from openai import OpenAI client = OpenAI() response = client.moderations.create( model="omni-moderation-latest", input=[ {"type": "text", "text": "...text to classify goes here..."}, { "type": "image_url", "image_url": { "url": "https://example.com/image.png", # can also use base64 encoded image URLs # "url": "data:image/jpeg;base64,abcdefg..." } }, ], ) print(response) javascript: | import OpenAI from "openai"; const openai = new OpenAI(); const moderation = await openai.moderations.create({ model: "omni-moderation-latest", input: [ { type: "text", text: "...text to classify goes here..." }, { type: "image_url", image_url: { url: "https://example.com/image.png" // can also use base64 encoded image URLs // url: "data:image/jpeg;base64,abcdefg..." } } ], }); console.log(moderation); response: | { "id": "modr-0d9740456c391e43c445bf0f010940c7", "model": "omni-moderation-latest", "results": [ { "flagged": true, "categories": { "harassment": true, "harassment/threatening": true, "sexual": false, "hate": false, "hate/threatening": false, "illicit": false, "illicit/violent": false, "self-harm/intent": false, "self-harm/instructions": false, "self-harm": false, "sexual/minors": false, "violence": true, "violence/graphic": true }, "category_scores": { "harassment": 0.8189693396524255, "harassment/threatening": 0.804985420696006, "sexual": 1.573112165348997e-6, "hate": 0.007562942636942845, "hate/threatening": 0.004208854591835476, "illicit": 0.030535955153511665, "illicit/violent": 0.008925306722380033, "self-harm/intent": 0.00023023930975076432, "self-harm/instructions": 0.0002293869201073356, "self-harm": 0.012598046106750154, "sexual/minors": 2.212566909570261e-8, "violence": 0.9999992735124786, "violence/graphic": 0.843064871157054 }, "category_applied_input_types": { "harassment": [ "text" ], "harassment/threatening": [ "text" ], "sexual": [ "text", "image" ], "hate": [ "text" ], "hate/threatening": [ "text" ], "illicit": [ "text" ], "illicit/violent": [ "text" ], "self-harm/intent": [ "text", "image" ], "self-harm/instructions": [ "text", "image" ], "self-harm": [ "text", "image" ], "sexual/minors": [ "text" ], "violence": [ "text", "image" ], "violence/graphic": [ "text", "image" ] } } ] } /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 nullable: true description: Return keys with IDs that come after this ID in the pagination order. - in: query name: order required: false schema: type: string enum: - asc - desc default: asc description: Order results by creation time, ascending or descending. - in: query name: limit required: false schema: type: integer default: 20 description: Maximum number of keys to return. responses: '200': description: A list of organization API keys. content: application/json: schema: $ref: '#/components/schemas/ApiKeyList' '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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "organization.admin_api_key", "id": "key_abc", "name": "Main Admin Key", "redacted_value": "sk-admin...def", "created_at": 1711471533, "expires_at": 1714063533, "last_used_at": 1711471534, "owner": { "type": "service_account", "object": "organization.service_account", "id": "sa_456", "name": "My Service Account", "created_at": 1711471533, "role": "member" } } ], "first_id": "key_abc", "last_id": "key_abc", "has_more": false } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "New Admin Key", "expires_in_seconds": 2592000 }' response: | { "object": "organization.admin_api_key", "id": "key_xyz", "name": "New Admin Key", "redacted_value": "sk-admin...xyz", "created_at": 1711471533, "expires_at": 1714063533, "last_used_at": 1711471534, "owner": { "type": "user", "object": "organization.user", "id": "user_123", "name": "John Doe", "created_at": 1711471533, "role": "owner" }, "value": "sk-admin-1234abcd" } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.admin_api_key", "id": "key_abc", "name": "Main Admin Key", "redacted_value": "sk-admin...xyz", "created_at": 1711471533, "expires_at": null, "last_used_at": 1711471534, "owner": { "type": "user", "object": "organization.user", "id": "user_123", "name": "John Doe", "created_at": 1711471533, "role": "owner" } } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "key_abc", "object": "organization.admin_api_key.deleted", "deleted": true } /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. 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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "id": "audit_log-xxx_yyyymmdd", "type": "project.archived", "effective_at": 1722461446, "actor": { "type": "api_key", "api_key": { "type": "user", "user": { "id": "user-xxx", "email": "user@example.com" } } }, "project.archived": { "id": "proj_abc" } }, { "id": "audit_log-yyy__20240101", "type": "api_key.updated", "effective_at": 1720804190, "actor": { "type": "session", "session": { "user": { "id": "user-xxx", "email": "user@example.com" }, "ip_address": "127.0.0.1", "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", "ja3": "a497151ce4338a12c4418c44d375173e", "ja4": "q13d0313h3_55b375c5d22e_c7319ce65786", "ip_address_details": { "country": "US", "city": "San Francisco", "region": "California", "region_code": "CA", "asn": "1234", "latitude": "37.77490", "longitude": "-122.41940" } } }, "api_key.updated": { "id": "key_xxxx", "data": { "scopes": ["resource_2.operation_2"] } } } ], "first_id": "audit_log-xxx__20240101", "last_id": "audit_log_yyy__20240101", "has_more": true } /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. 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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" response: | { "object": "list", "data": [ { "object": "organization.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } } ], "first_id": "cert_abc", "last_id": "cert_abc", "has_more": false } post: security: - AdminApiKeyAuth: [] summary: Upload certificate description: | Upload a certificate to the organization. This does **not** automatically activate the certificate. Organizations can upload up to 50 certificates. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "My Example Certificate", "certificate": "-----BEGIN CERTIFICATE-----\\nMIIDeT...\\n-----END CERTIFICATE-----" }' response: | { "object": "certificate", "id": "cert_abc", "name": "My Example Certificate", "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } } /organization/certificates/activate: post: security: - AdminApiKeyAuth: [] summary: Activate certificates for organization description: | Activate certificates at the organization level. You can atomically and idempotently activate up to 10 certificates at a time. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "certificate_ids": ["cert_abc", "cert_def"] }' response: | { "object": "organization.certificate.activation", "data": [ { "object": "organization.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, { "object": "organization.certificate", "id": "cert_def", "name": "My Example Certificate 2", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } } ] } /organization/certificates/deactivate: post: security: - AdminApiKeyAuth: [] summary: Deactivate certificates for organization description: | Deactivate certificates at the organization level. You can atomically and idempotently deactivate up to 10 certificates at a time. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "certificate_ids": ["cert_abc", "cert_def"] }' response: | { "object": "organization.certificate.deactivation", "data": [ { "object": "organization.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": false, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, { "object": "organization.certificate", "id": "cert_def", "name": "My Example Certificate 2", "active": false, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } } ] } /organization/certificates/{certificate_id}: get: security: - AdminApiKeyAuth: [] summary: Get certificate description: | Get a certificate that has been uploaded to the organization. You can get a certificate regardless of whether it is active or not. 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" response: | { "object": "certificate", "id": "cert_abc", "name": "My Example Certificate", "created_at": 1234567, "certificate_details": { "valid_at": 1234567, "expires_at": 12345678, "content": "-----BEGIN CERTIFICATE-----MIIDeT...-----END CERTIFICATE-----" } } post: security: - AdminApiKeyAuth: [] summary: Modify certificate description: | Modify a certificate. Note that only the name can be modified. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Renamed Certificate" }' response: | { "object": "certificate", "id": "cert_abc", "name": "Renamed Certificate", "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } } delete: security: - AdminApiKeyAuth: [] summary: Delete certificate description: | Delete a certificate from the organization. The certificate must be inactive for the organization and all projects. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" response: | { "object": "certificate.deleted", "id": "cert_abc" } /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. Support fields include `project_id`, `line_item`, `api_key_id` and any combination of them. required: false schema: type: array items: type: string enum: - project_id - line_item - api_key_id - name: limit in: query description: | A limit on the number of buckets to be returned. Limit can range between 1 and 180, and the default is 7. 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.costs.result", "amount": { "value": 0.06, "currency": "usd" }, "line_item": null, "project_id": null, "api_key_id": null, "quantity": null, "quantity_unit": null } ] } ], "has_more": false, "next_page": null } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.data_retention", "type": "modified_abuse_monitoring" } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "retention_type": "modified_abuse_monitoring" }' response: | { "object": "organization.data_retention", "type": "modified_abuse_monitoring" } /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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "group", "id": "group_01J1F8ABCDXYZ", "name": "Support Team", "created_at": 1711471533, "group_type": "group", "is_scim_managed": false } ], "has_more": false, "next": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Support Team" }' response: | { "object": "group", "id": "group_01J1F8ABCDXYZ", "name": "Support Team", "created_at": 1711471533, "group_type": "group", "is_scim_managed": false } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "group_01J1F8ABCDXYZ", "name": "Support Team", "created_at": 1711471533, "is_scim_managed": false, "group_type": "group" } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Escalations" }' response: | { "id": "group_01J1F8ABCDXYZ", "name": "Escalations", "created_at": 1711471533, "is_scim_managed": false } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "group.deleted", "id": "group_01J1F8ABCDXYZ", "deleted": true } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "id": "role_01J1F8ROLE01", "name": "API Group Manager", "permissions": [ "api.groups.read", "api.groups.write" ], "resource_type": "api.organization", "predefined_role": false, "description": "Allows managing organization groups", "created_at": 1711471533, "updated_at": 1711472599, "created_by": "user_abc123", "created_by_user_obj": { "id": "user_abc123", "name": "Ada Lovelace", "email": "ada@example.com" }, "metadata": {}, "assignment_sources": [ { "principal_id": "group_01J1F8ABCDXYZ", "principal_type": "group" } ] } ], "has_more": false, "next": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role_id": "role_01J1F8ROLE01" }' response: | { "object": "group.role", "group": { "object": "group", "id": "group_01J1F8ABCDXYZ", "name": "Support Team", "created_at": 1711471533, "scim_managed": false }, "role": { "object": "role", "id": "role_01J1F8ROLE01", "name": "API Group Manager", "description": "Allows managing organization groups", "permissions": [ "api.groups.read", "api.groups.write" ], "resource_type": "api.organization", "predefined_role": false } } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "role_01J1F8ROLE01", "name": "API Group Manager", "permissions": [ "api.groups.read", "api.groups.write" ], "resource_type": "api.organization", "predefined_role": false, "description": "Allows managing organization groups", "created_at": 1711471533, "updated_at": 1711472599, "created_by": "user_abc123", "created_by_user_obj": null, "metadata": {}, "assignment_sources": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "group.role.deleted", "deleted": true } /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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "id": "user_abc123", "name": "Ada Lovelace", "email": "ada@example.com" } ], "has_more": false, "next": null } 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "user_id": "user_abc123" }' response: | { "object": "group.user", "user_id": "user_abc123", "group_id": "group_01J1F8ABCDXYZ" } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "user_abc123", "name": "Ada Lovelace", "email": "ada@example.com", "picture": null, "is_service_account": false, "user_type": "user" } 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "group.user.deleted", "deleted": true } /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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "organization.invite", "id": "invite-abc", "email": "user@example.com", "role": "owner", "status": "accepted", "created_at": 1711471533, "expires_at": 1711471533, "accepted_at": 1711471533, "projects": [] } ], "first_id": "invite-abc", "last_id": "invite-abc", "has_more": false } 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' '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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "anotheruser@example.com", "role": "reader", "projects": [ { "id": "project-xyz", "role": "member" }, { "id": "project-abc", "role": "owner" } ] }' response: | { "object": "organization.invite", "id": "invite-def", "email": "anotheruser@example.com", "role": "reader", "status": "pending", "created_at": 1711471533, "expires_at": 1711471533, "accepted_at": null, "projects": [ { "id": "project-xyz", "role": "member" }, { "id": "project-abc", "role": "owner" } ] } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.invite", "id": "invite-abc", "email": "user@example.com", "role": "owner", "status": "accepted", "created_at": 1711471533, "expires_at": 1711471533, "accepted_at": 1711471533, "projects": [] } 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: | The caller is not permitted to delete the invite. content: application/json: schema: $ref: '#/components/schemas/PermissionErrorResponse' '404': description: | The invite was not found in the organization. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: | The request rate limit was exceeded. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.invite.deleted", "id": "invite-abc", "deleted": true } /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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "id": "proj_abc", "object": "organization.project", "name": "Project example", "created_at": 1711471533, "archived_at": null, "status": "active" } ], "first_id": "proj-abc", "last_id": "proj-xyz", "has_more": false } 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' '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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Project ABC" }' response: | { "id": "proj_abc", "object": "organization.project", "name": "Project ABC", "created_at": 1711471533, "archived_at": null, "status": "active" } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "proj_abc", "object": "organization.project", "name": "Project example", "created_at": 1711471533, "archived_at": null, "status": "active" } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Project DEF" }' /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. 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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "organization.project.api_key", "redacted_value": "sk-abc...def", "name": "My API Key", "created_at": 1711471533, "last_used_at": 1711471534, "id": "key_abc", "owner_project_access": "active", "owner": { "type": "user", "user": { "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "created_at": 1711471533 } } } ], "first_id": "key_abc", "last_id": "key_xyz", "has_more": false } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.project.api_key", "redacted_value": "sk-abc...def", "name": "My API Key", "created_at": 1711471533, "last_used_at": 1711471534, "id": "key_abc", "owner_project_access": "active", "owner": { "type": "user", "user": { "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "created_at": 1711471533 } } } delete: security: - AdminApiKeyAuth: [] summary: Delete project API key description: | Deletes an API key from the project. Returns confirmation of the key deletion, or an error if the key belonged to a service account. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.project.api_key.deleted", "id": "key_abc", "deleted": true } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "proj_abc", "object": "organization.project", "name": "Project DEF", "created_at": 1711471533, "archived_at": 1711471533, "status": "archived" } /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. 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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" response: | { "object": "list", "data": [ { "object": "organization.project.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } } ], "first_id": "cert_abc", "last_id": "cert_abc", "has_more": false } /organization/projects/{project_id}/certificates/activate: post: security: - AdminApiKeyAuth: [] summary: Activate certificates for project description: | Activate certificates at the project level. You can atomically and idempotently activate up to 10 certificates at a time. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "certificate_ids": ["cert_abc", "cert_def"] }' response: | { "object": "organization.project.certificate.activation", "data": [ { "object": "organization.project.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, { "object": "organization.project.certificate", "id": "cert_def", "name": "My Example Certificate 2", "active": true, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } } ] } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "certificate_ids": ["cert_abc", "cert_def"] }' response: | { "object": "organization.project.certificate.deactivation", "data": [ { "object": "organization.project.certificate", "id": "cert_abc", "name": "My Example Certificate", "active": false, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } }, { "object": "organization.project.certificate", "id": "cert_def", "name": "My Example Certificate 2", "active": false, "created_at": 1234567, "certificate_details": { "valid_at": 12345667, "expires_at": 12345678 } } ] } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "project.data_retention", "type": "organization_default" } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "retention_type": "modified_abuse_monitoring" }' response: | { "object": "project.data_retention", "type": "modified_abuse_monitoring" } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "project.group", "project_id": "proj_abc123", "group_id": "group_01J1F8ABCDXYZ", "group_name": "Support Team", "group_type": "group", "created_at": 1711471533 } ], "has_more": false, "next": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "group_id": "group_01J1F8ABCDXYZ", "role": "role_01J1F8PROJ" }' response: | { "object": "project.group", "project_id": "proj_abc123", "group_id": "group_01J1F8ABCDXYZ", "group_name": "Support Team", "group_type": "group", "created_at": 1711471533 } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "project.group", "project_id": "proj_abc123", "group_id": "group_01J1F8ABCDXYZ", "group_name": "Support Team", "group_type": "group", "created_at": 1711471533 } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "project.group.deleted", "deleted": true } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "file_search": { "enabled": true }, "web_search": { "enabled": true }, "image_generation": { "enabled": true }, "mcp": { "enabled": true }, "code_interpreter": { "enabled": true } } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "file_search": { "enabled": true }, "image_generation": { "enabled": false } }' response: | { "file_search": { "enabled": true }, "web_search": { "enabled": true }, "image_generation": { "enabled": false }, "mcp": { "enabled": true }, "code_interpreter": { "enabled": true } } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "project.model_permissions", "mode": "allow_list", "model_ids": [ "gpt-6-astra", "o3" ] } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "mode": "deny_list", "model_ids": [ "o3" ] }' response: | { "object": "project.model_permissions", "mode": "deny_list", "model_ids": [ "o3" ] } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "project.model_permissions.deleted", "deleted": true } /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. 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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "project.rate_limit", "id": "rl-ada", "model": "ada", "max_requests_per_1_minute": 600, "max_tokens_per_1_minute": 150000, "max_images_per_1_minute": 10 } ], "first_id": "rl-ada", "last_id": "rl-ada", "has_more": false } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "max_requests_per_1_minute": 500 }' response: | { "object": "project.rate_limit", "id": "rl-ada", "model": "ada", "max_requests_per_1_minute": 600, "max_tokens_per_1_minute": 150000, "max_images_per_1_minute": 10 } /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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "organization.project.service_account", "id": "svc_acct_abc", "name": "Service Account", "role": "owner", "created_at": 1711471533 } ], "first_id": "svc_acct_abc", "last_id": "svc_acct_xyz", "has_more": false } 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' '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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Production App" }' response: | { "object": "organization.project.service_account", "id": "svc_acct_abc", "name": "Production App", "role": "member", "created_at": 1711471533, "api_key": { "object": "organization.project.service_account.api_key", "value": "sk-abcdefghijklmnop123", "name": "Secret Key", "created_at": 1711471533, "id": "key_abc" } } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.project.service_account", "id": "svc_acct_abc", "name": "Service Account", "role": "owner", "created_at": 1711471533 } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated service account", "role": "member" }' response: | { "object": "organization.project.service_account", "id": "svc_acct_abc", "name": "Updated service account", "role": "member", "created_at": 1711471533 } delete: security: - AdminApiKeyAuth: [] summary: Delete project service account description: | Deletes a service account from the project. Returns confirmation of service account deletion, or an error if the project is archived (archived projects have no service accounts). 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: | The caller is not permitted to delete the service account. content: application/json: schema: $ref: '#/components/schemas/PermissionErrorResponse' '404': description: | The project or service account was not found in the organization. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: | The request rate limit was exceeded. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.project.service_account.deleted", "id": "svc_acct_abc", "deleted": true } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "id": "alert_abc123", "object": "project.spend_alert", "threshold_amount": 100000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } } ], "first_id": "alert_abc123", "last_id": "alert_abc123", "has_more": false } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "threshold_amount": 100000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } }' response: | { "id": "alert_abc123", "object": "project.spend_alert", "threshold_amount": 100000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "alert_abc123", "object": "project.spend_alert", "threshold_amount": 150000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "threshold_amount": 150000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } }' response: | { "id": "alert_abc123", "object": "project.spend_alert", "threshold_amount": 150000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "alert_abc123", "object": "project.spend_alert.deleted", "deleted": true } /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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "organization.project.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } ], "first_id": "user-abc", "last_id": "user-xyz", "has_more": false } 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' '400': description: | The request is invalid or the user cannot be added to the project in its current state. 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: | The request conflicts with the current state of the resource. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "user_id": "user_abc", "role": "member" }' response: | { "object": "organization.project.user", "id": "user_abc", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.project.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role": "owner" }' response: | { "object": "organization.project.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } delete: security: - AdminApiKeyAuth: [] summary: Delete project user description: | Deletes a user from the project. Returns confirmation of project user deletion, or an error if the project is archived (archived projects have no users). 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.project.user.deleted", "id": "user_abc", "deleted": true } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "role", "id": "role_01J1F8ROLE01", "name": "API Group Manager", "description": "Allows managing organization groups", "permissions": [ "api.groups.read", "api.groups.write" ], "resource_type": "api.organization", "predefined_role": false } ], "has_more": false, "next": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role_name": "API Group Manager", "permissions": [ "api.groups.read", "api.groups.write" ], "description": "Allows managing organization groups" }' response: | { "object": "role", "id": "role_01J1F8ROLE01", "name": "API Group Manager", "description": "Allows managing organization groups", "permissions": [ "api.groups.read", "api.groups.write" ], "resource_type": "api.organization", "predefined_role": false } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "role", "id": "role_01J1F8ROLE01", "name": "API Group Manager", "description": "Allows managing organization groups", "permissions": [ "api.groups.read", "api.groups.write" ], "resource_type": "api.organization", "predefined_role": false } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role_name": "API Group Manager", "permissions": [ "api.groups.read", "api.groups.write" ], "description": "Allows managing organization groups" }' response: | { "object": "role", "id": "role_01J1F8ROLE01", "name": "API Group Manager", "description": "Allows managing organization groups", "permissions": [ "api.groups.read", "api.groups.write" ], "resource_type": "api.organization", "predefined_role": false } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "role.deleted", "id": "role_01J1F8ROLE01", "deleted": true } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "id": "alert_abc123", "object": "organization.spend_alert", "threshold_amount": 100000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } } ], "first_id": "alert_abc123", "last_id": "alert_abc123", "has_more": false } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "threshold_amount": 100000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } }' response: | { "id": "alert_abc123", "object": "organization.spend_alert", "threshold_amount": 100000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "alert_abc123", "object": "organization.spend_alert", "threshold_amount": 150000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "threshold_amount": 150000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } }' response: | { "id": "alert_abc123", "object": "organization.spend_alert", "threshold_amount": 150000, "currency": "USD", "interval": "month", "notification_channel": { "type": "email", "recipients": ["finance@example.com"], "subject_prefix": "OpenAI spend alert" } } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "alert_abc123", "object": "organization.spend_alert.deleted", "deleted": true } /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. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.audio_speeches.result", "characters": 45, "num_model_requests": 1, "project_id": null, "user_id": null, "api_key_id": null, "model": null } ] } ], "has_more": false, "next_page": null } /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. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.audio_transcriptions.result", "seconds": 20, "num_model_requests": 1, "project_id": null, "user_id": null, "api_key_id": null, "model": null } ] } ], "has_more": false, "next_page": null } /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. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.code_interpreter_sessions.result", "num_sessions": 1, "project_id": null } ] } ], "has_more": false, "next_page": null } /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. required: false schema: type: boolean - name: group_by in: query description: Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `batch`, `service_tier` or any combination of them. required: false schema: type: array items: type: string enum: - project_id - user_id - api_key_id - model - batch - service_tier - name: limit in: query description: | Specifies the number of buckets to return. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.completions.result", "input_tokens": 1000, "input_cached_tokens": 400, "input_cache_write_tokens": 75, "input_cache_write_12h_tokens": 25, "input_uncached_tokens": 500, "output_tokens": 500, "input_text_tokens": 400, "output_text_tokens": 400, "input_cached_text_tokens": 300, "input_audio_tokens": 50, "input_cached_audio_tokens": 50, "output_audio_tokens": 50, "input_image_tokens": 50, "input_cached_image_tokens": 50, "output_image_tokens": 50, "num_model_requests": 5, "project_id": null, "user_id": null, "api_key_id": null, "model": null, "batch": null, "service_tier": null } ] } ], "has_more": true, "next_page": "page_AAAAAGdGxdEiJdKOAAAAAGcqsYA=" } /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. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.embeddings.result", "input_tokens": 16, "num_model_requests": 2, "project_id": null, "user_id": null, "api_key_id": null, "model": null } ] } ], "has_more": false, "next_page": null } /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. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.file_searches.result", "num_requests": 2, "project_id": null, "user_id": null, "api_key_id": null, "vector_store_id": null } ] } ], "has_more": false, "next_page": null } /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. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.images.result", "images": 2, "num_model_requests": 2, "size": null, "source": null, "project_id": null, "user_id": null, "api_key_id": null, "model": null } ] } ], "has_more": false, "next_page": null } /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. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.moderations.result", "input_tokens": 16, "num_model_requests": 2, "project_id": null, "user_id": null, "api_key_id": null, "model": null } ] } ], "has_more": false, "next_page": null } /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. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.vector_stores.result", "usage_bytes": 1024, "project_id": null } ] } ], "has_more": false, "next_page": null } /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` or any combination of them. required: false schema: type: array items: type: string enum: - project_id - user_id - api_key_id - model - context_level - name: limit in: query description: | Specifies the number of buckets to return. - `bucket_width=1d`: default: 7, max: 31 - `bucket_width=1h`: default: 24, max: 168 - `bucket_width=1m`: default: 60, max: 1440 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" \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "page", "data": [ { "object": "bucket", "start_time": 1730419200, "end_time": 1730505600, "results": [ { "object": "organization.usage.web_searches.result", "num_model_requests": 2, "num_requests": 2, "project_id": null, "user_id": null, "api_key_id": null, "model": null, "context_level": null } ] } ], "has_more": false, "next_page": null } /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. 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. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "organization.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } ], "first_id": "user-abc", "last_id": "user-xyz", "has_more": false } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role": "owner" }' response: | { "object": "organization.user", "id": "user_abc", "name": "First Last", "email": "user@example.com", "role": "owner", "added_at": 1711471533 } 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: | The caller is not permitted to delete the user. content: application/json: schema: $ref: '#/components/schemas/PermissionErrorResponse' '404': description: | The user was not found in the organization. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: | The request rate limit was exceeded. 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "organization.user.deleted", "id": "user_abc", "deleted": true } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "id": "role_01J1F8ROLE01", "name": "API Group Manager", "permissions": [ "api.groups.read", "api.groups.write" ], "resource_type": "api.organization", "predefined_role": false, "description": "Allows managing organization groups", "created_at": 1711471533, "updated_at": 1711472599, "created_by": "user_abc123", "created_by_user_obj": { "id": "user_abc123", "name": "Ada Lovelace", "email": "ada@example.com" }, "metadata": {}, "assignment_sources": [ { "principal_id": "user_abc123", "principal_type": "user" } ] } ], "has_more": false, "next": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role_id": "role_01J1F8ROLE01" }' response: | { "object": "user.role", "user": { "object": "organization.user", "id": "user_abc123", "name": "Ada Lovelace", "email": "ada@example.com", "role": "owner", "added_at": 1711470000 }, "role": { "object": "role", "id": "role_01J1F8ROLE01", "name": "API Group Manager", "description": "Allows managing organization groups", "permissions": [ "api.groups.read", "api.groups.write" ], "resource_type": "api.organization", "predefined_role": false } } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "role_01J1F8ROLE01", "name": "API Group Manager", "permissions": [ "api.groups.read", "api.groups.write" ], "resource_type": "api.organization", "predefined_role": false, "description": "Allows managing organization groups", "created_at": 1711471533, "updated_at": 1711472599, "created_by": "user_abc123", "created_by_user_obj": null, "metadata": {}, "assignment_sources": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "user.role.deleted", "deleted": true } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "id": "role_01J1F8PROJ", "name": "API Project Key Manager", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "resource_type": "api.project", "predefined_role": false, "description": "Allows managing API keys for the project", "created_at": 1711471533, "updated_at": 1711472599, "created_by": "user_abc123", "created_by_user_obj": { "id": "user_abc123", "name": "Ada Lovelace", "email": "ada@example.com" }, "metadata": {}, "assignment_sources": [ { "principal_id": "group_01J1F8ABCDXYZ", "principal_type": "group" } ] } ], "has_more": false, "next": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role_id": "role_01J1F8PROJ" }' response: | { "object": "group.role", "group": { "object": "group", "id": "group_01J1F8ABCDXYZ", "name": "Support Team", "created_at": 1711471533, "scim_managed": false }, "role": { "object": "role", "id": "role_01J1F8PROJ", "name": "API Project Key Manager", "description": "Allows managing API keys for the project", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "resource_type": "api.project", "predefined_role": false } } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "role_01J1F8PROJ", "name": "API Project Key Manager", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "resource_type": "api.project", "predefined_role": false, "description": "Allows managing API keys for the project", "created_at": 1711471533, "updated_at": 1711472599, "created_by": "user_abc123", "created_by_user_obj": null, "metadata": {}, "assignment_sources": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "group.role.deleted", "deleted": true } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "object": "role", "id": "role_01J1F8PROJ", "name": "API Project Key Manager", "description": "Allows managing API keys for the project", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "resource_type": "api.project", "predefined_role": false } ], "has_more": false, "next": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role_name": "API Project Key Manager", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "description": "Allows managing API keys for the project" }' response: | { "object": "role", "id": "role_01J1F8PROJ", "name": "API Project Key Manager", "description": "Allows managing API keys for the project", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "resource_type": "api.project", "predefined_role": false } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "role", "id": "role_01J1F8PROJ", "name": "API Project Key Manager", "description": "Allows managing API keys for the project", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "resource_type": "api.project", "predefined_role": false } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role_name": "API Project Key Manager", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "description": "Allows managing API keys for the project" }' response: | { "object": "role", "id": "role_01J1F8PROJ", "name": "API Project Key Manager", "description": "Allows managing API keys for the project", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "resource_type": "api.project", "predefined_role": false } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "role.deleted", "id": "role_01J1F8PROJ", "deleted": true } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "list", "data": [ { "id": "role_01J1F8PROJ", "name": "API Project Key Manager", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "resource_type": "api.project", "predefined_role": false, "description": "Allows managing API keys for the project", "created_at": 1711471533, "updated_at": 1711472599, "created_by": "user_abc123", "created_by_user_obj": { "id": "user_abc123", "name": "Ada Lovelace", "email": "ada@example.com" }, "metadata": {}, "assignment_sources": [ { "principal_id": "user_abc123", "principal_type": "user" } ] } ], "has_more": false, "next": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ "role_id": "role_01J1F8PROJ" }' response: | { "object": "user.role", "user": { "object": "organization.user", "id": "user_abc123", "name": "Ada Lovelace", "email": "ada@example.com", "role": "owner", "added_at": 1711470000 }, "role": { "object": "role", "id": "role_01J1F8PROJ", "name": "API Project Key Manager", "description": "Allows managing API keys for the project", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "resource_type": "api.project", "predefined_role": false } } /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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "id": "role_01J1F8PROJ", "name": "API Project Key Manager", "permissions": [ "api.organization.projects.api_keys.read", "api.organization.projects.api_keys.write" ], "resource_type": "api.project", "predefined_role": false, "description": "Allows managing API keys for the project", "created_at": 1711471533, "updated_at": 1711472599, "created_by": "user_abc123", "created_by_user_obj": null, "metadata": {}, "assignment_sources": null } 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 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" response: | { "object": "user.role.deleted", "deleted": true } /realtime/calls: post: summary: Create call description: |- Create a new Realtime API call over WebRTC and receive the SDP answer needed to 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 ephemeral **session token** and are authenticating the request with it. Realtime 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 `Location` response header includes the call ID for follow-up requests, e.g., establishing a monitoring WebSocket or hanging up the call. examples: request: curl: |- curl -X POST https://api.openai.com/v1/realtime/calls \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F "sdp=