{"note":"OpenAPI conversion -- returning structured metadata","name":"cohere","description":"API Reference","version":"1.0","base_url":"https://api.cohere.com","endpoints":41,"raw":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api API Reference\n@base https://api.cohere.com\n@version 1.0\n@auth Bearer bearer\n@common_fields {X-Client-Name: str # The name of the project that is making the request.}\n@endpoints 41\n@hint download_for_search\n@toc chat(2), generate(1), embed(2), audio(1), batches(4), embed-jobs(4), rerank(2), classify(1), datasets(5), summarize(1), tokenize(1), detokenize(1), connectors(6), models(2), check-api-key(1), finetuning(7)\n\n@group chat\n@endpoint POST /v1/chat\n@desc Chat API (v1)\n@required {message: str # Text input for the model to respond to.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments}\n@optional {Accepts: str # Pass text/event-stream to receive the streamed response as server-sent events. The default is `\\n` delimited events., model: str # The name of a compatible [Cohere model](https://docs.cohere.com/docs/models) or the ID of a [fine-tuned](https://docs.cohere.com/docs/chat-fine-tuning) model.  Compatible Deployments: Cohere Platform, Private Deployments, stream: bool # Defaults to `false`.  When `true`, the response will be a JSON stream of events. The final event will contain the complete response, and will have an `event_type` of `\"stream-end\"`.  Streaming is beneficial for user interfaces that render the contents of the response piece by piece, as it gets generated.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, preamble: str # When specified, the default Cohere preamble will be replaced with the provided one. Preambles are a part of the prompt used to adjust the model's overall behavior and conversation style, and use the `SYSTEM` role.  The `SYSTEM` role is also used for the contents of the optional `chat_history=` parameter. When used with the `chat_history=` parameter it adds content throughout a conversation. Conversely, when used with the `preamble=` parameter it adds content at the start of the conversation only.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, chat_history: [any] # A list of previous messages between the user and the model, giving the model conversational context for responding to the user's `message`.  Each item represents a single message in the chat history, excluding the current user turn. It has two properties: `role` and `message`. The `role` identifies the sender (`CHATBOT`, `SYSTEM`, or `USER`), while the `message` contains the text content.  The chat_history parameter should not be used for `SYSTEM` messages in most cases. Instead, to add a `SYSTEM` role message at the beginning of a conversation, the `preamble` parameter should be used.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, conversation_id: str # An alternative to `chat_history`.  Providing a `conversation_id` creates or resumes a persisted conversation with the specified ID. The ID can be any non empty string.  Compatible Deployments: Cohere Platform, prompt_truncation: str(OFF/AUTO/AUTO_PRESERVE_ORDER) # Defaults to `AUTO` when `connectors` are specified and `OFF` in all other cases.  Dictates how the prompt will be constructed.  With `prompt_truncation` set to \"AUTO\", some elements from `chat_history` and `documents` will be dropped in an attempt to construct a prompt that fits within the model's context length limit. During this process the order of the documents and chat history will be changed and ranked by relevance.  With `prompt_truncation` set to \"AUTO_PRESERVE_ORDER\", some elements from `chat_history` and `documents` will be dropped in an attempt to construct a prompt that fits within the model's context length limit. During this process the order of the documents and chat history will be preserved as they are inputted into the API.  With `prompt_truncation` set to \"OFF\", no elements will be dropped. If the sum of the inputs exceeds the model's context length limit, a `TooManyTokens` error will be returned.  Compatible Deployments:  - AUTO: Cohere Platform Only  - AUTO_PRESERVE_ORDER: Azure, AWS Sagemaker/Bedrock, Private Deployments, connectors: [map{id!: str, user_access_token: str, continue_on_failure: bool, options: map}] # Accepts `{\"id\": \"web-search\"}`, and/or the `\"id\"` for a custom [connector](https://docs.cohere.com/docs/connectors), if you've [created](https://docs.cohere.com/v1/docs/creating-and-deploying-a-connector) one.  When specified, the model's reply will be enriched with information found by querying each of the connectors (RAG).  Compatible Deployments: Cohere Platform, search_queries_only: bool # Defaults to `false`.  When `true`, the response will only contain a list of generated search queries, but no search will take place, and no reply from the model to the user's `message` will be generated.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, documents: [map{id: str}] # A list of relevant documents that the model can cite to generate a more accurate reply. Each document is a string-string dictionary.  Example: ``` [   { \"title\": \"Tall penguins\", \"text\": \"Emperor penguins are the tallest.\" },   { \"title\": \"Penguin habitats\", \"text\": \"Emperor penguins only live in Antarctica.\" }, ] ```  Keys and values from each document will be serialized to a string and passed to the model. The resulting generation will include citations that reference some of these documents.  Some suggested keys are \"text\", \"author\", and \"date\". For better generation quality, it is recommended to keep the total word count of the strings in the dictionary to under 300 words.  An `id` field (string) can be optionally supplied to identify the document in the citations. This field will not be passed to the model.  An `_excludes` field (array of strings) can be optionally supplied to omit some key-value pairs from being shown to the model. The omitted fields will still show up in the citation object. The \"_excludes\" field will not be passed to the model.  See ['Document Mode'](https://docs.cohere.com/docs/retrieval-augmented-generation-rag#document-mode) in the guide for more information.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, citation_quality: str(ENABLED/DISABLED/FAST/ACCURATE/OFF) # Defaults to `\"enabled\"`. Citations are enabled by default for models that support it, but can be turned off by setting `\"type\": \"disabled\"`.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, temperature: num(float) # Defaults to `0.3`.  A non-negative float that tunes the degree of randomness in generation. Lower temperatures mean less random generations, and higher temperatures mean more random generations.  Randomness can be further maximized by increasing the  value of the `p` parameter.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, max_tokens: int # The maximum number of tokens the model will generate as part of the response. Note: Setting a low value may result in incomplete generations.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, max_input_tokens: int # The maximum number of input tokens to send to the model. If not specified, `max_input_tokens` is the model's context length limit minus a small buffer.  Input will be truncated according to the `prompt_truncation` parameter.  Compatible Deployments: Cohere Platform, k: int=0 # Ensures only the top `k` most likely tokens are considered for generation at each step. Defaults to `0`, min value of `0`, max value of `500`.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, p: num=0.75 # Ensures that only the most likely tokens, with total probability mass of `p`, are considered for generation at each step. If both `k` and `p` are enabled, `p` acts after `k`. Defaults to `0.75`. min value of `0.01`, max value of `0.99`.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, seed: int # If specified, the backend will make a best effort to sample tokens deterministically, such that repeated requests with the same seed and parameters should return the same result. However, determinism cannot be totally guaranteed.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, stop_sequences: [str] # A list of up to 5 strings that the model will use to stop generation. If the model generates a string that matches any of the strings in the list, it will stop generating tokens and return the generated text up to that point not including the stop sequence.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, frequency_penalty: num # Defaults to `0.0`, min value of `0.0`, max value of `1.0`.  Used to reduce repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, presence_penalty: num # Defaults to `0.0`, min value of `0.0`, max value of `1.0`.  Used to reduce repetitiveness of generated tokens. Similar to `frequency_penalty`, except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, raw_prompting: bool # When enabled, the user's prompt will be sent to the model without any pre-processing.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, tools: [map{name!: str, description!: str, parameter_definitions: map}] # A list of available tools (functions) that the model may suggest invoking before producing a text response.  When `tools` is passed (without `tool_results`), the `text` field in the response will be `\"\"` and the `tool_calls` field in the response will be populated with a list of tool calls that need to be made. If no calls need to be made, the `tool_calls` array will be empty.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, tool_results: [map{call!: map, outputs!: [map]}] # A list of results from invoking tools recommended by the model in the previous chat turn. Results are used to produce a text response and will be referenced in citations. When using `tool_results`, `tools` must be passed as well. Each tool_result contains information about how it was invoked, as well as a list of outputs in the form of dictionaries.  **Note**: `outputs` must be a list of objects. If your tool returns a single object (eg `{\"status\": 200}`), make sure to wrap it in a list. ``` tool_results = [   {     \"call\": {       \"name\": ,       \"parameters\": {         :        }     },     \"outputs\": [{       :      }]   },   ... ] ``` **Note**: Chat calls with `tool_results` should not be included in the Chat history to avoid duplication of the message text.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, force_single_step: bool # Forces the chat to be single step. Defaults to `false`., response_format: any # Configuration for forcing the model output to adhere to the specified format. Supported on [Command R 03-2024](https://docs.cohere.com/docs/command-r), [Command R+ 04-2024](https://docs.cohere.com/docs/command-r-plus) and newer models.  The model can be forced into outputting JSON objects (with up to 5 levels of nesting) by setting `{ \"type\": \"json_object\" }`.  A [JSON Schema](https://json-schema.org/) can optionally be provided, to ensure a specific structure.  **Note**: When using  `{ \"type\": \"json_object\" }` your `message` should always explicitly instruct the model to generate a JSON (eg: _\"Generate a JSON ...\"_) . Otherwise the model may end up getting stuck generating an infinite stream of characters and eventually run out of context length. **Limitation**: The parameter is not supported in RAG mode (when any of `connectors`, `documents`, `tools`, `tool_results` are provided)., safety_mode: any(CONTEXTUAL/STRICT/NONE) # Used to select the [safety instruction](https://docs.cohere.com/docs/safety-modes) inserted into the prompt. Defaults to `CONTEXTUAL`. When `NONE` is specified, the safety instruction will be omitted.  Safety modes are not yet configurable in combination with `tools`, `tool_results` and `documents` parameters.  **Note**: This parameter is only compatible newer Cohere models, starting with [Command R 08-2024](https://docs.cohere.com/docs/command-r#august-2024-release) and [Command R+ 08-2024](https://docs.cohere.com/docs/command-r-plus#august-2024-release).  **Note**: `command-r7b-12-2024` and newer models only support `\"CONTEXTUAL\"` and `\"STRICT\"` modes.  Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments}\n@returns(200) OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint POST /v2/chat\n@desc Chat API (v2)\n@required {model: str # The name of a compatible [Cohere model](https://docs.cohere.com/v2/docs/models)., messages: [any] # A list of chat messages in chronological order, representing a conversation between the user and the model.  Messages can be from `User`, `Assistant`, `Tool` and `System` roles. Learn more about messages and roles in [the Chat API guide](https://docs.cohere.com/v2/docs/chat-api).}\n@optional {stream: bool # Defaults to `false`.  When `true`, the response will be a SSE stream of events.  Streaming is beneficial for user interfaces that render the contents of the response piece by piece, as it gets generated., tools: [map{type!: str, function: map}] # A list of tools (functions) available to the model. The model response may contain 'tool_calls' to the specified tools.  Learn more in the [Tool Use guide](https://docs.cohere.com/docs/tools)., strict_tools: bool # When set to `true`, tool calls in the Assistant message will be forced to follow the tool definition strictly. Learn more in the [Structured Outputs (Tools) guide](https://docs.cohere.com/docs/structured-outputs-json#structured-outputs-tools).  **Note**: The first few requests with a new set of tools will take longer to process., documents: [any] # A list of relevant documents that the model can cite to generate a more accurate reply. Each document is either a string or document object with content and metadata., citation_options: map{mode: str} # Options for controlling citation generation., response_format: any # Configuration for forcing the model output to adhere to the specified format. Supported on [Command R](https://docs.cohere.com/v2/docs/command-r), [Command R+](https://docs.cohere.com/v2/docs/command-r-plus) and newer models.  The model can be forced into outputting JSON objects by setting `{ \"type\": \"json_object\" }`.  A [JSON Schema](https://json-schema.org/) can optionally be provided, to ensure a specific structure.  **Note**: When using  `{ \"type\": \"json_object\" }` your `message` should always explicitly instruct the model to generate a JSON (eg: _\"Generate a JSON ...\"_) . Otherwise the model may end up getting stuck generating an infinite stream of characters and eventually run out of context length.  **Note**: When `json_schema` is not specified, the generated object can have up to 5 layers of nesting.  **Limitation**: The parameter is not supported when used in combinations with the `documents` or `tools` parameters., safety_mode: any(CONTEXTUAL/STRICT/OFF) # Used to select the [safety instruction](https://docs.cohere.com/v2/docs/safety-modes) inserted into the prompt. Defaults to `CONTEXTUAL`. When `OFF` is specified, the safety instruction will be omitted.  Safety modes are not yet configurable in combination with `tools` and `documents` parameters.  **Note**: This parameter is only compatible newer Cohere models, starting with [Command R 08-2024](https://docs.cohere.com/docs/command-r#august-2024-release) and [Command R+ 08-2024](https://docs.cohere.com/docs/command-r-plus#august-2024-release).  **Note**: `command-r7b-12-2024` and newer models only support `\"CONTEXTUAL\"` and `\"STRICT\"` modes., max_tokens: int # The maximum number of output tokens the model will generate in the response. If not set, `max_tokens` defaults to the model's maximum output token limit. You can find the maximum output token limits for each model in the [model documentation](https://docs.cohere.com/docs/models).  **Note**: Setting a low value may result in incomplete generations. In such cases, the `finish_reason` field in the response will be set to `\"MAX_TOKENS\"`.  **Note**: If `max_tokens` is set higher than the model's maximum output token limit, the generation will be capped at that model-specific maximum limit., stop_sequences: [str] # A list of up to 5 strings that the model will use to stop generation. If the model generates a string that matches any of the strings in the list, it will stop generating tokens and return the generated text up to that point not including the stop sequence., temperature: num(float) # Defaults to `0.3`.  A non-negative float that tunes the degree of randomness in generation. Lower temperatures mean less random generations, and higher temperatures mean more random generations.  Randomness can be further maximized by increasing the  value of the `p` parameter., seed: int # If specified, the backend will make a best effort to sample tokens deterministically, such that repeated requests with the same seed and parameters should return the same result. However, determinism cannot be totally guaranteed., frequency_penalty: num(float) # Defaults to `0.0`, min value of `0.0`, max value of `1.0`. Used to reduce repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation., presence_penalty: num(float) # Defaults to `0.0`, min value of `0.0`, max value of `1.0`. Used to reduce repetitiveness of generated tokens. Similar to `frequency_penalty`, except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies., k: int=0 # Ensures that only the top `k` most likely tokens are considered for generation at each step. When `k` is set to `0`, k-sampling is disabled. Defaults to `0`, min value of `0`, max value of `500`., p: num(float)=0.75 # Ensures that only the most likely tokens, with total probability mass of `p`, are considered for generation at each step. If both `k` and `p` are enabled, `p` acts after `k`. Defaults to `0.75`. min value of `0.01`, max value of `0.99`., logprobs: bool # Defaults to `false`. When set to `true`, the log probabilities of the generated tokens will be included in the response., tool_choice: any(REQUIRED/NONE) # Used to control whether or not the model will be forced to use a tool when answering. When `REQUIRED` is specified, the model will be forced to use at least one of the user-defined tools, and the `tools` parameter must be passed in the request. When `NONE` is specified, the model will be forced **not** to use one of the specified tools, and give a direct response. If tool_choice isn't specified, then the model is free to choose whether to use the specified tools or not.  **Note**: This parameter is only compatible with models [Command-r7b](https://docs.cohere.com/v2/docs/command-r7b) and newer., thinking: map{type!: str, token_budget: int} # Configuration for [reasoning features](https://docs.cohere.com/docs/reasoning)., priority: int=0 # Controls how early the request is handled. Lower numbers indicate higher priority (default: 0, the highest). When the system is under load, higher-priority requests are processed first and are the least likely to be dropped.}\n@returns(200) OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group generate\n@endpoint POST /v1/generate\n@desc Generate\n@required {prompt: str # The input text that serves as the starting point for generating the response. Note: The prompt will be pre-processed and modified before reaching the model.}\n@optional {model: str # The identifier of the model to generate with. Currently available models are `command` (default), `command-nightly` (experimental), `command-light`, and `command-light-nightly` (experimental). Smaller, \"light\" models are faster, while larger models will perform better. [Custom models](https://docs.cohere.com/docs/training-custom-models) can also be supplied with their full ID., num_generations: int # The maximum number of generations that will be returned. Defaults to `1`, min value of `1`, max value of `5`., stream: bool # When `true`, the response will be a JSON stream of events. Streaming is beneficial for user interfaces that render the contents of the response piece by piece, as it gets generated.  The final event will contain the complete response, and will contain an `is_finished` field set to `true`. The event will also contain a `finish_reason`, which can be one of the following: - `COMPLETE` - the model sent back a finished reply - `MAX_TOKENS` - the reply was cut off because the model reached the maximum number of tokens for its context length - `ERROR` - something went wrong when generating the reply - `ERROR_TOXIC` - the model generated a reply that was deemed toxic, max_tokens: int # The maximum number of tokens the model will generate as part of the response. Note: Setting a low value may result in incomplete generations.  This parameter is off by default, and if it's not specified, the model will continue generating until it emits an EOS completion token. See [BPE Tokens](/bpe-tokens-wiki) for more details.  Can only be set to `0` if `return_likelihoods` is set to `ALL` to get the likelihood of the prompt., truncate: str(NONE/START/END)=END # One of `NONE|START|END` to specify how the API will handle inputs longer than the maximum token length.  Passing `START` will discard the start of the input. `END` will discard the end of the input. In both cases, input is discarded until the remaining input is exactly the maximum input token length for the model.  If `NONE` is selected, when the input exceeds the maximum input token length an error will be returned., temperature: num # A non-negative float that tunes the degree of randomness in generation. Lower temperatures mean less random generations. See [Temperature](/temperature-wiki) for more details. Defaults to `0.75`, min value of `0.0`, max value of `5.0`., seed: int # If specified, the backend will make a best effort to sample tokens deterministically, such that repeated requests with the same seed and parameters should return the same result. However, determinism cannot be totally guaranteed. Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments, preset: str # Identifier of a custom preset. A preset is a combination of parameters, such as prompt, temperature etc. You can create presets in the [playground](https://dashboard.cohere.com/playground/generate). When a preset is specified, the `prompt` parameter becomes optional, and any included parameters will override the preset's parameters., end_sequences: [str] # The generated text will be cut at the beginning of the earliest occurrence of an end sequence. The sequence will be excluded from the text., stop_sequences: [str] # The generated text will be cut at the end of the earliest occurrence of a stop sequence. The sequence will be included the text., k: int # Ensures only the top `k` most likely tokens are considered for generation at each step. Defaults to `0`, min value of `0`, max value of `500`., p: num # Ensures that only the most likely tokens, with total probability mass of `p`, are considered for generation at each step. If both `k` and `p` are enabled, `p` acts after `k`. Defaults to `0.75`. min value of `0.01`, max value of `0.99`., frequency_penalty: num # Used to reduce repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation.  Using `frequency_penalty` in combination with `presence_penalty` is not supported on newer models., presence_penalty: num # Defaults to `0.0`, min value of `0.0`, max value of `1.0`.  Can be used to reduce repetitiveness of generated tokens. Similar to `frequency_penalty`, except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies.  Using `frequency_penalty` in combination with `presence_penalty` is not supported on newer models., return_likelihoods: str(GENERATION/ALL/NONE)=NONE # One of `GENERATION|NONE` to specify how and if the token likelihoods are returned with the response. Defaults to `NONE`.  If `GENERATION` is selected, the token likelihoods will only be provided for generated text.  WARNING: `ALL` is deprecated, and will be removed in a future release., raw_prompting: bool # When enabled, the user's prompt will be sent to the model without any pre-processing.}\n@returns(200) {id: str, prompt: str, generations: [map], meta: map{api_version: map{version: str, is_deprecated: bool, is_experimental: bool}, billed_units: map{images: num, input_tokens: num, image_tokens: num, output_tokens: num, search_units: num, classifications: num}, tokens: map{input_tokens: num, output_tokens: num}, cached_tokens: num, warnings: [str]}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group embed\n@endpoint POST /v1/embed\n@desc Embed API (v1)\n@optional {texts: [str] # An array of strings for the model to embed. Maximum number of texts per call is `96`., images: [str] # An array of image data URIs for the model to embed. Maximum number of images per call is `1`.  The image must be a valid [data URI](https://developer.mozilla.org/en-US/docs/Web/URI/Schemes/data). The image must be in either `image/jpeg`, `image/png`, `image/webp`, or `image/gif` format and has a maximum size of 5MB.  Images are only supported with Embed v3.0 and newer models., model: str # ID of one of the available [Embedding models](https://docs.cohere.com/docs/cohere-embed)., input_type: str(search_document/search_query/classification/clustering/image) # Specifies the type of input passed to the model. Required for embedding models v3 and higher.  - `\"search_document\"`: Used for embeddings stored in a vector database for search use-cases. - `\"search_query\"`: Used for embeddings of search queries run against a vector DB to find relevant documents. - `\"classification\"`: Used for embeddings passed through a text classifier. - `\"clustering\"`: Used for the embeddings run through a clustering algorithm. - `\"image\"`: Used for embeddings with image input., embedding_types: [str] # Specifies the types of embeddings you want to get back. Not required and default is None, which returns the Embed Floats response type. Can be one or more of the following types.  * `\"float\"`: Use this when you want to get back the default float embeddings. Supported with all Embed models. * `\"int8\"`: Use this when you want to get back signed int8 embeddings. Supported with Embed v3.0 and newer Embed models. * `\"uint8\"`: Use this when you want to get back unsigned int8 embeddings. Supported with Embed v3.0 and newer Embed models. * `\"binary\"`: Use this when you want to get back signed binary embeddings. Supported with Embed v3.0 and newer Embed models. * `\"ubinary\"`: Use this when you want to get back unsigned binary embeddings. Supported with Embed v3.0 and newer Embed models., truncate: str(NONE/START/END)=END # One of `NONE|START|END` to specify how the API will handle inputs longer than the maximum token length.  Passing `START` will discard the start of the input. `END` will discard the end of the input. In both cases, input is discarded until the remaining input is exactly the maximum input token length for the model.  If `NONE` is selected, when the input exceeds the maximum input token length an error will be returned.}\n@returns(200) OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint POST /v2/embed\n@desc Embed API (v2)\n@required {model: str # ID of one of the available [Embedding models](https://docs.cohere.com/docs/cohere-embed)., input_type: str(search_document/search_query/classification/clustering/image) # Specifies the type of input passed to the model. Required for embedding models v3 and higher.  - `\"search_document\"`: Used for embeddings stored in a vector database for search use-cases. - `\"search_query\"`: Used for embeddings of search queries run against a vector DB to find relevant documents. - `\"classification\"`: Used for embeddings passed through a text classifier. - `\"clustering\"`: Used for the embeddings run through a clustering algorithm. - `\"image\"`: Used for embeddings with image input.}\n@optional {texts: [str] # An array of strings for the model to embed. Maximum number of texts per call is `96`., images: [str] # An array of image data URIs for the model to embed. Maximum number of images per call is `1`.  The image must be a valid [data URI](https://developer.mozilla.org/en-US/docs/Web/URI/Schemes/data). The image must be in either `image/jpeg`, `image/png`, `image/webp`, or `image/gif` format and has a maximum size of 5MB.  Image embeddings are supported with Embed v3.0 and newer models., inputs: [map{content!: [any]}] # An array of inputs for the model to embed. Maximum number of inputs per call is `96`. An input can contain a mix of text and image components., max_tokens: int # The maximum number of tokens to embed per input. If the input text is longer than this, it will be truncated according to the `truncate` parameter., output_dimension: int # The number of dimensions of the output embedding. This is only available for `embed-v4` and newer models. Possible values are `256`, `512`, `1024`, and `1536`. The default is `1536`., embedding_types: [str]=float # Specifies the types of embeddings you want to get back. Can be one or more of the following types.  * `\"float\"`: Use this when you want to get back the default float embeddings. Supported with all Embed models. * `\"int8\"`: Use this when you want to get back signed int8 embeddings. Supported with Embed v3.0 and newer Embed models. * `\"uint8\"`: Use this when you want to get back unsigned int8 embeddings. Supported with Embed v3.0 and newer Embed models. * `\"binary\"`: Use this when you want to get back signed binary embeddings. Supported with Embed v3.0 and newer Embed models. * `\"ubinary\"`: Use this when you want to get back unsigned binary embeddings. Supported with Embed v3.0 and newer Embed models. * `\"base64\"`: Use this when you want to get back base64 embeddings. Supported with Embed v3.0 and newer Embed models., truncate: str(NONE/START/END)=END # One of `NONE|START|END` to specify how the API will handle inputs longer than the maximum token length.  Passing `START` will discard the start of the input. `END` will discard the end of the input. In both cases, input is discarded until the remaining input is exactly the maximum input token length for the model.  If `NONE` is selected, when the input exceeds the maximum input token length an error will be returned., priority: int=0 # Controls how early the request is handled. Lower numbers indicate higher priority (default: 0, the highest). When the system is under load, higher-priority requests are processed first and are the least likely to be dropped.}\n@returns(200) {response_type: str, id: str, embeddings: map{float: [[num]], int8: [[int]], uint8: [[int]], binary: [[int]], ubinary: [[int]], base64: [str]}, texts: [str], images: [map], meta: map{api_version: map{version: str, is_deprecated: bool, is_experimental: bool}, billed_units: map{images: num, input_tokens: num, image_tokens: num, output_tokens: num, search_units: num, classifications: num}, tokens: map{input_tokens: num, output_tokens: num}, cached_tokens: num, warnings: [str]}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group audio\n@endpoint POST /v2/audio/transcriptions\n@desc Create a transcription\n@returns(200) {text: str} # A successful response.\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group batches\n@endpoint GET /v2/batches\n@desc List batches\n@optional {page_size: int(int32) # The maximum number of batches to return. The service may return fewer than this value. If unspecified, at most 50 batches will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000., page_token: str # A page token, received from a previous `ListBatches` call. Provide this to retrieve the subsequent page., order_by: str # Batches can be ordered by creation time or last updated time. Use `created_at` for creation time or `updated_at` for last updated time.}\n@returns(200) {batches: [map], next_page_token: str} # A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endpoint POST /v2/batches\n@desc Create a batch\n@required {name: str # Batch name (e.g. `foobar`)., input_dataset_id: str # ID of the dataset the batch reads inputs from., model: str # The name of the model the batch uses.}\n@optional {id: str # read-only. Batch ID., creator_id: str # read-only. User ID of the creator., org_id: str # read-only. Organization ID., status: str(BATCH_STATUS_UNSPECIFIED/BATCH_STATUS_QUEUED/BATCH_STATUS_IN_PROGRESS/BATCH_STATUS_CANCELING/BATCH_STATUS_COMPLETED/BATCH_STATUS_FAILED/BATCH_STATUS_CANCELED)=BATCH_STATUS_UNSPECIFIED # The possible stages of a batch life-cycle.   - BATCH_STATUS_UNSPECIFIED: Unspecified status.  - BATCH_STATUS_QUEUED: The batch has been queued.  - BATCH_STATUS_IN_PROGRESS: The batch is in-progress.  - BATCH_STATUS_CANCELING: The batch is being canceled.  - BATCH_STATUS_COMPLETED: The batch has been completed.  - BATCH_STATUS_FAILED: The batch has failed.  - BATCH_STATUS_CANCELED: The batch has been canceled., created_at: str(date-time) # read-only. Creation timestamp., updated_at: str(date-time) # read-only. Latest update timestamp., output_dataset_id: str, input_tokens: str(int64) # read-only. The total number of input tokens in the batch., output_tokens: str(int64) # read-only. The total number of output tokens in the batch., num_records: int(int32) # read-only. The total number of records in the batch., num_successful_records: int(int32) # read-only. The current number of successful records in the batch., num_failed_records: int(int32) # read-only. The current number of failed records in the batch., status_reason: str # read-only. More details about the reason for the status of a batch job.}\n@returns(200) {batch: map{id: str, name: str, creator_id: str, org_id: str, status: str, created_at: str(date-time), updated_at: str(date-time), input_dataset_id: str, output_dataset_id: str, input_tokens: str(int64), output_tokens: str(int64), model: str, num_records: int(int32), num_successful_records: int(int32), num_failed_records: int(int32), status_reason: str}} # A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endpoint GET /v2/batches/{id}\n@desc Retrieve a batch\n@required {id: str # The batch ID.}\n@returns(200) {batch: map{id: str, name: str, creator_id: str, org_id: str, status: str, created_at: str(date-time), updated_at: str(date-time), input_dataset_id: str, output_dataset_id: str, input_tokens: str(int64), output_tokens: str(int64), model: str, num_records: int(int32), num_successful_records: int(int32), num_failed_records: int(int32), status_reason: str}} # A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endpoint POST /v2/batches/{id}:cancel\n@desc Cancel a batch\n@required {id: str # The batch ID.}\n@returns(200) A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endgroup\n\n@group embed-jobs\n@endpoint POST /v1/embed-jobs\n@desc Create an Embed Job\n@required {model: str(string) # ID of the embedding model.  Available models and corresponding embedding dimensions:  - `embed-english-v3.0` : 1024 - `embed-multilingual-v3.0` : 1024 - `embed-english-light-v3.0` : 384 - `embed-multilingual-light-v3.0` : 384, dataset_id: str # ID of a [Dataset](https://docs.cohere.com/docs/datasets). The Dataset must be of type `embed-input` and must have a validation status `Validated`, input_type: str(search_document/search_query/classification/clustering/image) # Specifies the type of input passed to the model. Required for embedding models v3 and higher.  - `\"search_document\"`: Used for embeddings stored in a vector database for search use-cases. - `\"search_query\"`: Used for embeddings of search queries run against a vector DB to find relevant documents. - `\"classification\"`: Used for embeddings passed through a text classifier. - `\"clustering\"`: Used for the embeddings run through a clustering algorithm. - `\"image\"`: Used for embeddings with image input.}\n@optional {name: str # The name of the embed job., embedding_types: [str] # Specifies the types of embeddings you want to get back. Not required and default is None, which returns the Embed Floats response type. Can be one or more of the following types.  * `\"float\"`: Use this when you want to get back the default float embeddings. Valid for all models. * `\"int8\"`: Use this when you want to get back signed int8 embeddings. Valid for v3 and newer model versions. * `\"uint8\"`: Use this when you want to get back unsigned int8 embeddings. Valid for v3 and newer model versions. * `\"binary\"`: Use this when you want to get back signed binary embeddings. Valid for v3 and newer model versions. * `\"ubinary\"`: Use this when you want to get back unsigned binary embeddings. Valid for v3 and newer model versions., truncate: str(START/END)=END # One of `START|END` to specify how the API will handle inputs longer than the maximum token length.  Passing `START` will discard the start of the input. `END` will discard the end of the input. In both cases, input is discarded until the remaining input is exactly the maximum input token length for the model.}\n@returns(200) {job_id: str, meta: map{api_version: map{version: str, is_deprecated: bool, is_experimental: bool}, billed_units: map{images: num, input_tokens: num, image_tokens: num, output_tokens: num, search_units: num, classifications: num}, tokens: map{input_tokens: num, output_tokens: num}, cached_tokens: num, warnings: [str]}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint GET /v1/embed-jobs\n@desc List Embed Jobs\n@returns(200) {embed_jobs: [map]} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint GET /v1/embed-jobs/{id}\n@desc Fetch an Embed Job\n@required {id: str # The ID of the embed job to retrieve.}\n@returns(200) {job_id: str, name: str, status: str, created_at: str(date-time), input_dataset_id: str, output_dataset_id: str, model: str, truncate: str, meta: map{api_version: map{version: str, is_deprecated: bool, is_experimental: bool}, billed_units: map{images: num, input_tokens: num, image_tokens: num, output_tokens: num, search_units: num, classifications: num}, tokens: map{input_tokens: num, output_tokens: num}, cached_tokens: num, warnings: [str]}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint POST /v1/embed-jobs/{id}/cancel\n@desc Cancel an Embed Job\n@required {id: str # The ID of the embed job to cancel.}\n@returns(200) OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group rerank\n@endpoint POST /v1/rerank\n@desc Rerank API (v1)\n@required {query: str # The search query, documents: [any] # A list of document objects or strings to rerank. If a document is provided the text fields is required and all other fields will be preserved in the response.  The total max chunks (length of documents * max_chunks_per_doc) must be less than 10000.  We recommend a maximum of 1,000 documents for optimal endpoint performance.}\n@optional {model: str # The identifier of the model to use, eg `rerank-v3.5`., top_n: int # The number of most relevant documents or indices to return, defaults to the length of the documents, rank_fields: [str] # If a JSON object is provided, you can specify which keys you would like to have considered for reranking. The model will rerank based on order of the fields passed in (i.e. rank_fields=['title','author','text'] will rerank using the values in title, author, text  sequentially. If the length of title, author, and text exceeds the context length of the model, the chunking will not re-consider earlier fields). If not provided, the model will use the default text field for ranking., return_documents: bool=false # - If false, returns results without the doc text - the api will return a list of {index, relevance score} where index is inferred from the list passed into the request. - If true, returns results with the doc text passed in - the api will return an ordered list of {index, text, relevance score} where index + text refers to the list passed into the request., max_chunks_per_doc: int=10 # The maximum number of chunks to produce internally from a document}\n@returns(200) {id: str, results: [map], meta: map{api_version: map{version: str, is_deprecated: bool, is_experimental: bool}, billed_units: map{images: num, input_tokens: num, image_tokens: num, output_tokens: num, search_units: num, classifications: num}, tokens: map{input_tokens: num, output_tokens: num}, cached_tokens: num, warnings: [str]}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint POST /v2/rerank\n@desc Rerank API (v2)\n@required {model: str # The identifier of the model to use, eg `rerank-v3.5`., query: str # The search query, documents: [str] # A list of texts that will be compared to the `query`. For optimal performance we recommend against sending more than 1,000 documents in a single request.  **Note**: long documents will automatically be truncated to the value of `max_tokens_per_doc`.  **Note**: structured data should be formatted as YAML strings for best performance.}\n@optional {top_n: int # Limits the number of returned rerank results to the specified value. If not passed, all the rerank results will be returned., max_tokens_per_doc: int # Defaults to `4096`. Long documents will be automatically truncated to the specified number of tokens., priority: int=0 # Controls how early the request is handled. Lower numbers indicate higher priority (default: 0, the highest). When the system is under load, higher-priority requests are processed first and are the least likely to be dropped.}\n@returns(200) {id: str, results: [map], meta: map{api_version: map{version: str, is_deprecated: bool, is_experimental: bool}, billed_units: map{images: num, input_tokens: num, image_tokens: num, output_tokens: num, search_units: num, classifications: num}, tokens: map{input_tokens: num, output_tokens: num}, cached_tokens: num, warnings: [str]}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group classify\n@endpoint POST /v1/classify\n@desc Classify\n@required {inputs: [str] # A list of up to 96 texts to be classified. Each one must be a non-empty string. There is, however, no consistent, universal limit to the length a particular input can be. We perform classification on the first `x` tokens of each input, and `x` varies depending on which underlying model is powering classification. The maximum token length for each model is listed in the \"max tokens\" column [here](https://docs.cohere.com/docs/models). Note: by default the `truncate` parameter is set to `END`, so tokens exceeding the limit will be automatically dropped. This behavior can be disabled by setting `truncate` to `NONE`, which will result in validation errors for longer texts.}\n@optional {examples: [map{text: str, label: str}] # An array of examples to provide context to the model. Each example is a text string and its associated label/class. Each unique label requires at least 2 examples associated with it; the maximum number of examples is 2500, and each example has a maximum length of 512 tokens. The values should be structured as `{text: \"...\",label: \"...\"}`. Note: [Fine-tuned Models](https://docs.cohere.com/docs/classify-fine-tuning) trained on classification examples don't require the `examples` parameter to be passed in explicitly., model: str # ID of a [Fine-tuned](https://docs.cohere.com/v2/docs/classify-starting-the-training) Classify model, preset: str # The ID of a custom playground preset. You can create presets in the [playground](https://dashboard.cohere.com/playground). If you use a preset, all other parameters become optional, and any included parameters will override the preset's parameters., truncate: str(NONE/START/END)=END # One of `NONE|START|END` to specify how the API will handle inputs longer than the maximum token length. Passing `START` will discard the start of the input. `END` will discard the end of the input. In both cases, input is discarded until the remaining input is exactly the maximum input token length for the model. If `NONE` is selected, when the input exceeds the maximum input token length an error will be returned.}\n@returns(200) {id: str, classifications: [map], meta: map{api_version: map{version: str, is_deprecated: bool, is_experimental: bool}, billed_units: map{images: num, input_tokens: num, image_tokens: num, output_tokens: num, search_units: num, classifications: num}, tokens: map{input_tokens: num, output_tokens: num}, cached_tokens: num, warnings: [str]}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group datasets\n@endpoint POST /v1/datasets\n@desc Create a Dataset\n@required {name: str # The name of the uploaded dataset., type: str # The dataset type, which is used to validate the data. The only valid type is `embed-input` used in conjunction with the Embed Jobs API.}\n@optional {keep_original_file: bool # Indicates if the original file should be stored., skip_malformed_input: bool # Indicates whether rows with malformed input should be dropped (instead of failing the validation check). Dropped rows will be returned in the warnings field., keep_fields: [str] # List of names of fields that will be persisted in the Dataset. By default the Dataset will retain only the required fields indicated in the [schema for the corresponding Dataset type](https://docs.cohere.com/docs/datasets#dataset-types). For example, datasets of type `embed-input` will drop all fields other than the required `text` field. If any of the fields in `keep_fields` are missing from the uploaded file, Dataset validation will fail., optional_fields: [str] # List of names of fields that will be persisted in the Dataset. By default the Dataset will retain only the required fields indicated in the [schema for the corresponding Dataset type](https://docs.cohere.com/docs/datasets#dataset-types). For example, Datasets of type `embed-input` will drop all fields other than the required `text` field. If any of the fields in `optional_fields` are missing from the uploaded file, Dataset validation will pass., text_separator: str # Raw .txt uploads will be split into entries using the text_separator value., csv_delimiter: str # The delimiter used for .csv uploads.}\n@returns(200) {id: str} # A successful response.\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint GET /v1/datasets\n@desc List Datasets\n@optional {datasetType: str # optional filter by dataset type, before: str(date-time) # optional filter before a date, after: str(date-time) # optional filter after a date, limit: num # optional limit to number of results, offset: num # optional offset to start of results, validationStatus: str # optional filter by validation status}\n@returns(200) {datasets: [map]} # A successful response.\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint GET /v1/datasets/usage\n@desc Get Dataset Usage\n@returns(200) {organization_usage: num(int64)} # A successful response.\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint GET /v1/datasets/{id}\n@desc Get a Dataset\n@required {id: str}\n@returns(200) {dataset: map{id: str, name: str, created_at: str(date-time), updated_at: str(date-time), dataset_type: str, validation_status: str, validation_error: str, schema: str, required_fields: [str], preserve_fields: [str], dataset_parts: [map], validation_warnings: [str], parse_info: map{separator: str, delimiter: str}, metrics: map{finetune_dataset_metrics: map{trainable_token_count: num(int64), total_examples: num(int64), train_examples: num(int64), train_size_bytes: num(int64), eval_examples: num(int64), eval_size_bytes: num(int64), reranker_data_metrics: map, chat_data_metrics: map, classify_data_metrics: map}}}} # A successful response.\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint DELETE /v1/datasets/{id}\n@desc Delete a Dataset\n@required {id: str}\n@returns(200) A successful response.\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group summarize\n@endpoint POST /v1/summarize\n@desc Summarize\n@required {text: str # The text to generate a summary for. Can be up to 100,000 characters long. Currently the only supported language is English.}\n@optional {length: str(short/medium/long)=medium # One of `short`, `medium`, `long`, or `auto` defaults to `auto`. Indicates the approximate length of the summary. If `auto` is selected, the best option will be picked based on the input text., format: str(paragraph/bullets)=paragraph # One of `paragraph`, `bullets`, or `auto`, defaults to `auto`. Indicates the style in which the summary will be delivered - in a free form paragraph or in bullet points. If `auto` is selected, the best option will be picked based on the input text., model: str # The identifier of the model to generate the summary with. Currently available models are `command` (default), `command-nightly` (experimental), `command-light`, and `command-light-nightly` (experimental). Smaller, \"light\" models are faster, while larger models will perform better., extractiveness: str(low/medium/high)=low # One of `low`, `medium`, `high`, or `auto`, defaults to `auto`. Controls how close to the original text the summary is. `high` extractiveness summaries will lean towards reusing sentences verbatim, while `low` extractiveness summaries will tend to paraphrase more. If `auto` is selected, the best option will be picked based on the input text., temperature: num=0.3 # Ranges from 0 to 5. Controls the randomness of the output. Lower values tend to generate more “predictable” output, while higher values tend to generate more “creative” output. The sweet spot is typically between 0 and 1., additional_command: str # A free-form instruction for modifying how the summaries get generated. Should complete the sentence \"Generate a summary _\". Eg. \"focusing on the next steps\" or \"written by Yoda\"}\n@returns(200) {id: str, summary: str, meta: map{api_version: map{version: str, is_deprecated: bool, is_experimental: bool}, billed_units: map{images: num, input_tokens: num, image_tokens: num, output_tokens: num, search_units: num, classifications: num}, tokens: map{input_tokens: num, output_tokens: num}, cached_tokens: num, warnings: [str]}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group tokenize\n@endpoint POST /v1/tokenize\n@desc Tokenize\n@required {text: str # The string to be tokenized, the minimum text length is 1 character, and the maximum text length is 65536 characters., model: str # The input will be tokenized by the tokenizer that is used by this model.}\n@returns(200) {tokens: [int], token_strings: [str], meta: map{api_version: map{version: str, is_deprecated: bool, is_experimental: bool}, billed_units: map{images: num, input_tokens: num, image_tokens: num, output_tokens: num, search_units: num, classifications: num}, tokens: map{input_tokens: num, output_tokens: num}, cached_tokens: num, warnings: [str]}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n@example_request {\"text\":\"tokenize me! :D\",\"model\":\"command\"}\n\n@endgroup\n\n@group detokenize\n@endpoint POST /v1/detokenize\n@desc Detokenize\n@required {tokens: [int] # The list of tokens to be detokenized., model: str # An optional parameter to provide the model name. This will ensure that the detokenization is done by the tokenizer used by that model.}\n@returns(200) {text: str, meta: map{api_version: map{version: str, is_deprecated: bool, is_experimental: bool}, billed_units: map{images: num, input_tokens: num, image_tokens: num, output_tokens: num, search_units: num, classifications: num}, tokens: map{input_tokens: num, output_tokens: num}, cached_tokens: num, warnings: [str]}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group connectors\n@endpoint GET /v1/connectors\n@desc List Connectors\n@optional {limit: num=30 # Maximum number of connectors to return [0, 100]., offset: num=0 # Number of connectors to skip before returning results [0, inf].}\n@returns(200) {connectors: [map], total_count: num} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint POST /v1/connectors\n@desc Create a Connector\n@required {name: str # A human-readable name for the connector., url: str # The URL of the connector that will be used to search for documents.}\n@optional {description: str # A description of the connector., excludes: [str] # A list of fields to exclude from the prompt (fields remain in the document)., oauth: map{client_id: str, client_secret: str, authorize_url: str, token_url: str, scope: str}, active: bool=true # Whether the connector is active or not., continue_on_failure: bool=false # Whether a chat request should continue or not if the request to this connector fails., service_auth: map{type!: str, token!: str}}\n@returns(200) {connector: map{id: str, organization_id: str, name: str, description: str, url: str, created_at: str(date-time), updated_at: str(date-time), excludes: [str], auth_type: str(enum), oauth: map{client_id: str, client_secret: str, authorize_url: str, token_url: str, scope: str}, auth_status: str, active: bool, continue_on_failure: bool}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint GET /v1/connectors/{id}\n@desc Get a Connector\n@required {id: str # The ID of the connector to retrieve.}\n@returns(200) {connector: map{id: str, organization_id: str, name: str, description: str, url: str, created_at: str(date-time), updated_at: str(date-time), excludes: [str], auth_type: str(enum), oauth: map{client_id: str, client_secret: str, authorize_url: str, token_url: str, scope: str}, auth_status: str, active: bool, continue_on_failure: bool}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint PATCH /v1/connectors/{id}\n@desc Update a Connector\n@required {id: str # The ID of the connector to update.}\n@optional {name: str # A human-readable name for the connector., url: str # The URL of the connector that will be used to search for documents., excludes: [str] # A list of fields to exclude from the prompt (fields remain in the document)., oauth: map{client_id: str, client_secret: str, authorize_url: str, token_url: str, scope: str}, active: bool=true, continue_on_failure: bool=false, service_auth: map{type!: str, token!: str}}\n@returns(200) {connector: map{id: str, organization_id: str, name: str, description: str, url: str, created_at: str(date-time), updated_at: str(date-time), excludes: [str], auth_type: str(enum), oauth: map{client_id: str, client_secret: str, authorize_url: str, token_url: str, scope: str}, auth_status: str, active: bool, continue_on_failure: bool}} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint DELETE /v1/connectors/{id}\n@desc Delete a Connector\n@required {id: str # The ID of the connector to delete.}\n@returns(200) OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint POST /v1/connectors/{id}/oauth/authorize\n@desc Authorize with oAuth\n@required {id: str # The ID of the connector to authorize.}\n@optional {after_token_redirect: str # The URL to redirect to after the connector has been authorized.}\n@returns(200) {redirect_url: str} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group models\n@endpoint GET /v1/models/{model}\n@desc Get a Model\n@required {model: str}\n@returns(200) {name: str, is_deprecated: bool, endpoints: [str], finetuned: bool, context_length: num, tokenizer_url: str, default_endpoints: [str], features: [str]} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endpoint GET /v1/models\n@desc List Models\n@optional {page_size: num # Maximum number of models to include in a page Defaults to `20`, min value of `1`, max value of `1000`., page_token: str # Page token provided in the `next_page_token` field of a previous response., endpoint: str # When provided, filters the list of models to only those that are compatible with the specified endpoint., default_only: bool # When provided, filters the list of models to only the default model to the endpoint. This parameter is only valid when `endpoint` is provided.}\n@returns(200) {models: [map], next_page_token: str} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group check-api-key\n@endpoint POST /v1/check-api-key\n@desc Check API key\n@returns(200) {valid: bool, organization_id: str, owner_id: str} # OK\n@errors {400: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 401: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 403: This error indicates that the operation attempted to be performed is not allowed. This could be because:   - The api token is invalid   - The user does not have the necessary permissions, 404: This error is returned when a resource is not found. This could be because:   - The endpoint does not exist   - The resource does not exist eg model id, dataset id, 422: This error is returned when the request is not well formed. This could be because:   - JSON is invalid   - The request is missing required fields   - The request contains an invalid combination of fields, 429: Too many requests, 498: This error is returned when a request or response contains a deny-listed token., 499: This error is returned when a request is cancelled by the user., 500: This error is returned when an uncategorised internal server error occurs., 501: This error is returned when the requested feature is not implemented., 503: This error is returned when the service is unavailable. This could be due to:   - Too many users trying to access the service at the same time, 504: This error is returned when a request to the server times out. This could be due to:   - An internal services taking too long to respond}\n\n@endgroup\n\n@group finetuning\n@endpoint GET /v1/finetuning/finetuned-models\n@desc Lists fine-tuned models.\n@optional {page_size: int(int32) # Maximum number of results to be returned by the server. If 0, defaults to 50., page_token: str # Request a specific page of the list results., order_by: str # Comma separated list of fields. For example: \"created_at,name\". The default sorting order is ascending. To specify descending order for a field, append \" desc\" to the field name. For example: \"created_at desc,name\".  Supported sorting fields:   - created_at (default)}\n@returns(200) {finetuned_models: [map], next_page_token: str, total_size: int(int32)} # A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endpoint POST /v1/finetuning/finetuned-models\n@desc Trains and deploys a fine-tuned model.\n@required {name: str # FinetunedModel name (e.g. `foobar`)., settings: map{base_model!: map, dataset_id!: str, hyperparameters: map, multi_label: bool, wandb: map} # The configuration used for fine-tuning.}\n@optional {id: str # read-only. FinetunedModel ID., creator_id: str # read-only. User ID of the creator., organization_id: str # read-only. Organization ID., status: str(STATUS_UNSPECIFIED/STATUS_FINETUNING/STATUS_DEPLOYING_API/STATUS_READY/STATUS_FAILED/STATUS_DELETED/STATUS_TEMPORARILY_OFFLINE/STATUS_PAUSED/STATUS_QUEUED)=STATUS_UNSPECIFIED # The possible stages of a fine-tuned model life-cycle.   - STATUS_UNSPECIFIED: Unspecified status.  - STATUS_FINETUNING: The fine-tuned model is being fine-tuned.  - STATUS_DEPLOYING_API: Deprecated: The fine-tuned model is being deployed.  - STATUS_READY: The fine-tuned model is ready to receive requests.  - STATUS_FAILED: The fine-tuned model failed.  - STATUS_DELETED: The fine-tuned model was deleted.  - STATUS_TEMPORARILY_OFFLINE: Deprecated: The fine-tuned model is temporarily unavailable.  - STATUS_PAUSED: Deprecated: The fine-tuned model is paused (Vanilla only).  - STATUS_QUEUED: The fine-tuned model is queued for training., created_at: str(date-time) # read-only. Creation timestamp., updated_at: str(date-time) # read-only. Latest update timestamp., completed_at: str(date-time) # read-only. Timestamp for the completed fine-tuning., last_used: str(date-time) # read-only. Deprecated: Timestamp for the latest request to this fine-tuned model.}\n@returns(200) {finetuned_model: map{id: str, name: str, creator_id: str, organization_id: str, settings: map{base_model: map{name: str, version: str, base_type: str, strategy: str}, dataset_id: str, hyperparameters: map{early_stopping_patience: int(int32), early_stopping_threshold: num(double), train_batch_size: int(int32), train_epochs: int(int32), learning_rate: num(double), lora_alpha: int(int32), lora_rank: int(int32), lora_target_modules: str}, multi_label: bool, wandb: map{project: str, api_key: str, entity: str}}, status: str, created_at: str(date-time), updated_at: str(date-time), completed_at: str(date-time), last_used: str(date-time)}} # A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endpoint PATCH /v1/finetuning/finetuned-models/{id}\n@desc Updates a fine-tuned model.\n@required {id: str # FinetunedModel ID., name: str # FinetunedModel name (e.g. `foobar`)., settings: map{base_model!: map, dataset_id!: str, hyperparameters: map, multi_label: bool, wandb: map} # The configuration used for fine-tuning.}\n@optional {creator_id: str # User ID of the creator., organization_id: str # Organization ID., status: str(STATUS_UNSPECIFIED/STATUS_FINETUNING/STATUS_DEPLOYING_API/STATUS_READY/STATUS_FAILED/STATUS_DELETED/STATUS_TEMPORARILY_OFFLINE/STATUS_PAUSED/STATUS_QUEUED)=STATUS_UNSPECIFIED # The possible stages of a fine-tuned model life-cycle.   - STATUS_UNSPECIFIED: Unspecified status.  - STATUS_FINETUNING: The fine-tuned model is being fine-tuned.  - STATUS_DEPLOYING_API: Deprecated: The fine-tuned model is being deployed.  - STATUS_READY: The fine-tuned model is ready to receive requests.  - STATUS_FAILED: The fine-tuned model failed.  - STATUS_DELETED: The fine-tuned model was deleted.  - STATUS_TEMPORARILY_OFFLINE: Deprecated: The fine-tuned model is temporarily unavailable.  - STATUS_PAUSED: Deprecated: The fine-tuned model is paused (Vanilla only).  - STATUS_QUEUED: The fine-tuned model is queued for training., created_at: str(date-time) # Creation timestamp., updated_at: str(date-time) # Latest update timestamp., completed_at: str(date-time) # Timestamp for the completed fine-tuning., last_used: str(date-time) # Deprecated: Timestamp for the latest request to this fine-tuned model.}\n@returns(200) {finetuned_model: map{id: str, name: str, creator_id: str, organization_id: str, settings: map{base_model: map{name: str, version: str, base_type: str, strategy: str}, dataset_id: str, hyperparameters: map{early_stopping_patience: int(int32), early_stopping_threshold: num(double), train_batch_size: int(int32), train_epochs: int(int32), learning_rate: num(double), lora_alpha: int(int32), lora_rank: int(int32), lora_target_modules: str}, multi_label: bool, wandb: map{project: str, api_key: str, entity: str}}, status: str, created_at: str(date-time), updated_at: str(date-time), completed_at: str(date-time), last_used: str(date-time)}} # A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endpoint GET /v1/finetuning/finetuned-models/{id}\n@desc Returns a fine-tuned model by ID.\n@required {id: str # The fine-tuned model ID.}\n@returns(200) {finetuned_model: map{id: str, name: str, creator_id: str, organization_id: str, settings: map{base_model: map{name: str, version: str, base_type: str, strategy: str}, dataset_id: str, hyperparameters: map{early_stopping_patience: int(int32), early_stopping_threshold: num(double), train_batch_size: int(int32), train_epochs: int(int32), learning_rate: num(double), lora_alpha: int(int32), lora_rank: int(int32), lora_target_modules: str}, multi_label: bool, wandb: map{project: str, api_key: str, entity: str}}, status: str, created_at: str(date-time), updated_at: str(date-time), completed_at: str(date-time), last_used: str(date-time)}} # A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endpoint DELETE /v1/finetuning/finetuned-models/{id}\n@desc Deletes a fine-tuned model.\n@required {id: str # The fine-tuned model ID.}\n@returns(200) A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endpoint GET /v1/finetuning/finetuned-models/{finetuned_model_id}/events\n@desc Fetch history of statuses for a fine-tuned model.\n@required {finetuned_model_id: str # The parent fine-tuned model ID.}\n@optional {page_size: int(int32) # Maximum number of results to be returned by the server. If 0, defaults to 50., page_token: str # Request a specific page of the list results., order_by: str # Comma separated list of fields. For example: \"created_at,name\". The default sorting order is ascending. To specify descending order for a field, append \" desc\" to the field name. For example: \"created_at desc,name\".  Supported sorting fields:   - created_at (default)}\n@returns(200) {events: [map], next_page_token: str, total_size: int(int32)} # A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endpoint GET /v1/finetuning/finetuned-models/{finetuned_model_id}/training-step-metrics\n@desc Retrieve training metrics for fine-tuned models.\n@required {finetuned_model_id: str # The parent fine-tuned model ID.}\n@optional {page_size: int(int32) # Maximum number of results to be returned by the server. If 0, defaults to 50., page_token: str # Request a specific page of the list results.}\n@returns(200) {step_metrics: [map], next_page_token: str} # A successful response.\n@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Internal Server Error, 503: Status Service Unavailable}\n\n@endgroup\n\n@end\n"}