@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api API Reference
@base https://api.cohere.com
@version 1.0
@auth Bearer bearer
@common_fields {X-Client-Name: str}
@endpoints 41
@hint download_for_search
@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)

@group chat
@endpoint POST /v1/chat
@required {message: str}
@optional {Accepts: str, model: str, stream: bool, preamble: str, chat_history: [any], conversation_id: str, prompt_truncation: str(OFF/AUTO/AUTO_PRESERVE_ORDER), connectors: [map{id!: str, user_access_token: str, continue_on_failure: bool, options: map}], search_queries_only: bool, documents: [map{id: str}], citation_quality: str(ENABLED/DISABLED/FAST/ACCURATE/OFF), temperature: num(float), max_tokens: int, max_input_tokens: int, k: int=0, p: num=0.75, seed: int, stop_sequences: [str], frequency_penalty: num, presence_penalty: num, raw_prompting: bool, tools: [map{name!: str, description!: str, parameter_definitions: map}], tool_results: [map{call!: map, outputs!: [map]}], force_single_step: bool, response_format: any, safety_mode: any(CONTEXTUAL/STRICT/NONE)}
@returns(200)
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint POST /v2/chat
@required {model: str, messages: [any]}
@optional {stream: bool, tools: [map{type!: str, function: map}], strict_tools: bool, documents: [any], citation_options: map{mode: str}, response_format: any, safety_mode: any(CONTEXTUAL/STRICT/OFF), max_tokens: int, stop_sequences: [str], temperature: num(float), seed: int, frequency_penalty: num(float), presence_penalty: num(float), k: int=0, p: num(float)=0.75, logprobs: bool, tool_choice: any(REQUIRED/NONE), thinking: map{type!: str, token_budget: int}, priority: int=0}
@returns(200)
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group generate
@endpoint POST /v1/generate
@required {prompt: str}
@optional {model: str, num_generations: int, stream: bool, max_tokens: int, truncate: str(NONE/START/END)=END, temperature: num, seed: int, preset: str, end_sequences: [str], stop_sequences: [str], k: int, p: num, frequency_penalty: num, presence_penalty: num, return_likelihoods: str(GENERATION/ALL/NONE)=NONE, raw_prompting: bool}
@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]}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group embed
@endpoint POST /v1/embed
@optional {texts: [str], images: [str], model: str, input_type: str(search_document/search_query/classification/clustering/image), embedding_types: [str], truncate: str(NONE/START/END)=END}
@returns(200)
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint POST /v2/embed
@required {model: str, input_type: str(search_document/search_query/classification/clustering/image)}
@optional {texts: [str], images: [str], inputs: [map{content!: [any]}], max_tokens: int, output_dimension: int, embedding_types: [str]=float, truncate: str(NONE/START/END)=END, priority: int=0}
@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]}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group audio
@endpoint POST /v2/audio/transcriptions
@returns(200) {text: str}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group batches
@endpoint GET /v2/batches
@optional {page_size: int(int32), page_token: str, order_by: str}
@returns(200) {batches: [map], next_page_token: str}
@errors {400, 401, 403, 404, 500, 503}

@endpoint POST /v2/batches
@required {name: str, input_dataset_id: str, model: str}
@optional {id: str, creator_id: str, org_id: str, 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, created_at: str(date-time), updated_at: str(date-time), output_dataset_id: str, input_tokens: str(int64), output_tokens: str(int64), num_records: int(int32), num_successful_records: int(int32), num_failed_records: int(int32), status_reason: str}
@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}}
@errors {400, 401, 403, 404, 500, 503}

@endpoint GET /v2/batches/{id}
@required {id: str}
@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}}
@errors {400, 401, 403, 404, 500, 503}

@endpoint POST /v2/batches/{id}:cancel
@required {id: str}
@returns(200)
@errors {400, 401, 403, 404, 500, 503}

@endgroup

