@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api OpenAI API
@base https://api.openai.com/v1
@version 2.3.0
@auth Bearer bearer
@endpoints 148
@hint download_for_search
@toc assistants(5), audio(3), batches(4), chat(6), completions(1), embeddings(1), evals(12), files(5), fine_tuning(9), images(3), models(3), moderations(1), organization(51), realtime(2), responses(4), threads(18), uploads(4), vector_stores(16)

@group assistants
@endpoint GET /assistants
@desc Returns a list of assistants.
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., order: str(asc/desc)=desc # Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order., after: str # 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., before: str # 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.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # OK

@endpoint POST /assistants
@desc Create an assistant with a model and instructions.
@required {model: any # ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them.}
@optional {name: str # The name of the assistant. The maximum length is 256 characters., description: str # The description of the assistant. The maximum length is 512 characters., instructions: str # The system instructions that the assistant uses. The maximum length is 256,000 characters., reasoning_effort: str(low/medium/high)=medium # **o-series models only**   Constrains effort on reasoning for  [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `low`, `medium`, and `high`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response., tools: [any]= # A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`., tool_resources: map{code_interpreter: map, file_search: map} # A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters., temperature: num=1 # What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic., top_p: num=1 # An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.  We generally recommend altering this or temperature but not both., response_format: any # Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.  Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).  Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.  **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.}
@returns(200) {id: str, object: str, created_at: int, name: str?, description: str?, model: str, instructions: str?, tools: [any], tool_resources: map?{code_interpreter: map{file_ids: [str]}, file_search: map{vector_store_ids: [str]}}, metadata: map?, temperature: num?, top_p: num?, response_format: any} # OK

@endpoint GET /assistants/{assistant_id}
@desc Retrieves an assistant.
@required {assistant_id: str # The ID of the assistant to retrieve.}
@returns(200) {id: str, object: str, created_at: int, name: str?, description: str?, model: str, instructions: str?, tools: [any], tool_resources: map?{code_interpreter: map{file_ids: [str]}, file_search: map{vector_store_ids: [str]}}, metadata: map?, temperature: num?, top_p: num?, response_format: any} # OK

@endpoint POST /assistants/{assistant_id}
@desc Modifies an assistant.
@required {assistant_id: str # The ID of the assistant to modify.}
@optional {model: any # ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them., reasoning_effort: str(low/medium/high)=medium # **o-series models only**   Constrains effort on reasoning for  [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `low`, `medium`, and `high`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response., name: str # The name of the assistant. The maximum length is 256 characters., description: str # The description of the assistant. The maximum length is 512 characters., instructions: str # The system instructions that the assistant uses. The maximum length is 256,000 characters., tools: [any]= # A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`., tool_resources: map{code_interpreter: map, file_search: map} # A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters., temperature: num=1 # What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic., top_p: num=1 # An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.  We generally recommend altering this or temperature but not both., response_format: any # Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.  Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).  Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.  **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.}
@returns(200) {id: str, object: str, created_at: int, name: str?, description: str?, model: str, instructions: str?, tools: [any], tool_resources: map?{code_interpreter: map{file_ids: [str]}, file_search: map{vector_store_ids: [str]}}, metadata: map?, temperature: num?, top_p: num?, response_format: any} # OK

@endpoint DELETE /assistants/{assistant_id}
@desc Delete an assistant.
@required {assistant_id: str # The ID of the assistant to delete.}
@returns(200) {id: str, deleted: bool, object: str} # OK

@endgroup

@group audio
@endpoint POST /audio/speech
@desc Generates audio from the input text.
@required {model: any # One of the available [TTS models](/docs/models#tts): `tts-1`, `tts-1-hd` or `gpt-4o-mini-tts`., input: str # The text to generate audio for. The maximum length is 4096 characters., voice: any}
@optional {instructions: str # Control the voice of your generated audio with additional instructions. Does not work with `tts-1` or `tts-1-hd`., response_format: str(mp3/opus/aac/flac/wav/pcm)=mp3 # The format to audio in. Supported formats are `mp3`, `opus`, `aac`, `flac`, `wav`, and `pcm`., speed: num=1 # The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is the default.}
@returns(200) OK

@endpoint POST /audio/transcriptions
@desc Transcribes audio into the input language.
@returns(200) OK

@endpoint POST /audio/translations
@desc Translates audio into English.
@returns(200) OK

@endgroup

@group batches
@endpoint POST /batches
@desc Creates and executes a batch from an uploaded file of requests
@required {input_file_id: str # The ID of an uploaded file that contains requests for the new batch.  See [upload file](/docs/api-reference/files/create) for how to upload a file.  Your input file must be formatted as a [JSONL file](/docs/api-reference/batch/request-input), and must be uploaded with the purpose `batch`. The file can contain up to 50,000 requests, and can be up to 200 MB in size., endpoint: str(/v1/responses//v1/chat/completions//v1/embeddings//v1/completions) # The endpoint to be used for all requests in the batch. Currently `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported. Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch., completion_window: str # The time frame within which the batch should be processed. Currently only `24h` is supported.}
@optional {metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {id: str, object: str, endpoint: str, errors: map{object: str, data: [map]}, input_file_id: str, completion_window: str, status: str, output_file_id: str, error_file_id: str, created_at: int, in_progress_at: int, expires_at: int, finalizing_at: int, completed_at: int, failed_at: int, expired_at: int, cancelling_at: int, cancelled_at: int, request_counts: map{total: int, completed: int, failed: int}, metadata: map?} # Batch created successfully.

@endpoint GET /batches
@desc List your organization's batches.
@optional {after: str # 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., limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.}
@returns(200) {data: [map], first_id: str, last_id: str, has_more: bool, object: str} # Batch listed successfully.

@endpoint GET /batches/{batch_id}
@desc Retrieves a batch.
@required {batch_id: str # The ID of the batch to retrieve.}
@returns(200) {id: str, object: str, endpoint: str, errors: map{object: str, data: [map]}, input_file_id: str, completion_window: str, status: str, output_file_id: str, error_file_id: str, created_at: int, in_progress_at: int, expires_at: int, finalizing_at: int, completed_at: int, failed_at: int, expired_at: int, cancelling_at: int, cancelled_at: int, request_counts: map{total: int, completed: int, failed: int}, metadata: map?} # Batch retrieved successfully.

@endpoint POST /batches/{batch_id}/cancel
@desc 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.
@required {batch_id: str # The ID of the batch to cancel.}
@returns(200) {id: str, object: str, endpoint: str, errors: map{object: str, data: [map]}, input_file_id: str, completion_window: str, status: str, output_file_id: str, error_file_id: str, created_at: int, in_progress_at: int, expires_at: int, finalizing_at: int, completed_at: int, failed_at: int, expired_at: int, cancelling_at: int, cancelled_at: int, request_counts: map{total: int, completed: int, failed: int}, metadata: map?} # Batch is cancelling. Returns the cancelling batch's details.

@endgroup

@group chat
@endpoint GET /chat/completions
@desc List stored Chat Completions. Only Chat Completions that have been stored
@optional {model: str # The model used to generate the Chat Completions., metadata: map # A list of metadata keys to filter the Chat Completions by. Example:  `metadata[key1]=value1&metadata[key2]=value2`, after: str # Identifier for the last chat completion from the previous pagination request., limit: int=20 # Number of Chat Completions to retrieve., order: str(asc/desc)=asc # Sort order for Chat Completions by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # A list of Chat Completions

@endpoint POST /chat/completions
@desc **Starting a new project?** We recommend trying [Responses](/docs/api-reference/responses)
@returns(200) {id: str, choices: [map], created: int, model: str, service_tier: str?, system_fingerprint: str, object: str, usage: map{completion_tokens: int, prompt_tokens: int, total_tokens: int, completion_tokens_details: map{accepted_prediction_tokens: int, audio_tokens: int, reasoning_tokens: int, rejected_prediction_tokens: int}, prompt_tokens_details: map{audio_tokens: int, cached_tokens: int}}} # OK

@endpoint GET /chat/completions/{completion_id}
@desc Get a stored chat completion. Only Chat Completions that have been created
@required {completion_id: str # The ID of the chat completion to retrieve.}
@returns(200) {id: str, choices: [map], created: int, model: str, service_tier: str?, system_fingerprint: str, object: str, usage: map{completion_tokens: int, prompt_tokens: int, total_tokens: int, completion_tokens_details: map{accepted_prediction_tokens: int, audio_tokens: int, reasoning_tokens: int, rejected_prediction_tokens: int}, prompt_tokens_details: map{audio_tokens: int, cached_tokens: int}}} # A chat completion

@endpoint POST /chat/completions/{completion_id}
@desc Modify a stored chat completion. Only Chat Completions that have been
@required {completion_id: str # The ID of the chat completion to update., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {id: str, choices: [map], created: int, model: str, service_tier: str?, system_fingerprint: str, object: str, usage: map{completion_tokens: int, prompt_tokens: int, total_tokens: int, completion_tokens_details: map{accepted_prediction_tokens: int, audio_tokens: int, reasoning_tokens: int, rejected_prediction_tokens: int}, prompt_tokens_details: map{audio_tokens: int, cached_tokens: int}}} # A chat completion

@endpoint DELETE /chat/completions/{completion_id}
@desc Delete a stored chat completion. Only Chat Completions that have been
@required {completion_id: str # The ID of the chat completion to delete.}
@returns(200) {object: str, id: str, deleted: bool} # The chat completion was deleted successfully.

@endpoint GET /chat/completions/{completion_id}/messages
@desc Get the messages in a stored chat completion. Only Chat Completions that
@required {completion_id: str # The ID of the chat completion to retrieve messages from.}
@optional {after: str # Identifier for the last message from the previous pagination request., limit: int=20 # Number of messages to retrieve., order: str(asc/desc)=asc # Sort order for messages by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.}
@returns(200) {object: str, data: [any], first_id: str, last_id: str, has_more: bool} # A list of messages

@endgroup

@group completions
@endpoint POST /completions
@desc Creates a completion for the provided prompt and parameters.
@required {model: any # ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them., prompt: any=<|endoftext|> # The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.  Note that  is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document.}
@optional {best_of: int=1 # Generates `best_of` completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed.  When used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`.  **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`., echo: bool=false # Echo back the prompt in addition to the completion, frequency_penalty: num=0 # Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.  [See more information about frequency and presence penalties.](/docs/guides/text-generation), logit_bias: map=null # Modify the likelihood of specified tokens appearing in the completion.  Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this [tokenizer tool](/tokenizer?view=bpe) to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.  As an example, you can pass `{"50256": -100}` to prevent the  token from being generated., logprobs: int=null # Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response.  The maximum value for `logprobs` is 5., max_tokens: int=16 # The maximum number of [tokens](/tokenizer) that can be generated in the completion.  The token count of your prompt plus `max_tokens` cannot exceed the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens., n: int=1 # How many completions to generate for each prompt.  **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`., presence_penalty: num=0 # Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.  [See more information about frequency and presence penalties.](/docs/guides/text-generation), seed: int(int64) # If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result.  Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend., stop: any=null # Not supported with latest reasoning models `o3` and `o4-mini`.  Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence., stream: bool=false # Whether to stream back partial progress. If set, tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions)., stream_options: map{include_usage: bool}=null # Options for streaming response. Only set this when you set `stream: true`., suffix: str=null # The suffix that comes after a completion of inserted text.  This parameter is only supported for `gpt-3.5-turbo-instruct`., temperature: num=1 # What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.  We generally recommend altering this or `top_p` but not both., top_p: num=1 # An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.  We generally recommend altering this or `temperature` but not both., user: str # A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).}
@returns(200) {id: str, choices: [map], created: int, model: str, system_fingerprint: str, object: str, usage: map{completion_tokens: int, prompt_tokens: int, total_tokens: int, completion_tokens_details: map{accepted_prediction_tokens: int, audio_tokens: int, reasoning_tokens: int, rejected_prediction_tokens: int}, prompt_tokens_details: map{audio_tokens: int, cached_tokens: int}}} # OK

@endgroup

@group embeddings
@endpoint POST /embeddings
@desc Creates an embedding vector representing the input text.
@required {input: any # Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (8192 tokens for `text-embedding-ada-002`), cannot be an empty string, and any array must be 2048 dimensions or less. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. Some models may also impose a limit on total number of tokens summed across inputs., model: any # ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them.}
@optional {encoding_format: str(float/base64)=float # The format to return the embeddings in. Can be either `float` or [`base64`](https://pypi.org/project/pybase64/)., dimensions: int # The number of dimensions the resulting output embeddings should have. Only supported in `text-embedding-3` and later models., user: str # A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).}
@returns(200) {data: [map], model: str, object: str, usage: map{prompt_tokens: int, total_tokens: int}} # OK

@endgroup

@group evals
@endpoint GET /evals
@desc List evaluations for a project.
@optional {after: str # Identifier for the last eval from the previous pagination request., limit: int=20 # Number of evals to retrieve., order: str(asc/desc)=asc # Sort order for evals by timestamp. Use `asc` for ascending order or `desc` for descending order., order_by: str(created_at/updated_at)=created_at # Evals can be ordered by creation time or last updated time. Use `created_at` for creation time or `updated_at` for last updated time.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # A list of evals

@endpoint POST /evals
@desc Create the structure of an evaluation that can be used to test a model's performance.
@required {data_source_config: map # The configuration for the data source used for the evaluation runs., testing_criteria: [any] # A list of graders for all eval runs in this group.}
@optional {name: str # The name of the evaluation., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(201) {object: str, id: str, name: str, data_source_config: map, testing_criteria: [any], created_at: int, metadata: map?} # OK

@endpoint GET /evals/{eval_id}
@desc Get an evaluation by ID.
@required {eval_id: str # The ID of the evaluation to retrieve.}
@returns(200) {object: str, id: str, name: str, data_source_config: map, testing_criteria: [any], created_at: int, metadata: map?} # The evaluation

@endpoint POST /evals/{eval_id}
@desc Update certain properties of an evaluation.
@required {eval_id: str # The ID of the evaluation to update.}
@optional {name: str # Rename the evaluation., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {object: str, id: str, name: str, data_source_config: map, testing_criteria: [any], created_at: int, metadata: map?} # The updated evaluation

@endpoint DELETE /evals/{eval_id}
@desc Delete an evaluation.
@required {eval_id: str # The ID of the evaluation to delete.}
@returns(200) {object: str, deleted: bool, eval_id: str} # Successfully deleted the evaluation.
@errors {404: Evaluation not found.}

@endpoint GET /evals/{eval_id}/runs
@desc Get a list of runs for an evaluation.
@required {eval_id: str # The ID of the evaluation to retrieve runs for.}
@optional {after: str # Identifier for the last run from the previous pagination request., limit: int=20 # Number of runs to retrieve., order: str(asc/desc)=asc # Sort order for runs by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`., status: str(queued/in_progress/completed/canceled/failed) # Filter runs by status. One of `queued` | `in_progress` | `failed` | `completed` | `canceled`.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # A list of runs for the evaluation

@endpoint POST /evals/{eval_id}/runs
@desc Create a new evaluation run. This is the endpoint that will kick off grading.
@required {eval_id: str # The ID of the evaluation to create a run for., data_source: map # Details about the run's data source.}
@optional {name: str # The name of the run., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(201) {object: str, id: str, eval_id: str, status: str, model: str, name: str, created_at: int, report_url: str, result_counts: map{total: int, errored: int, failed: int, passed: int}, per_model_usage: [map], per_testing_criteria_results: [map], data_source: map, metadata: map?, error: map{code: str, message: str}} # Successfully created a run for the evaluation
@errors {400: Bad request (for example, missing eval object)}

@endpoint GET /evals/{eval_id}/runs/{run_id}
@desc Get an evaluation run by ID.
@required {eval_id: str # The ID of the evaluation to retrieve runs for., run_id: str # The ID of the run to retrieve.}
@returns(200) {object: str, id: str, eval_id: str, status: str, model: str, name: str, created_at: int, report_url: str, result_counts: map{total: int, errored: int, failed: int, passed: int}, per_model_usage: [map], per_testing_criteria_results: [map], data_source: map, metadata: map?, error: map{code: str, message: str}} # The evaluation run

@endpoint POST /evals/{eval_id}/runs/{run_id}
@desc Cancel an ongoing evaluation run.
@required {eval_id: str # The ID of the evaluation whose run you want to cancel., run_id: str # The ID of the run to cancel.}
@returns(200) {object: str, id: str, eval_id: str, status: str, model: str, name: str, created_at: int, report_url: str, result_counts: map{total: int, errored: int, failed: int, passed: int}, per_model_usage: [map], per_testing_criteria_results: [map], data_source: map, metadata: map?, error: map{code: str, message: str}} # The canceled eval run object

@endpoint DELETE /evals/{eval_id}/runs/{run_id}
@desc Delete an eval run.
@required {eval_id: str # The ID of the evaluation to delete the run from., run_id: str # The ID of the run to delete.}
@returns(200) {object: str, deleted: bool, run_id: str} # Successfully deleted the eval run
@errors {404: Run not found}

@endpoint GET /evals/{eval_id}/runs/{run_id}/output_items
@desc Get a list of output items for an evaluation run.
@required {eval_id: str # The ID of the evaluation to retrieve runs for., run_id: str # The ID of the run to retrieve output items for.}
@optional {after: str # Identifier for the last output item from the previous pagination request., limit: int=20 # Number of output items to retrieve., status: str(fail/pass) # Filter output items by status. Use `failed` to filter by failed output items or `pass` to filter by passed output items., order: str(asc/desc)=asc # Sort order for output items by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # A list of output items for the evaluation run

@endpoint GET /evals/{eval_id}/runs/{run_id}/output_items/{output_item_id}
@desc Get an evaluation run output item by ID.
@required {eval_id: str # The ID of the evaluation to retrieve runs for., run_id: str # The ID of the run to retrieve., output_item_id: str # The ID of the output item to retrieve.}
@returns(200) {object: str, id: str, run_id: str, eval_id: str, created_at: int, status: str, datasource_item_id: int, datasource_item: map, results: [map], sample: map{input: [map], output: [map], finish_reason: str, model: str, usage: map{total_tokens: int, completion_tokens: int, prompt_tokens: int, cached_tokens: int}, error: map{code: str, message: str}, temperature: num, max_completion_tokens: int, top_p: num, seed: int}} # The evaluation run output item

@endgroup

@group files
@endpoint GET /files
@desc Returns a list of files.
@optional {purpose: str # Only return files with the given purpose., limit: int=10000 # A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000., order: str(asc/desc)=desc # Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order., after: str # 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.}
@returns(200) {object: str, data: [any], first_id: str, last_id: str, has_more: bool} # OK

@endpoint POST /files
@desc Upload a file that can be used across various endpoints. Individual files can be up to 512 MB, and the size of all files uploaded by one organization can be up to 100 GB.
@returns(200) {id: str, bytes: int, created_at: int, expires_at: int, filename: str, object: str, purpose: str, status: str, status_details: str} # OK

@endpoint DELETE /files/{file_id}
@desc Delete a file.
@required {file_id: str # The ID of the file to use for this request.}
@returns(200) {id: str, object: str, deleted: bool} # OK

@endpoint GET /files/{file_id}
@desc Returns information about a specific file.
@required {file_id: str # The ID of the file to use for this request.}
@returns(200) {id: str, bytes: int, created_at: int, expires_at: int, filename: str, object: str, purpose: str, status: str, status_details: str} # OK

@endpoint GET /files/{file_id}/content
@desc Returns the contents of the specified file.
@required {file_id: str # The ID of the file to use for this request.}
@returns(200) OK

@endgroup

@group fine_tuning
@endpoint GET /fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions
@desc **NOTE:** This endpoint requires an [admin API key](../admin-api-keys).
@required {fine_tuned_model_checkpoint: str # The ID of the fine-tuned model checkpoint to get permissions for.}
@optional {project_id: str # The ID of the project to get permissions for., after: str # Identifier for the last permission ID from the previous pagination request., limit: int=10 # Number of permissions to retrieve., order: str(ascending/descending)=descending # The order in which to retrieve permissions.}
@returns(200) {data: [map], object: str, first_id: str?, last_id: str?, has_more: bool} # OK

@endpoint POST /fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions
@desc **NOTE:** Calling this endpoint requires an [admin API key](../admin-api-keys).
@required {fine_tuned_model_checkpoint: str # The ID of the fine-tuned model checkpoint to create a permission for., project_ids: [str] # The project identifiers to grant access to.}
@returns(200) {data: [map], object: str, first_id: str?, last_id: str?, has_more: bool} # OK

@endpoint DELETE /fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions/{permission_id}
@desc **NOTE:** This endpoint requires an [admin API key](../admin-api-keys).
@required {fine_tuned_model_checkpoint: str # The ID of the fine-tuned model checkpoint to delete a permission for., permission_id: str # The ID of the fine-tuned model checkpoint permission to delete.}
@returns(200) {id: str, object: str, deleted: bool} # OK

@endpoint POST /fine_tuning/jobs
@desc Creates a fine-tuning job which begins the process of creating a new model from a given dataset.
@required {model: any # The name of the model to fine-tune. You can select one of the [supported models](/docs/guides/fine-tuning#which-models-can-be-fine-tuned)., training_file: str # The ID of an uploaded file that contains training data.  See [upload file](/docs/api-reference/files/create) for how to upload a file.  Your dataset must be formatted as a JSONL file. Additionally, you must upload your file with the purpose `fine-tune`.  The contents of the file should differ depending on if the model uses the [chat](/docs/api-reference/fine-tuning/chat-input), [completions](/docs/api-reference/fine-tuning/completions-input) format, or if the fine-tuning method uses the [preference](/docs/api-reference/fine-tuning/preference-input) format.  See the [fine-tuning guide](/docs/guides/fine-tuning) for more details.}
@optional {hyperparameters: map{batch_size: any, learning_rate_multiplier: any, n_epochs: any} # The hyperparameters used for the fine-tuning job. This value is now deprecated in favor of `method`, and should be passed in under the `method` parameter., suffix: str=null # A string of up to 64 characters that will be added to your fine-tuned model name.  For example, a `suffix` of "custom-model-name" would produce a model name like `ft:gpt-4o-mini:openai:custom-model-name:7p4lURel`., validation_file: str # The ID of an uploaded file that contains validation data.  If you provide this file, the data is used to generate validation metrics periodically during fine-tuning. These metrics can be viewed in the fine-tuning results file. The same data should not be present in both train and validation files.  Your dataset must be formatted as a JSONL file. You must upload your file with the purpose `fine-tune`.  See the [fine-tuning guide](/docs/guides/fine-tuning) for more details., integrations: [map{type!: any, wandb!: map}] # A list of integrations to enable for your fine-tuning job., seed: int # The seed controls the reproducibility of the job. Passing in the same seed and job parameters should produce the same results, but may differ in rare cases. If a seed is not specified, one will be generated for you., method: map{type: str, supervised: map, dpo: map} # The method used for fine-tuning., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {id: str, created_at: int, error: map?{code: str, message: str, param: str?}, fine_tuned_model: str?, finished_at: int?, hyperparameters: map{batch_size: any, learning_rate_multiplier: any, n_epochs: any}, model: str, object: str, organization_id: str, result_files: [str], status: str, trained_tokens: int?, training_file: str, validation_file: str?, integrations: [any]?, seed: int, estimated_finish: int?, method: map{type: str, supervised: map{hyperparameters: map{batch_size: any, learning_rate_multiplier: any, n_epochs: any}}, dpo: map{hyperparameters: map{beta: any, batch_size: any, learning_rate_multiplier: any, n_epochs: any}}}, metadata: map?} # OK

@endpoint GET /fine_tuning/jobs
@desc List your organization's fine-tuning jobs
@optional {after: str # Identifier for the last job from the previous pagination request., limit: int=20 # Number of fine-tuning jobs to retrieve., metadata: map # Optional metadata filter. To filter, use the syntax `metadata[k]=v`. Alternatively, set `metadata=null` to indicate no metadata.}
@returns(200) {data: [map], has_more: bool, object: str} # OK

@endpoint GET /fine_tuning/jobs/{fine_tuning_job_id}
@desc Get info about a fine-tuning job.
@required {fine_tuning_job_id: str # The ID of the fine-tuning job.}
@returns(200) {id: str, created_at: int, error: map?{code: str, message: str, param: str?}, fine_tuned_model: str?, finished_at: int?, hyperparameters: map{batch_size: any, learning_rate_multiplier: any, n_epochs: any}, model: str, object: str, organization_id: str, result_files: [str], status: str, trained_tokens: int?, training_file: str, validation_file: str?, integrations: [any]?, seed: int, estimated_finish: int?, method: map{type: str, supervised: map{hyperparameters: map{batch_size: any, learning_rate_multiplier: any, n_epochs: any}}, dpo: map{hyperparameters: map{beta: any, batch_size: any, learning_rate_multiplier: any, n_epochs: any}}}, metadata: map?} # OK

@endpoint POST /fine_tuning/jobs/{fine_tuning_job_id}/cancel
@desc Immediately cancel a fine-tune job.
@required {fine_tuning_job_id: str # The ID of the fine-tuning job to cancel.}
@returns(200) {id: str, created_at: int, error: map?{code: str, message: str, param: str?}, fine_tuned_model: str?, finished_at: int?, hyperparameters: map{batch_size: any, learning_rate_multiplier: any, n_epochs: any}, model: str, object: str, organization_id: str, result_files: [str], status: str, trained_tokens: int?, training_file: str, validation_file: str?, integrations: [any]?, seed: int, estimated_finish: int?, method: map{type: str, supervised: map{hyperparameters: map{batch_size: any, learning_rate_multiplier: any, n_epochs: any}}, dpo: map{hyperparameters: map{beta: any, batch_size: any, learning_rate_multiplier: any, n_epochs: any}}}, metadata: map?} # OK

@endpoint GET /fine_tuning/jobs/{fine_tuning_job_id}/checkpoints
@desc List checkpoints for a fine-tuning job.
@required {fine_tuning_job_id: str # The ID of the fine-tuning job to get checkpoints for.}
@optional {after: str # Identifier for the last checkpoint ID from the previous pagination request., limit: int=10 # Number of checkpoints to retrieve.}
@returns(200) {data: [map], object: str, first_id: str?, last_id: str?, has_more: bool} # OK

@endpoint GET /fine_tuning/jobs/{fine_tuning_job_id}/events
@desc Get status updates for a fine-tuning job.
@required {fine_tuning_job_id: str # The ID of the fine-tuning job to get events for.}
@optional {after: str # Identifier for the last event from the previous pagination request., limit: int=20 # Number of events to retrieve.}
@returns(200) {data: [map], object: str, has_more: bool} # OK

@endgroup

@group images
@endpoint POST /images/edits
@desc Creates an edited or extended image given one or more source images and a prompt. This endpoint only supports `gpt-image-1` and `dall-e-2`.
@returns(200) {created: int, data: [map], usage: map{total_tokens: int, input_tokens: int, output_tokens: int, input_tokens_details: map{text_tokens: int, image_tokens: int}}} # OK

@endpoint POST /images/generations
@desc Creates an image given a prompt. [Learn more](/docs/guides/images).
@required {prompt: str # A text description of the desired image(s). The maximum length is 32000 characters for `gpt-image-1`, 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`.}
@optional {model: any=dall-e-2 # The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or `gpt-image-1`. Defaults to `dall-e-2` unless a parameter specific to `gpt-image-1` is used., n: int=1 # The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported., quality: str(standard/hd/low/medium/high/auto)=auto # The quality of the image that will be generated.   - `auto` (default value) will automatically select the best quality for the given model. - `high`, `medium` and `low` are supported for `gpt-image-1`. - `hd` and `standard` are supported for `dall-e-3`. - `standard` is the only option for `dall-e-2`., response_format: str(url/b64_json)=url # The format in which generated images with `dall-e-2` and `dall-e-3` are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter isn't supported for `gpt-image-1` which will always return base64-encoded images., output_format: str(png/jpeg/webp)=png # The format in which the generated images are returned. This parameter is only supported for `gpt-image-1`. Must be one of `png`, `jpeg`, or `webp`., output_compression: int=100 # The compression level (0-100%) for the generated images. This parameter is only supported for `gpt-image-1` with the `webp` or `jpeg` output formats, and defaults to 100., size: str(auto/1024x1024/1536x1024/1024x1536/256x256/512x512/1792x1024/1024x1792)=auto # The size of the generated images. Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default value) for `gpt-image-1`, one of `256x256`, `512x512`, or `1024x1024` for `dall-e-2`, and one of `1024x1024`, `1792x1024`, or `1024x1792` for `dall-e-3`., moderation: str(low/auto)=auto # Control the content-moderation level for images generated by `gpt-image-1`. Must be either `low` for less restrictive filtering or `auto` (default value)., background: str(transparent/opaque/auto)=auto # Allows to set transparency for the background of the generated image(s).  This parameter is only supported for `gpt-image-1`. Must be one of  `transparent`, `opaque` or `auto` (default value). When `auto` is used, the  model will automatically determine the best background for the image.  If `transparent`, the output format needs to support transparency, so it  should be set to either `png` (default value) or `webp`., style: str(vivid/natural)=vivid # The style of the generated images. This parameter is only supported for `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images., user: str # A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).}
@returns(200) {created: int, data: [map], usage: map{total_tokens: int, input_tokens: int, output_tokens: int, input_tokens_details: map{text_tokens: int, image_tokens: int}}} # OK

@endpoint POST /images/variations
@desc Creates a variation of a given image. This endpoint only supports `dall-e-2`.
@returns(200) {created: int, data: [map], usage: map{total_tokens: int, input_tokens: int, output_tokens: int, input_tokens_details: map{text_tokens: int, image_tokens: int}}} # OK

@endgroup

@group models
@endpoint GET /models
@desc Lists the currently available models, and provides basic information about each one such as the owner and availability.
@returns(200) {object: str, data: [any]} # OK

@endpoint GET /models/{model}
@desc Retrieves a model instance, providing basic information about the model such as the owner and permissioning.
@required {model: str # The ID of the model to use for this request}
@returns(200) {id: str, created: int, object: str, owned_by: str} # OK

@endpoint DELETE /models/{model}
@desc Delete a fine-tuned model. You must have the Owner role in your organization to delete a model.
@required {model: str # The model to delete}
@returns(200) {id: str, deleted: bool, object: str} # OK

@endgroup

@group moderations
@endpoint POST /moderations
@desc Classifies if text and/or image inputs are potentially harmful. Learn
@required {input: any # Input (or inputs) to classify. Can be a single string, an array of strings, or an array of multi-modal input objects similar to other models.}
@optional {model: any=omni-moderation-latest # The content moderation model you would like to use. Learn more in [the moderation guide](/docs/guides/moderation), and learn about available models [here](/docs/models#moderation).}
@returns(200) {id: str, model: str, results: [map]} # OK

@endgroup

@group organization
@endpoint GET /organization/admin_api_keys
@desc List organization API keys
@optional {after: str, order: str(asc/desc)=asc, limit: int=20}
@returns(200) {object: str, data: [map], has_more: bool, first_id: str, last_id: str} # A list of organization API keys.

@endpoint POST /organization/admin_api_keys
@desc Create an organization admin API key
@required {name: str}
@returns(200) {object: str, id: str, name: str, redacted_value: str, value: str, created_at: int(int64), last_used_at: int(int64)?, owner: map{type: str, object: str, id: str, name: str, created_at: int(int64), role: str}} # The newly created admin API key.

@endpoint GET /organization/admin_api_keys/{key_id}
@desc Retrieve a single organization API key
@required {key_id: str}
@returns(200) {object: str, id: str, name: str, redacted_value: str, value: str, created_at: int(int64), last_used_at: int(int64)?, owner: map{type: str, object: str, id: str, name: str, created_at: int(int64), role: str}} # Details of the requested API key.

@endpoint DELETE /organization/admin_api_keys/{key_id}
@desc Delete an organization admin API key
@required {key_id: str}
@returns(200) {id: str, object: str, deleted: bool} # Confirmation that the API key was deleted.

@endpoint GET /organization/audit_logs
@desc List user actions and configuration changes within this organization.
@optional {effective_at: map # Return only events whose `effective_at` (Unix seconds) is in this range., project_ids[]: [str] # Return only events for these projects., event_types[]: [str] # Return only events with a `type` in one of these values. For example, `project.created`. For all options, see the documentation for the [audit log object](/docs/api-reference/audit-logs/object)., actor_ids[]: [str] # Return only events performed by these actors. Can be a user ID, a service account ID, or an api key tracking ID., actor_emails[]: [str] # Return only events performed by users with these emails., resource_ids[]: [str] # Return only events performed on these targets. For example, a project ID updated., limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., after: str # 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., before: str # 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.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # Audit logs listed successfully.

@endpoint GET /organization/certificates
@desc List uploaded certificates for this organization.
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., after: str # 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., order: str(asc/desc)=desc # Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.}
@returns(200) {data: [map], first_id: str, last_id: str, has_more: bool, object: str} # Certificates listed successfully.

@endpoint POST /organization/certificates
@desc Upload a certificate to the organization. This does **not** automatically activate the certificate.
@required {content: str # The certificate content in PEM format}
@optional {name: str # An optional name for the certificate}
@returns(200) {object: str, id: str, name: str, created_at: int, certificate_details: map{valid_at: int, expires_at: int, content: str}, active: bool} # Certificate uploaded successfully.

@endpoint POST /organization/certificates/activate
@desc Activate certificates at the organization level.
@required {certificate_ids: [str]}
@returns(200) {data: [map], first_id: str, last_id: str, has_more: bool, object: str} # Certificates activated successfully.

@endpoint POST /organization/certificates/deactivate
@desc Deactivate certificates at the organization level.
@required {certificate_ids: [str]}
@returns(200) {data: [map], first_id: str, last_id: str, has_more: bool, object: str} # Certificates deactivated successfully.

@endpoint GET /organization/certificates/{certificate_id}
@desc Get a certificate that has been uploaded to the organization.
@required {cert_id: str # Unique ID of the certificate to retrieve.}
@optional {include: [str] # 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.}
@returns(200) {object: str, id: str, name: str, created_at: int, certificate_details: map{valid_at: int, expires_at: int, content: str}, active: bool} # Certificate retrieved successfully.

@endpoint POST /organization/certificates/{certificate_id}
@desc Modify a certificate. Note that only the name can be modified.
@required {name: str # The updated name for the certificate}
@returns(200) {object: str, id: str, name: str, created_at: int, certificate_details: map{valid_at: int, expires_at: int, content: str}, active: bool} # Certificate modified successfully.

@endpoint DELETE /organization/certificates/{certificate_id}
@desc Delete a certificate from the organization.
@returns(200) {object: str, id: str} # Certificate deleted successfully.

@endpoint GET /organization/costs
@desc Get costs details for the organization.
@required {start_time: int # Start time (Unix seconds) of the query time range, inclusive.}
@optional {end_time: int # End time (Unix seconds) of the query time range, exclusive., bucket_width: str=1d # Width of each time bucket in response. Currently only `1d` is supported, default to `1d`., project_ids: [str] # Return only costs for these projects., group_by: [str] # Group the costs by the specified fields. Support fields include `project_id`, `line_item` and any combination of them., limit: int=7 # A limit on the number of buckets to be returned. Limit can range between 1 and 180, and the default is 7., page: str # A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.}
@returns(200) {object: str, data: [map], has_more: bool, next_page: str} # Costs data retrieved successfully.

@endpoint GET /organization/invites
@desc Returns a list of invites in the organization.
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., after: str # 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.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # Invites listed successfully.

@endpoint POST /organization/invites
@desc Create an invite for a user to the organization. The invite must be accepted by the user before they have access to the organization.
@required {email: str # Send an email to this address, role: str(reader/owner) # `owner` or `reader`}
@optional {projects: [map{id!: str, role!: str}] # An array of projects to which membership is granted at the same time the org invite is accepted. If omitted, the user will be invited to the default project for compatibility with legacy behavior.}
@returns(200) {object: str, id: str, email: str, role: str, status: str, invited_at: int, expires_at: int, accepted_at: int, projects: [map]} # User invited successfully.

@endpoint GET /organization/invites/{invite_id}
@desc Retrieves an invite.
@required {invite_id: str # The ID of the invite to retrieve.}
@returns(200) {object: str, id: str, email: str, role: str, status: str, invited_at: int, expires_at: int, accepted_at: int, projects: [map]} # Invite retrieved successfully.

@endpoint DELETE /organization/invites/{invite_id}
@desc Delete an invite. If the invite has already been accepted, it cannot be deleted.
@required {invite_id: str # The ID of the invite to delete.}
@returns(200) {object: str, id: str, deleted: bool} # Invite deleted successfully.

@endpoint GET /organization/projects
@desc Returns a list of projects.
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., after: str # 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., include_archived: bool=false # If `true` returns all projects including those that have been `archived`. Archived projects are not included by default.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # Projects listed successfully.

@endpoint POST /organization/projects
@desc Create a new project in the organization. Projects can be created and archived, but cannot be deleted.
@required {name: str # The friendly name of the project, this name appears in reports.}
@returns(200) {id: str, object: str, name: str, created_at: int, archived_at: int?, status: str} # Project created successfully.

@endpoint GET /organization/projects/{project_id}
@desc Retrieves a project.
@required {project_id: str # The ID of the project.}
@returns(200) {id: str, object: str, name: str, created_at: int, archived_at: int?, status: str} # Project retrieved successfully.

@endpoint POST /organization/projects/{project_id}
@desc Modifies a project in the organization.
@required {project_id: str # The ID of the project., name: str # The updated name of the project, this name appears in reports.}
@returns(200) {id: str, object: str, name: str, created_at: int, archived_at: int?, status: str} # Project updated successfully.
@errors {400: Error response when updating the default project.}

@endpoint GET /organization/projects/{project_id}/api_keys
@desc Returns a list of API keys in the project.
@required {project_id: str # The ID of the project.}
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., after: str # 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.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # Project API keys listed successfully.

@endpoint GET /organization/projects/{project_id}/api_keys/{key_id}
@desc Retrieves an API key in the project.
@required {project_id: str # The ID of the project., key_id: str # The ID of the API key.}
@returns(200) {object: str, redacted_value: str, name: str, created_at: int, last_used_at: int, id: str, owner: map{type: str, user: map{object: str, id: str, name: str, email: str, role: str, added_at: int}, service_account: map{object: str, id: str, name: str, role: str, created_at: int}}} # Project API key retrieved successfully.

@endpoint DELETE /organization/projects/{project_id}/api_keys/{key_id}
@desc Deletes an API key from the project.
@required {project_id: str # The ID of the project., key_id: str # The ID of the API key.}
@returns(200) {object: str, id: str, deleted: bool} # Project API key deleted successfully.
@errors {400: Error response for various conditions.}

@endpoint POST /organization/projects/{project_id}/archive
@desc Archives a project in the organization. Archived projects cannot be used or updated.
@required {project_id: str # The ID of the project.}
@returns(200) {id: str, object: str, name: str, created_at: int, archived_at: int?, status: str} # Project archived successfully.

@endpoint GET /organization/projects/{project_id}/certificates
@desc List certificates for this project.
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., after: str # 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., order: str(asc/desc)=desc # Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.}
@returns(200) {data: [map], first_id: str, last_id: str, has_more: bool, object: str} # Certificates listed successfully.

@endpoint POST /organization/projects/{project_id}/certificates/activate
@desc Activate certificates at the project level.
@required {certificate_ids: [str]}
@returns(200) {data: [map], first_id: str, last_id: str, has_more: bool, object: str} # Certificates activated successfully.

@endpoint POST /organization/projects/{project_id}/certificates/deactivate
@desc Deactivate certificates at the project level.
@required {certificate_ids: [str]}
@returns(200) {data: [map], first_id: str, last_id: str, has_more: bool, object: str} # Certificates deactivated successfully.

@endpoint GET /organization/projects/{project_id}/rate_limits
@desc Returns the rate limits per model for a project.
@required {project_id: str # The ID of the project.}
@optional {limit: int=100 # A limit on the number of objects to be returned. The default is 100., after: str # 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., before: str # 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.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # Project rate limits listed successfully.

@endpoint POST /organization/projects/{project_id}/rate_limits/{rate_limit_id}
@desc Updates a project rate limit.
@required {project_id: str # The ID of the project., rate_limit_id: str # The ID of the rate limit.}
@optional {max_requests_per_1_minute: int # The maximum requests per minute., max_tokens_per_1_minute: int # The maximum tokens per minute., max_images_per_1_minute: int # The maximum images per minute. Only relevant for certain models., max_audio_megabytes_per_1_minute: int # The maximum audio megabytes per minute. Only relevant for certain models., max_requests_per_1_day: int # The maximum requests per day. Only relevant for certain models., batch_1_day_max_input_tokens: int # The maximum batch input tokens per day. Only relevant for certain models.}
@returns(200) {object: str, id: str, model: str, max_requests_per_1_minute: int, max_tokens_per_1_minute: int, max_images_per_1_minute: int, max_audio_megabytes_per_1_minute: int, max_requests_per_1_day: int, batch_1_day_max_input_tokens: int} # Project rate limit updated successfully.
@errors {400: Error response for various conditions.}

@endpoint GET /organization/projects/{project_id}/service_accounts
@desc Returns a list of service accounts in the project.
@required {project_id: str # The ID of the project.}
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., after: str # 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.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # Project service accounts listed successfully.
@errors {400: Error response when project is archived.}

@endpoint POST /organization/projects/{project_id}/service_accounts
@desc Creates a new service account in the project. This also returns an unredacted API key for the service account.
@required {project_id: str # The ID of the project., name: str # The name of the service account being created.}
@returns(200) {object: str, id: str, name: str, role: str, created_at: int, api_key: map{object: str, value: str, name: str, created_at: int, id: str}} # Project service account created successfully.
@errors {400: Error response when project is archived.}

@endpoint GET /organization/projects/{project_id}/service_accounts/{service_account_id}
@desc Retrieves a service account in the project.
@required {project_id: str # The ID of the project., service_account_id: str # The ID of the service account.}
@returns(200) {object: str, id: str, name: str, role: str, created_at: int} # Project service account retrieved successfully.

@endpoint DELETE /organization/projects/{project_id}/service_accounts/{service_account_id}
@desc Deletes a service account from the project.
@required {project_id: str # The ID of the project., service_account_id: str # The ID of the service account.}
@returns(200) {object: str, id: str, deleted: bool} # Project service account deleted successfully.

@endpoint GET /organization/projects/{project_id}/users
@desc Returns a list of users in the project.
@required {project_id: str # The ID of the project.}
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., after: str # 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.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # Project users listed successfully.
@errors {400: Error response when project is archived.}

@endpoint POST /organization/projects/{project_id}/users
@desc Adds a user to the project. Users must already be members of the organization to be added to a project.
@required {project_id: str # The ID of the project., user_id: str # The ID of the user., role: str(owner/member) # `owner` or `member`}
@returns(200) {object: str, id: str, name: str, email: str, role: str, added_at: int} # User added to project successfully.
@errors {400: Error response for various conditions.}

@endpoint GET /organization/projects/{project_id}/users/{user_id}
@desc Retrieves a user in the project.
@required {project_id: str # The ID of the project., user_id: str # The ID of the user.}
@returns(200) {object: str, id: str, name: str, email: str, role: str, added_at: int} # Project user retrieved successfully.

@endpoint POST /organization/projects/{project_id}/users/{user_id}
@desc Modifies a user's role in the project.
@required {project_id: str # The ID of the project., user_id: str # The ID of the user., role: str(owner/member) # `owner` or `member`}
@returns(200) {object: str, id: str, name: str, email: str, role: str, added_at: int} # Project user's role updated successfully.
@errors {400: Error response for various conditions.}

@endpoint DELETE /organization/projects/{project_id}/users/{user_id}
@desc Deletes a user from the project.
@required {project_id: str # The ID of the project., user_id: str # The ID of the user.}
@returns(200) {object: str, id: str, deleted: bool} # Project user deleted successfully.
@errors {400: Error response for various conditions.}

@endpoint GET /organization/usage/audio_speeches
@desc Get audio speeches usage details for the organization.
@required {start_time: int # Start time (Unix seconds) of the query time range, inclusive.}
@optional {end_time: int # End time (Unix seconds) of the query time range, exclusive., bucket_width: str(1m/1h/1d)=1d # Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`., project_ids: [str] # Return only usage for these projects., user_ids: [str] # Return only usage for these users., api_key_ids: [str] # Return only usage for these API keys., models: [str] # Return only usage for these models., group_by: [str] # Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them., limit: int # 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, page: str # A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.}
@returns(200) {object: str, data: [map], has_more: bool, next_page: str} # Usage data retrieved successfully.

@endpoint GET /organization/usage/audio_transcriptions
@desc Get audio transcriptions usage details for the organization.
@required {start_time: int # Start time (Unix seconds) of the query time range, inclusive.}
@optional {end_time: int # End time (Unix seconds) of the query time range, exclusive., bucket_width: str(1m/1h/1d)=1d # Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`., project_ids: [str] # Return only usage for these projects., user_ids: [str] # Return only usage for these users., api_key_ids: [str] # Return only usage for these API keys., models: [str] # Return only usage for these models., group_by: [str] # Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them., limit: int # 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, page: str # A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.}
@returns(200) {object: str, data: [map], has_more: bool, next_page: str} # Usage data retrieved successfully.

@endpoint GET /organization/usage/code_interpreter_sessions
@desc Get code interpreter sessions usage details for the organization.
@required {start_time: int # Start time (Unix seconds) of the query time range, inclusive.}
@optional {end_time: int # End time (Unix seconds) of the query time range, exclusive., bucket_width: str(1m/1h/1d)=1d # Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`., project_ids: [str] # Return only usage for these projects., group_by: [str] # Group the usage data by the specified fields. Support fields include `project_id`., limit: int # 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, page: str # A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.}
@returns(200) {object: str, data: [map], has_more: bool, next_page: str} # Usage data retrieved successfully.

@endpoint GET /organization/usage/completions
@desc Get completions usage details for the organization.
@required {start_time: int # Start time (Unix seconds) of the query time range, inclusive.}
@optional {end_time: int # End time (Unix seconds) of the query time range, exclusive., bucket_width: str(1m/1h/1d)=1d # Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`., project_ids: [str] # Return only usage for these projects., user_ids: [str] # Return only usage for these users., api_key_ids: [str] # Return only usage for these API keys., models: [str] # Return only usage for these models., batch: bool # If `true`, return batch jobs only. If `false`, return non-batch jobs only. By default, return both., group_by: [str] # Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model`, `batch` or any combination of them., limit: int # 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, page: str # A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.}
@returns(200) {object: str, data: [map], has_more: bool, next_page: str} # Usage data retrieved successfully.

@endpoint GET /organization/usage/embeddings
@desc Get embeddings usage details for the organization.
@required {start_time: int # Start time (Unix seconds) of the query time range, inclusive.}
@optional {end_time: int # End time (Unix seconds) of the query time range, exclusive., bucket_width: str(1m/1h/1d)=1d # Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`., project_ids: [str] # Return only usage for these projects., user_ids: [str] # Return only usage for these users., api_key_ids: [str] # Return only usage for these API keys., models: [str] # Return only usage for these models., group_by: [str] # Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them., limit: int # 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, page: str # A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.}
@returns(200) {object: str, data: [map], has_more: bool, next_page: str} # Usage data retrieved successfully.

@endpoint GET /organization/usage/images
@desc Get images usage details for the organization.
@required {start_time: int # Start time (Unix seconds) of the query time range, inclusive.}
@optional {end_time: int # End time (Unix seconds) of the query time range, exclusive., bucket_width: str(1m/1h/1d)=1d # Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`., sources: [str] # Return only usages for these sources. Possible values are `image.generation`, `image.edit`, `image.variation` or any combination of them., sizes: [str] # Return only usages for these image sizes. Possible values are `256x256`, `512x512`, `1024x1024`, `1792x1792`, `1024x1792` or any combination of them., project_ids: [str] # Return only usage for these projects., user_ids: [str] # Return only usage for these users., api_key_ids: [str] # Return only usage for these API keys., models: [str] # Return only usage for these models., group_by: [str] # 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., limit: int # 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, page: str # A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.}
@returns(200) {object: str, data: [map], has_more: bool, next_page: str} # Usage data retrieved successfully.

@endpoint GET /organization/usage/moderations
@desc Get moderations usage details for the organization.
@required {start_time: int # Start time (Unix seconds) of the query time range, inclusive.}
@optional {end_time: int # End time (Unix seconds) of the query time range, exclusive., bucket_width: str(1m/1h/1d)=1d # Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`., project_ids: [str] # Return only usage for these projects., user_ids: [str] # Return only usage for these users., api_key_ids: [str] # Return only usage for these API keys., models: [str] # Return only usage for these models., group_by: [str] # Group the usage data by the specified fields. Support fields include `project_id`, `user_id`, `api_key_id`, `model` or any combination of them., limit: int # 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, page: str # A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.}
@returns(200) {object: str, data: [map], has_more: bool, next_page: str} # Usage data retrieved successfully.

@endpoint GET /organization/usage/vector_stores
@desc Get vector stores usage details for the organization.
@required {start_time: int # Start time (Unix seconds) of the query time range, inclusive.}
@optional {end_time: int # End time (Unix seconds) of the query time range, exclusive., bucket_width: str(1m/1h/1d)=1d # Width of each time bucket in response. Currently `1m`, `1h` and `1d` are supported, default to `1d`., project_ids: [str] # Return only usage for these projects., group_by: [str] # Group the usage data by the specified fields. Support fields include `project_id`., limit: int # 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, page: str # A cursor for use in pagination. Corresponding to the `next_page` field from the previous response.}
@returns(200) {object: str, data: [map], has_more: bool, next_page: str} # Usage data retrieved successfully.

@endpoint GET /organization/users
@desc Lists all of the users in the organization.
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., after: str # 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., emails: [str] # Filter by the email address of users.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # Users listed successfully.

@endpoint GET /organization/users/{user_id}
@desc Retrieves a user by their identifier.
@required {user_id: str # The ID of the user.}
@returns(200) {object: str, id: str, name: str, email: str, role: str, added_at: int} # User retrieved successfully.

@endpoint POST /organization/users/{user_id}
@desc Modifies a user's role in the organization.
@required {user_id: str # The ID of the user., role: str(owner/reader) # `owner` or `reader`}
@returns(200) {object: str, id: str, name: str, email: str, role: str, added_at: int} # User role updated successfully.

@endpoint DELETE /organization/users/{user_id}
@desc Deletes a user from the organization.
@required {user_id: str # The ID of the user.}
@returns(200) {object: str, id: str, deleted: bool} # User deleted successfully.

@endgroup

@group realtime
@endpoint POST /realtime/sessions
@desc Create an ephemeral API token for use in client-side applications with the
@optional {modalities: any # The set of modalities the model can respond with. To disable audio, set this to ["text"]., model: str(gpt-4o-realtime-preview/gpt-4o-realtime-preview-2024-10-01/gpt-4o-realtime-preview-2024-12-17/gpt-4o-mini-realtime-preview/gpt-4o-mini-realtime-preview-2024-12-17) # The Realtime model used for this session., instructions: str # The default system instructions (i.e. system message) prepended to model  calls. This field allows the client to guide the model on desired  responses. The model can be instructed on response content and format,  (e.g. "be extremely succinct", "act friendly", "here are examples of good  responses") and on audio behavior (e.g. "talk quickly", "inject emotion  into your voice", "laugh frequently"). The instructions are not guaranteed  to be followed by the model, but they provide guidance to the model on the desired behavior.  Note that the server sets default instructions which will be used if this  field is not set and are visible in the `session.created` event at the  start of the session., voice: any, input_audio_format: str(pcm16/g711_ulaw/g711_alaw)=pcm16 # The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate,  single channel (mono), and little-endian byte order., output_audio_format: str(pcm16/g711_ulaw/g711_alaw)=pcm16 # The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For `pcm16`, output audio is sampled at a rate of 24kHz., input_audio_transcription: map{model: str, language: str, prompt: str} # Configuration for input audio transcription, defaults to off and can be  set to `null` to turn off once on. Input audio transcription is not native to the model, since the model consumes audio directly. Transcription runs  asynchronously through [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) and should be treated as guidance of input audio content rather than precisely what the model heard. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service., turn_detection: map{type: str, eagerness: str, threshold: num, prefix_padding_ms: int, silence_duration_ms: int, create_response: bool, interrupt_response: bool} # Configuration for turn detection, ether Server VAD or Semantic VAD. This can be set to `null` to turn off, in which case the client must manually trigger model response. Server VAD means that the model will detect the start and end of speech based on audio volume and respond at the end of user speech. Semantic VAD is more advanced and uses a turn detection model (in conjuction with VAD) to semantically estimate whether the user has finished speaking, then dynamically sets a timeout based on this probability. For example, if user audio trails off with "uhhm", the model will score a low probability of turn end and wait longer for the user to continue speaking. This can be useful for more natural conversations, but may have a higher latency., input_audio_noise_reduction: map{type: str}=null # Configuration for input audio noise reduction. This can be set to `null` to turn off. Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model. Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio., tools: [map{type: str, name: str, description: str, parameters: map}] # Tools (functions) available to the model., tool_choice: str=auto # How the model chooses tools. Options are `auto`, `none`, `required`, or  specify a function., temperature: num=0.8 # Sampling temperature for the model, limited to [0.6, 1.2]. For audio models a temperature of 0.8 is highly recommended for best performance., max_response_output_tokens: any # Maximum number of output tokens for a single assistant response, inclusive of tool calls. Provide an integer between 1 and 4096 to limit output tokens, or `inf` for the maximum available tokens for a given model. Defaults to `inf`.}
@returns(200) {client_secret: map{value: str, expires_at: int}, modalities: any, instructions: str, voice: any, input_audio_format: str, output_audio_format: str, input_audio_transcription: map{model: str}, turn_detection: map{type: str, threshold: num, prefix_padding_ms: int, silence_duration_ms: int}, tools: [map], tool_choice: str, temperature: num, max_response_output_tokens: any} # Session created successfully.

@endpoint POST /realtime/transcription_sessions
@desc Create an ephemeral API token for use in client-side applications with the
@optional {modalities: any # The set of modalities the model can respond with. To disable audio, set this to ["text"]., input_audio_format: str(pcm16/g711_ulaw/g711_alaw)=pcm16 # The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate,  single channel (mono), and little-endian byte order., input_audio_transcription: map{model: str, language: str, prompt: str} # Configuration for input audio transcription. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service., turn_detection: map{type: str, eagerness: str, threshold: num, prefix_padding_ms: int, silence_duration_ms: int, create_response: bool, interrupt_response: bool} # Configuration for turn detection, ether Server VAD or Semantic VAD. This can be set to `null` to turn off, in which case the client must manually trigger model response. Server VAD means that the model will detect the start and end of speech based on audio volume and respond at the end of user speech. Semantic VAD is more advanced and uses a turn detection model (in conjuction with VAD) to semantically estimate whether the user has finished speaking, then dynamically sets a timeout based on this probability. For example, if user audio trails off with "uhhm", the model will score a low probability of turn end and wait longer for the user to continue speaking. This can be useful for more natural conversations, but may have a higher latency., input_audio_noise_reduction: map{type: str}=null # Configuration for input audio noise reduction. This can be set to `null` to turn off. Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model. Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio., include: [str] # The set of items to include in the transcription. Current available items are: - `item.input_audio_transcription.logprobs`}
@returns(200) {client_secret: map{value: str, expires_at: int}, modalities: any, input_audio_format: str, input_audio_transcription: map{model: str, language: str, prompt: str}, turn_detection: map{type: str, threshold: num, prefix_padding_ms: int, silence_duration_ms: int}} # Session created successfully.

@endgroup

@group responses
@endpoint POST /responses
@desc Creates a model response. Provide [text](/docs/guides/text) or
@returns(200) OK

@endpoint GET /responses/{response_id}
@desc Retrieves a model response with the given ID.
@required {response_id: str # The ID of the response to retrieve.}
@optional {include: [str] # Additional fields to include in the response. See the `include` parameter for Response creation above for more information.}
@returns(200) OK

@endpoint DELETE /responses/{response_id}
@desc Deletes a model response with the given ID.
@required {response_id: str # The ID of the response to delete.}
@returns(200) OK
@errors {404: Not Found}

@endpoint GET /responses/{response_id}/input_items
@desc Returns a list of input items for a given response.
@required {response_id: str # The ID of the response to retrieve input items for.}
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., order: str(asc/desc) # The order to return the input items in. Default is `asc`. - `asc`: Return the input items in ascending order. - `desc`: Return the input items in descending order., after: str # An item ID to list items after, used in pagination., before: str # An item ID to list items before, used in pagination., include: [str] # Additional fields to include in the response. See the `include` parameter for Response creation above for more information.}
@returns(200) {object: str, data: [any], has_more: bool, first_id: str, last_id: str} # OK

@endgroup

@group threads
@endpoint POST /threads
@desc Create a thread.
@optional {messages: [map{role!: str, content!: any, attachments: [map], metadata: map}] # A list of [messages](/docs/api-reference/messages) to start the thread with., tool_resources: map{code_interpreter: map, file_search: map} # A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {id: str, object: str, created_at: int, tool_resources: map?{code_interpreter: map{file_ids: [str]}, file_search: map{vector_store_ids: [str]}}, metadata: map?} # OK

@endpoint POST /threads/runs
@desc Create a thread and run it in one request.
@required {assistant_id: str # The ID of the [assistant](/docs/api-reference/assistants) to use to execute this run.}
@optional {thread: map{messages: [map], tool_resources: map, metadata: map} # Options to create a new thread. If no thread is provided when running a  request, an empty thread will be created., model: any # The ID of the [Model](/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used., instructions: str # Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis., tools: [any] # Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis., tool_resources: map{code_interpreter: map, file_search: map} # A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters., temperature: num=1 # What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic., top_p: num=1 # An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.  We generally recommend altering this or temperature but not both., stream: bool # If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message., max_prompt_tokens: int # The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info., max_completion_tokens: int # The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info., truncation_strategy: any, tool_choice: any, parallel_tool_calls: bool=true # Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use., response_format: any # Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.  Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).  Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.  **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.}
@returns(200) {id: str, object: str, created_at: int, thread_id: str, assistant_id: str, status: str, required_action: map?{type: str, submit_tool_outputs: map{tool_calls: [map]}}, last_error: map?{code: str, message: str}, expires_at: int?, started_at: int?, cancelled_at: int?, failed_at: int?, completed_at: int?, incomplete_details: map?{reason: str}, model: str, instructions: str, tools: [any], metadata: map?, usage: map?{completion_tokens: int, prompt_tokens: int, total_tokens: int}, temperature: num?, top_p: num?, max_prompt_tokens: int?, max_completion_tokens: int?, truncation_strategy: any, tool_choice: any, parallel_tool_calls: bool, response_format: any} # OK

@endpoint GET /threads/{thread_id}
@desc Retrieves a thread.
@required {thread_id: str # The ID of the thread to retrieve.}
@returns(200) {id: str, object: str, created_at: int, tool_resources: map?{code_interpreter: map{file_ids: [str]}, file_search: map{vector_store_ids: [str]}}, metadata: map?} # OK

@endpoint POST /threads/{thread_id}
@desc Modifies a thread.
@required {thread_id: str # The ID of the thread to modify. Only the `metadata` can be modified.}
@optional {tool_resources: map{code_interpreter: map, file_search: map} # A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {id: str, object: str, created_at: int, tool_resources: map?{code_interpreter: map{file_ids: [str]}, file_search: map{vector_store_ids: [str]}}, metadata: map?} # OK

@endpoint DELETE /threads/{thread_id}
@desc Delete a thread.
@required {thread_id: str # The ID of the thread to delete.}
@returns(200) {id: str, deleted: bool, object: str} # OK

@endpoint GET /threads/{thread_id}/messages
@desc Returns a list of messages for a given thread.
@required {thread_id: str # The ID of the [thread](/docs/api-reference/threads) the messages belong to.}
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., order: str(asc/desc)=desc # Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order., after: str # 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., before: str # 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., run_id: str # Filter messages by the run ID that generated them.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # OK

@endpoint POST /threads/{thread_id}/messages
@desc Create a message.
@required {thread_id: str # The ID of the [thread](/docs/api-reference/threads) to create a message for., role: str(user/assistant) # The role of the entity that is creating the message. Allowed values include: - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation., content: any}
@optional {attachments: [map{file_id: str, tools: [any]}] # A list of files attached to the message, and the tools they should be added to., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {id: str, object: str, created_at: int, thread_id: str, status: str, incomplete_details: map?{reason: str}, completed_at: int?, incomplete_at: int?, role: str, content: [any], assistant_id: str?, run_id: str?, attachments: [map]?, metadata: map?} # OK

@endpoint GET /threads/{thread_id}/messages/{message_id}
@desc Retrieve a message.
@required {thread_id: str # The ID of the [thread](/docs/api-reference/threads) to which this message belongs., message_id: str # The ID of the message to retrieve.}
@returns(200) {id: str, object: str, created_at: int, thread_id: str, status: str, incomplete_details: map?{reason: str}, completed_at: int?, incomplete_at: int?, role: str, content: [any], assistant_id: str?, run_id: str?, attachments: [map]?, metadata: map?} # OK

@endpoint POST /threads/{thread_id}/messages/{message_id}
@desc Modifies a message.
@required {thread_id: str # The ID of the thread to which this message belongs., message_id: str # The ID of the message to modify.}
@optional {metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {id: str, object: str, created_at: int, thread_id: str, status: str, incomplete_details: map?{reason: str}, completed_at: int?, incomplete_at: int?, role: str, content: [any], assistant_id: str?, run_id: str?, attachments: [map]?, metadata: map?} # OK

@endpoint DELETE /threads/{thread_id}/messages/{message_id}
@desc Deletes a message.
@required {thread_id: str # The ID of the thread to which this message belongs., message_id: str # The ID of the message to delete.}
@returns(200) {id: str, deleted: bool, object: str} # OK

@endpoint GET /threads/{thread_id}/runs
@desc Returns a list of runs belonging to a thread.
@required {thread_id: str # The ID of the thread the run belongs to.}
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., order: str(asc/desc)=desc # Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order., after: str # 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., before: str # 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.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # OK

@endpoint POST /threads/{thread_id}/runs
@desc Create a run.
@required {thread_id: str # The ID of the thread to run., assistant_id: str # The ID of the [assistant](/docs/api-reference/assistants) to use to execute this run.}
@optional {include[]: [str] # A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content.  See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information., model: any # The ID of the [Model](/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used., reasoning_effort: str(low/medium/high)=medium # **o-series models only**   Constrains effort on reasoning for  [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `low`, `medium`, and `high`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response., instructions: str # Overrides the [instructions](/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis., additional_instructions: str # Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions., additional_messages: [map{role!: str, content!: any, attachments: [map], metadata: map}] # Adds additional messages to the thread before creating the run., tools: [any] # Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters., temperature: num=1 # What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic., top_p: num=1 # An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.  We generally recommend altering this or temperature but not both., stream: bool # If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message., max_prompt_tokens: int # The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info., max_completion_tokens: int # The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info., truncation_strategy: any, tool_choice: any, parallel_tool_calls: bool=true # Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use., response_format: any # Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`.  Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs).  Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON.  **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length.}
@returns(200) {id: str, object: str, created_at: int, thread_id: str, assistant_id: str, status: str, required_action: map?{type: str, submit_tool_outputs: map{tool_calls: [map]}}, last_error: map?{code: str, message: str}, expires_at: int?, started_at: int?, cancelled_at: int?, failed_at: int?, completed_at: int?, incomplete_details: map?{reason: str}, model: str, instructions: str, tools: [any], metadata: map?, usage: map?{completion_tokens: int, prompt_tokens: int, total_tokens: int}, temperature: num?, top_p: num?, max_prompt_tokens: int?, max_completion_tokens: int?, truncation_strategy: any, tool_choice: any, parallel_tool_calls: bool, response_format: any} # OK

@endpoint GET /threads/{thread_id}/runs/{run_id}
@desc Retrieves a run.
@required {thread_id: str # The ID of the [thread](/docs/api-reference/threads) that was run., run_id: str # The ID of the run to retrieve.}
@returns(200) {id: str, object: str, created_at: int, thread_id: str, assistant_id: str, status: str, required_action: map?{type: str, submit_tool_outputs: map{tool_calls: [map]}}, last_error: map?{code: str, message: str}, expires_at: int?, started_at: int?, cancelled_at: int?, failed_at: int?, completed_at: int?, incomplete_details: map?{reason: str}, model: str, instructions: str, tools: [any], metadata: map?, usage: map?{completion_tokens: int, prompt_tokens: int, total_tokens: int}, temperature: num?, top_p: num?, max_prompt_tokens: int?, max_completion_tokens: int?, truncation_strategy: any, tool_choice: any, parallel_tool_calls: bool, response_format: any} # OK

@endpoint POST /threads/{thread_id}/runs/{run_id}
@desc Modifies a run.
@required {thread_id: str # The ID of the [thread](/docs/api-reference/threads) that was run., run_id: str # The ID of the run to modify.}
@optional {metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {id: str, object: str, created_at: int, thread_id: str, assistant_id: str, status: str, required_action: map?{type: str, submit_tool_outputs: map{tool_calls: [map]}}, last_error: map?{code: str, message: str}, expires_at: int?, started_at: int?, cancelled_at: int?, failed_at: int?, completed_at: int?, incomplete_details: map?{reason: str}, model: str, instructions: str, tools: [any], metadata: map?, usage: map?{completion_tokens: int, prompt_tokens: int, total_tokens: int}, temperature: num?, top_p: num?, max_prompt_tokens: int?, max_completion_tokens: int?, truncation_strategy: any, tool_choice: any, parallel_tool_calls: bool, response_format: any} # OK

@endpoint POST /threads/{thread_id}/runs/{run_id}/cancel
@desc Cancels a run that is `in_progress`.
@required {thread_id: str # The ID of the thread to which this run belongs., run_id: str # The ID of the run to cancel.}
@returns(200) {id: str, object: str, created_at: int, thread_id: str, assistant_id: str, status: str, required_action: map?{type: str, submit_tool_outputs: map{tool_calls: [map]}}, last_error: map?{code: str, message: str}, expires_at: int?, started_at: int?, cancelled_at: int?, failed_at: int?, completed_at: int?, incomplete_details: map?{reason: str}, model: str, instructions: str, tools: [any], metadata: map?, usage: map?{completion_tokens: int, prompt_tokens: int, total_tokens: int}, temperature: num?, top_p: num?, max_prompt_tokens: int?, max_completion_tokens: int?, truncation_strategy: any, tool_choice: any, parallel_tool_calls: bool, response_format: any} # OK

@endpoint GET /threads/{thread_id}/runs/{run_id}/steps
@desc Returns a list of run steps belonging to a run.
@required {thread_id: str # The ID of the thread the run and run steps belong to., run_id: str # The ID of the run the run steps belong to.}
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., order: str(asc/desc)=desc # Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order., after: str # 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., before: str # 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., include[]: [str] # A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content.  See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # OK

@endpoint GET /threads/{thread_id}/runs/{run_id}/steps/{step_id}
@desc Retrieves a run step.
@required {thread_id: str # The ID of the thread to which the run and run step belongs., run_id: str # The ID of the run to which the run step belongs., step_id: str # The ID of the run step to retrieve.}
@optional {include[]: [str] # A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content.  See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information.}
@returns(200) {id: str, object: str, created_at: int, assistant_id: str, thread_id: str, run_id: str, type: str, status: str, step_details: map, last_error: map?{code: str, message: str}, expired_at: int?, cancelled_at: int?, failed_at: int?, completed_at: int?, metadata: map?, usage: map?{completion_tokens: int, prompt_tokens: int, total_tokens: int}} # OK

@endpoint POST /threads/{thread_id}/runs/{run_id}/submit_tool_outputs
@desc When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request.
@required {thread_id: str # The ID of the [thread](/docs/api-reference/threads) to which this run belongs., run_id: str # The ID of the run that requires the tool output submission., tool_outputs: [map{tool_call_id: str, output: str}] # A list of tools for which the outputs are being submitted.}
@optional {stream: bool # If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message.}
@returns(200) {id: str, object: str, created_at: int, thread_id: str, assistant_id: str, status: str, required_action: map?{type: str, submit_tool_outputs: map{tool_calls: [map]}}, last_error: map?{code: str, message: str}, expires_at: int?, started_at: int?, cancelled_at: int?, failed_at: int?, completed_at: int?, incomplete_details: map?{reason: str}, model: str, instructions: str, tools: [any], metadata: map?, usage: map?{completion_tokens: int, prompt_tokens: int, total_tokens: int}, temperature: num?, top_p: num?, max_prompt_tokens: int?, max_completion_tokens: int?, truncation_strategy: any, tool_choice: any, parallel_tool_calls: bool, response_format: any} # OK

@endgroup

@group uploads
@endpoint POST /uploads
@desc Creates an intermediate [Upload](/docs/api-reference/uploads/object) object
@required {filename: str # The name of the file to upload., purpose: str(assistants/batch/fine-tune/vision) # The intended purpose of the uploaded file.  See the [documentation on File purposes](/docs/api-reference/files/create#files-create-purpose)., bytes: int # The number of bytes in the file you are uploading., mime_type: str # The MIME type of the file.  This must fall within the supported MIME types for your file purpose. See the supported MIME types for assistants and vision.}
@returns(200) {id: str, created_at: int, filename: str, bytes: int, purpose: str, status: str, expires_at: int, object: str, file: any} # OK

@endpoint POST /uploads/{upload_id}/cancel
@desc Cancels the Upload. No Parts may be added after an Upload is cancelled.
@required {upload_id: str # The ID of the Upload.}
@returns(200) {id: str, created_at: int, filename: str, bytes: int, purpose: str, status: str, expires_at: int, object: str, file: any} # OK

@endpoint POST /uploads/{upload_id}/complete
@desc Completes the [Upload](/docs/api-reference/uploads/object).
@required {upload_id: str # The ID of the Upload., part_ids: [str] # The ordered list of Part IDs.}
@optional {md5: str # The optional md5 checksum for the file contents to verify if the bytes uploaded matches what you expect.}
@returns(200) {id: str, created_at: int, filename: str, bytes: int, purpose: str, status: str, expires_at: int, object: str, file: any} # OK

@endpoint POST /uploads/{upload_id}/parts
@desc Adds a [Part](/docs/api-reference/uploads/part-object) to an [Upload](/docs/api-reference/uploads/object) object. A Part represents a chunk of bytes from the file you are trying to upload.
@required {upload_id: str # The ID of the Upload.}
@returns(200) {id: str, created_at: int, upload_id: str, object: str} # OK

@endgroup

@group vector_stores
@endpoint GET /vector_stores
@desc Returns a list of vector stores.
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., order: str(asc/desc)=desc # Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order., after: str # 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., before: str # 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.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # OK

@endpoint POST /vector_stores
@desc Create a vector store.
@optional {file_ids: [str] # A list of [File](/docs/api-reference/files) IDs that the vector store should use. Useful for tools like `file_search` that can access files., name: str # The name of the vector store., expires_after: map{anchor!: str, days!: int} # The expiration policy for a vector store., chunking_strategy: map # The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. Only applicable if `file_ids` is non-empty., metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {id: str, object: str, created_at: int, name: str, usage_bytes: int, file_counts: map{in_progress: int, completed: int, failed: int, cancelled: int, total: int}, status: str, expires_after: map{anchor: str, days: int}, expires_at: int?, last_active_at: int?, metadata: map?} # OK

@endpoint GET /vector_stores/{vector_store_id}
@desc Retrieves a vector store.
@required {vector_store_id: str # The ID of the vector store to retrieve.}
@returns(200) {id: str, object: str, created_at: int, name: str, usage_bytes: int, file_counts: map{in_progress: int, completed: int, failed: int, cancelled: int, total: int}, status: str, expires_after: map{anchor: str, days: int}, expires_at: int?, last_active_at: int?, metadata: map?} # OK

@endpoint POST /vector_stores/{vector_store_id}
@desc Modifies a vector store.
@required {vector_store_id: str # The ID of the vector store to modify.}
@optional {name: str # The name of the vector store., expires_after: any, metadata: map # Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.   Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.}
@returns(200) {id: str, object: str, created_at: int, name: str, usage_bytes: int, file_counts: map{in_progress: int, completed: int, failed: int, cancelled: int, total: int}, status: str, expires_after: map{anchor: str, days: int}, expires_at: int?, last_active_at: int?, metadata: map?} # OK

@endpoint DELETE /vector_stores/{vector_store_id}
@desc Delete a vector store.
@required {vector_store_id: str # The ID of the vector store to delete.}
@returns(200) {id: str, deleted: bool, object: str} # OK

@endpoint POST /vector_stores/{vector_store_id}/file_batches
@desc Create a vector store file batch.
@required {vector_store_id: str # The ID of the vector store for which to create a File Batch., file_ids: [str] # A list of [File](/docs/api-reference/files) IDs that the vector store should use. Useful for tools like `file_search` that can access files.}
@optional {chunking_strategy: map # The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy., attributes: map # Set of 16 key-value pairs that can be attached to an object. This can be  useful for storing additional information about the object in a structured  format, and querying for objects via API or the dashboard. Keys are strings  with a maximum length of 64 characters. Values are strings with a maximum  length of 512 characters, booleans, or numbers.}
@returns(200) {id: str, object: str, created_at: int, vector_store_id: str, status: str, file_counts: map{in_progress: int, completed: int, failed: int, cancelled: int, total: int}} # OK

@endpoint GET /vector_stores/{vector_store_id}/file_batches/{batch_id}
@desc Retrieves a vector store file batch.
@required {vector_store_id: str # The ID of the vector store that the file batch belongs to., batch_id: str # The ID of the file batch being retrieved.}
@returns(200) {id: str, object: str, created_at: int, vector_store_id: str, status: str, file_counts: map{in_progress: int, completed: int, failed: int, cancelled: int, total: int}} # OK

@endpoint POST /vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel
@desc Cancel a vector store file batch. This attempts to cancel the processing of files in this batch as soon as possible.
@required {vector_store_id: str # The ID of the vector store that the file batch belongs to., batch_id: str # The ID of the file batch to cancel.}
@returns(200) {id: str, object: str, created_at: int, vector_store_id: str, status: str, file_counts: map{in_progress: int, completed: int, failed: int, cancelled: int, total: int}} # OK

@endpoint GET /vector_stores/{vector_store_id}/file_batches/{batch_id}/files
@desc Returns a list of vector store files in a batch.
@required {vector_store_id: str # The ID of the vector store that the files belong to., batch_id: str # The ID of the file batch that the files belong to.}
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., order: str(asc/desc)=desc # Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order., after: str # 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., before: str # 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., filter: str(in_progress/completed/failed/cancelled) # Filter by file status. One of `in_progress`, `completed`, `failed`, `cancelled`.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # OK

@endpoint GET /vector_stores/{vector_store_id}/files
@desc Returns a list of vector store files.
@required {vector_store_id: str # The ID of the vector store that the files belong to.}
@optional {limit: int=20 # A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20., order: str(asc/desc)=desc # Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order., after: str # 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., before: str # 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., filter: str(in_progress/completed/failed/cancelled) # Filter by file status. One of `in_progress`, `completed`, `failed`, `cancelled`.}
@returns(200) {object: str, data: [map], first_id: str, last_id: str, has_more: bool} # OK

@endpoint POST /vector_stores/{vector_store_id}/files
@desc Create a vector store file by attaching a [File](/docs/api-reference/files) to a [vector store](/docs/api-reference/vector-stores/object).
@required {vector_store_id: str # The ID of the vector store for which to create a File., file_id: str # A [File](/docs/api-reference/files) ID that the vector store should use. Useful for tools like `file_search` that can access files.}
@optional {chunking_strategy: map # The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy., attributes: map # Set of 16 key-value pairs that can be attached to an object. This can be  useful for storing additional information about the object in a structured  format, and querying for objects via API or the dashboard. Keys are strings  with a maximum length of 64 characters. Values are strings with a maximum  length of 512 characters, booleans, or numbers.}
@returns(200) {id: str, object: str, usage_bytes: int, created_at: int, vector_store_id: str, status: str, last_error: map?{code: str, message: str}, chunking_strategy: map, attributes: map?} # OK

@endpoint GET /vector_stores/{vector_store_id}/files/{file_id}
@desc Retrieves a vector store file.
@required {vector_store_id: str # The ID of the vector store that the file belongs to., file_id: str # The ID of the file being retrieved.}
@returns(200) {id: str, object: str, usage_bytes: int, created_at: int, vector_store_id: str, status: str, last_error: map?{code: str, message: str}, chunking_strategy: map, attributes: map?} # OK

@endpoint DELETE /vector_stores/{vector_store_id}/files/{file_id}
@desc Delete a vector store file. This will remove the file from the vector store but the file itself will not be deleted. To delete the file, use the [delete file](/docs/api-reference/files/delete) endpoint.
@required {vector_store_id: str # The ID of the vector store that the file belongs to., file_id: str # The ID of the file to delete.}
@returns(200) {id: str, deleted: bool, object: str} # OK

@endpoint POST /vector_stores/{vector_store_id}/files/{file_id}
@desc Update attributes on a vector store file.
@required {vector_store_id: str # The ID of the vector store the file belongs to., file_id: str # The ID of the file to update attributes., attributes: map # Set of 16 key-value pairs that can be attached to an object. This can be  useful for storing additional information about the object in a structured  format, and querying for objects via API or the dashboard. Keys are strings  with a maximum length of 64 characters. Values are strings with a maximum  length of 512 characters, booleans, or numbers.}
@returns(200) {id: str, object: str, usage_bytes: int, created_at: int, vector_store_id: str, status: str, last_error: map?{code: str, message: str}, chunking_strategy: map, attributes: map?} # OK

@endpoint GET /vector_stores/{vector_store_id}/files/{file_id}/content
@desc Retrieve the parsed contents of a vector store file.
@required {vector_store_id: str # The ID of the vector store., file_id: str # The ID of the file within the vector store.}
@returns(200) {object: str, data: [map], has_more: bool, next_page: str?} # OK

@endpoint POST /vector_stores/{vector_store_id}/search
@desc Search a vector store for relevant chunks based on a query and file attributes filter.
@required {vector_store_id: str # The ID of the vector store to search., query: any # A query string for a search}
@optional {rewrite_query: bool=false # Whether to rewrite the natural language query for vector search., max_num_results: int=10 # The maximum number of results to return. This number should be between 1 and 50 inclusive., filters: any # A filter to apply based on file attributes., ranking_options: map{ranker: str, score_threshold: num} # Ranking options for search.}
@returns(200) {object: str, search_query: [str], data: [map], has_more: bool, next_page: str?} # OK

@endgroup

@end