@group embed-jobs
@endpoint POST /v1/embed-jobs
@required {model: str(string), dataset_id: str, input_type: str(search_document/search_query/classification/clustering/image)}
@optional {name: str, embedding_types: [str], truncate: str(START/END)=END}
@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]}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint GET /v1/embed-jobs
@returns(200) {embed_jobs: [map]}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint GET /v1/embed-jobs/{id}
@required {id: str}
@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]}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint POST /v1/embed-jobs/{id}/cancel
@required {id: str}
@returns(200)
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group rerank
@endpoint POST /v1/rerank
@required {query: str, documents: [any]}
@optional {model: str, top_n: int, rank_fields: [str], return_documents: bool=false, max_chunks_per_doc: int=10}
@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]}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint POST /v2/rerank
@required {model: str, query: str, documents: [str]}
@optional {top_n: int, max_tokens_per_doc: int, priority: int=0}
@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]}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group classify
@endpoint POST /v1/classify
@required {inputs: [str]}
@optional {examples: [map{text: str, label: str}], model: str, preset: str, truncate: str(NONE/START/END)=END}
@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]}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group datasets
@endpoint POST /v1/datasets
@required {name: str, type: str}
@optional {keep_original_file: bool, skip_malformed_input: bool, keep_fields: [str], optional_fields: [str], text_separator: str, csv_delimiter: str}
@returns(200) {id: str}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint GET /v1/datasets
@optional {datasetType: str, before: str(date-time), after: str(date-time), limit: num, offset: num, validationStatus: str}
@returns(200) {datasets: [map]}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint GET /v1/datasets/usage
@returns(200) {organization_usage: num(int64)}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint GET /v1/datasets/{id}
@required {id: str}
@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}}}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint DELETE /v1/datasets/{id}
@required {id: str}
@returns(200)
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group summarize
@endpoint POST /v1/summarize
@required {text: str}
@optional {length: str(short/medium/long)=medium, format: str(paragraph/bullets)=paragraph, model: str, extractiveness: str(low/medium/high)=low, temperature: num=0.3, additional_command: str}
@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]}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group tokenize
@endpoint POST /v1/tokenize
@required {text: str, model: str}
@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]}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group detokenize
@endpoint POST /v1/detokenize
@required {tokens: [int], model: str}
@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]}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group connectors
@endpoint GET /v1/connectors
@optional {limit: num=30, offset: num=0}
@returns(200) {connectors: [map], total_count: num}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint POST /v1/connectors
@required {name: str, url: str}
@optional {description: str, excludes: [str], 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}}
@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}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint GET /v1/connectors/{id}
@required {id: str}
@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}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint PATCH /v1/connectors/{id}
@required {id: str}
@optional {name: str, url: str, excludes: [str], 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}}
@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}}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint DELETE /v1/connectors/{id}
@required {id: str}
@returns(200)
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint POST /v1/connectors/{id}/oauth/authorize
@required {id: str}
@optional {after_token_redirect: str}
@returns(200) {redirect_url: str}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group models
@endpoint GET /v1/models/{model}
@required {model: str}
@returns(200) {name: str, is_deprecated: bool, endpoints: [str], finetuned: bool, context_length: num, tokenizer_url: str, default_endpoints: [str], features: [str]}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endpoint GET /v1/models
@optional {page_size: num, page_token: str, endpoint: str, default_only: bool}
@returns(200) {models: [map], next_page_token: str}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group check-api-key
@endpoint POST /v1/check-api-key
@returns(200) {valid: bool, organization_id: str, owner_id: str}
@errors {400, 401, 403, 404, 422, 429, 498, 499, 500, 501, 503, 504}

@endgroup

@group finetuning
@endpoint GET /v1/finetuning/finetuned-models
@optional {page_size: int(int32), page_token: str, order_by: str}
@returns(200) {finetuned_models: [map], next_page_token: str, total_size: int(int32)}
@errors {400, 401, 403, 404, 500, 503}

@endpoint POST /v1/finetuning/finetuned-models
@required {name: str, settings: map{base_model!: map, dataset_id!: str, hyperparameters: map, multi_label: bool, wandb: map}}
@optional {id: str, creator_id: str, organization_id: str, status: str(STATUS_UNSPECIFIED/STATUS_FINETUNING/STATUS_DEPLOYING_API/STATUS_READY/STATUS_FAILED/STATUS_DELETED/STATUS_TEMPORARILY_OFFLINE/STATUS_PAUSED/STATUS_QUEUED)=STATUS_UNSPECIFIED, created_at: str(date-time), updated_at: str(date-time), completed_at: str(date-time), last_used: str(date-time)}
@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)}}
@errors {400, 401, 403, 404, 500, 503}

@endpoint PATCH /v1/finetuning/finetuned-models/{id}
@required {id: str, name: str, settings: map{base_model!: map, dataset_id!: str, hyperparameters: map, multi_label: bool, wandb: map}}
@optional {creator_id: str, organization_id: str, status: str(STATUS_UNSPECIFIED/STATUS_FINETUNING/STATUS_DEPLOYING_API/STATUS_READY/STATUS_FAILED/STATUS_DELETED/STATUS_TEMPORARILY_OFFLINE/STATUS_PAUSED/STATUS_QUEUED)=STATUS_UNSPECIFIED, created_at: str(date-time), updated_at: str(date-time), completed_at: str(date-time), last_used: str(date-time)}
@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)}}
@errors {400, 401, 403, 404, 500, 503}

@endpoint GET /v1/finetuning/finetuned-models/{id}
@required {id: str}
@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)}}
@errors {400, 401, 403, 404, 500, 503}

@endpoint DELETE /v1/finetuning/finetuned-models/{id}
@required {id: str}
@returns(200)
@errors {400, 401, 403, 404, 500, 503}

@endpoint GET /v1/finetuning/finetuned-models/{finetuned_model_id}/events
@required {finetuned_model_id: str}
@optional {page_size: int(int32), page_token: str, order_by: str}
@returns(200) {events: [map], next_page_token: str, total_size: int(int32)}
@errors {400, 401, 403, 404, 500, 503}

@endpoint GET /v1/finetuning/finetuned-models/{finetuned_model_id}/training-step-metrics
@required {finetuned_model_id: str}
@optional {page_size: int(int32), page_token: str}
@returns(200) {step_metrics: [map], next_page_token: str}
@errors {400, 401, 403, 404, 500, 503}

@endgroup

@end