Skip to main content
API docs by Redocly

Mistral AI API (1.0.0)

Download OpenAPI specification:Download

Our Chat Completion and Embeddings APIs specification. Create your account on La Plateforme to get access and read the docs to learn how to use it.

Chat

Chat Completion API.

Chat Completion

Authorizations:
ApiKey
Request Body schema: application/json
required
model
required
string (Model)

ID of the model to use. You can use the List Available Models API to see all of your available models, or see our Model overview for model descriptions.

Temperature (number) or Temperature (null) (Temperature)

What sampling temperature to use, we recommend between 0.0 and 0.7. Higher values like 0.7 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. The default value varies depending on the model you are targeting. Call the /models endpoint to retrieve the appropriate value.

top_p
number (Top P) [ 0 .. 1 ]
Default: 1

Nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.

Max Tokens (integer) or Max Tokens (null) (Max Tokens)

The maximum number of tokens to generate in the completion. The token count of your prompt plus max_tokens cannot exceed the model's context length.

stream
boolean (Stream)
Default: false

Whether to stream back partial progress. If set, tokens will be sent as data-only server-side events as they become available, with the stream terminated by a data: [DONE] message. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.

Stop (string) or Array of Stop (strings) (Stop)

Stop generation if this token is detected. Or if one of these tokens is detected when providing an array

Random Seed (integer) or Random Seed (null) (Random Seed)

The seed to use for random sampling. If set, different calls will generate deterministic results.

required
Array of any (Messages)

The prompt(s) to generate completions for, encoded as a list of dict with role and content.

object (ResponseFormat)
Array of Tools (objects) or Tools (null) (Tools)
ToolChoice (object) or ToolChoiceEnum (string) (Tool Choice)
Default: "auto"
presence_penalty
number (Presence Penalty) [ -2 .. 2 ]
Default: 0

presence_penalty determines how much the model penalizes the repetition of words or phrases. A higher presence penalty encourages the model to use a wider variety of words and phrases, making the output more diverse and creative.

frequency_penalty
number (Frequency Penalty) [ -2 .. 2 ]
Default: 0

frequency_penalty penalizes the repetition of words based on their frequency in the generated text. A higher frequency penalty discourages the model from repeating words that have already appeared frequently in the output, promoting diversity and reducing repetition.

N (integer) or N (null) (N)

Number of completions to return for each request, input tokens are only billed once.

object (Prediction)
Default: {"type":"content","content":""}

Enable users to specify expected results, optimizing response times by leveraging known or predictable content. This approach is especially effective for updating text documents or code files with minimal changes, reducing latency while maintaining high-quality results.

parallel_tool_calls
boolean (Parallel Tool Calls)
Default: true
MistralPromptMode (string) or null

Allows toggling between the reasoning mode and no system prompt. When set to reasoning the system prompt for reasoning models will be used.

safe_prompt
boolean
Default: false

Whether to inject a safety prompt before all conversations.

Responses

Request samples

Content type
application/json
{
  • "model": "mistral-small-latest",
  • "temperature": 1.5,
  • "top_p": 1,
  • "max_tokens": 0,
  • "stream": false,
  • "stop": "string",
  • "random_seed": 0,
  • "messages": [
    ],
  • "response_format": {
    },
  • "tools": [
    ],
  • "tool_choice": "auto",
  • "presence_penalty": 0,
  • "frequency_penalty": 0,
  • "n": 1,
  • "prediction": {
    },
  • "parallel_tool_calls": true,
  • "prompt_mode": "reasoning",
  • "safe_prompt": false
}

Response samples

Content type
{
  • "id": "cmpl-e5cc70bb28c444948073e77776eb30ef",
  • "object": "chat.completion",
  • "model": "mistral-small-latest",
  • "usage": {
    },
  • "created": 1702256327,
  • "choices": [
    ]
}

FIM

Fill-in-the-middle API.

Fim Completion

FIM completion.

Authorizations:
ApiKey
Request Body schema: application/json
required
model
required
string (Model)
Default: "codestral-2405"

ID of the model to use. Only compatible for now with:

  • codestral-2405
  • codestral-latest
Temperature (number) or Temperature (null) (Temperature)

What sampling temperature to use, we recommend between 0.0 and 0.7. Higher values like 0.7 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. The default value varies depending on the model you are targeting. Call the /models endpoint to retrieve the appropriate value.

top_p
number (Top P) [ 0 .. 1 ]
Default: 1

Nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.

Max Tokens (integer) or Max Tokens (null) (Max Tokens)

The maximum number of tokens to generate in the completion. The token count of your prompt plus max_tokens cannot exceed the model's context length.

stream
boolean (Stream)
Default: false

Whether to stream back partial progress. If set, tokens will be sent as data-only server-side events as they become available, with the stream terminated by a data: [DONE] message. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.

Stop (string) or Array of Stop (strings) (Stop)

Stop generation if this token is detected. Or if one of these tokens is detected when providing an array

Random Seed (integer) or Random Seed (null) (Random Seed)

The seed to use for random sampling. If set, different calls will generate deterministic results.

prompt
required
string (Prompt)

The text/code to complete.

Suffix (string) or Suffix (null) (Suffix)
Default: ""

Optional text/code that adds more context for the model. When given a prompt and a suffix the model will fill what is between them. When suffix is not provided, the model will simply execute completion starting with prompt.

Min Tokens (integer) or Min Tokens (null) (Min Tokens)

The minimum number of tokens to generate in the completion.

Responses

Request samples

Content type
application/json
{
  • "model": "codestral-2405",
  • "temperature": 1.5,
  • "top_p": 1,
  • "max_tokens": 0,
  • "stream": false,
  • "stop": "string",
  • "random_seed": 0,
  • "prompt": "def",
  • "suffix": "return a+b",
  • "min_tokens": 0
}

Response samples

Content type
{
  • "id": "cmpl-e5cc70bb28c444948073e77776eb30ef",
  • "object": "chat.completion",
  • "model": "codestral-latest",
  • "usage": {
    },
  • "created": 1702256327,
  • "choices": [
    ]
}

Agents

Agents API.

Agents Completion

Authorizations:
ApiKey
Request Body schema: application/json
required
Max Tokens (integer) or Max Tokens (null) (Max Tokens)

The maximum number of tokens to generate in the completion. The token count of your prompt plus max_tokens cannot exceed the model's context length.

stream
boolean (Stream)
Default: false

Whether to stream back partial progress. If set, tokens will be sent as data-only server-side events as they become available, with the stream terminated by a data: [DONE] message. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.

Stop (string) or Array of Stop (strings) (Stop)

Stop generation if this token is detected. Or if one of these tokens is detected when providing an array

Random Seed (integer) or Random Seed (null) (Random Seed)

The seed to use for random sampling. If set, different calls will generate deterministic results.

required
Array of any (Messages)

The prompt(s) to generate completions for, encoded as a list of dict with role and content.

object (ResponseFormat)
Array of Tools (objects) or Tools (null) (Tools)
ToolChoice (object) or ToolChoiceEnum (string) (Tool Choice)
Default: "auto"
presence_penalty
number (Presence Penalty) [ -2 .. 2 ]
Default: 0

presence_penalty determines how much the model penalizes the repetition of words or phrases. A higher presence penalty encourages the model to use a wider variety of words and phrases, making the output more diverse and creative.

frequency_penalty
number (Frequency Penalty) [ -2 .. 2 ]
Default: 0

frequency_penalty penalizes the repetition of words based on their frequency in the generated text. A higher frequency penalty discourages the model from repeating words that have already appeared frequently in the output, promoting diversity and reducing repetition.

N (integer) or N (null) (N)

Number of completions to return for each request, input tokens are only billed once.

object (Prediction)
Default: {"type":"content","content":""}

Enable users to specify expected results, optimizing response times by leveraging known or predictable content. This approach is especially effective for updating text documents or code files with minimal changes, reducing latency while maintaining high-quality results.

parallel_tool_calls
boolean (Parallel Tool Calls)
Default: true
MistralPromptMode (string) or null

Allows toggling between the reasoning mode and no system prompt. When set to reasoning the system prompt for reasoning models will be used.

agent_id
required
string

The ID of the agent to use for this completion.

Responses

Request samples

Content type
application/json
{
  • "max_tokens": 0,
  • "stream": false,
  • "stop": "string",
  • "random_seed": 0,
  • "messages": [
    ],
  • "response_format": {
    },
  • "tools": [
    ],
  • "tool_choice": "auto",
  • "presence_penalty": 0,
  • "frequency_penalty": 0,
  • "n": 1,
  • "prediction": {
    },
  • "parallel_tool_calls": true,
  • "prompt_mode": "reasoning",
  • "agent_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "cmpl-e5cc70bb28c444948073e77776eb30ef",
  • "object": "chat.completion",
  • "model": "mistral-small-latest",
  • "usage": {
    },
  • "created": 1702256327,
  • "choices": [
    ]
}

Embeddings

Embeddings API.

Embeddings

Embeddings

Authorizations:
ApiKey
Request Body schema: application/json
required
model
required
string (Model)

ID of the model to use.

required
Input (string) or Array of Input (strings) (Input)

Text to embed.

Output Dimension (integer) or Output Dimension (null) (Output Dimension)

The dimension of the output embeddings.

output_dtype
string (EmbeddingDtype)
Default: "float"
Enum: "float" "int8" "uint8" "binary" "ubinary"

The data type of the output embeddings.

Responses

Request samples

Content type
application/json
{
  • "model": "mistral-embed",
  • "input": [
    ],
  • "output_dimension": 0,
  • "output_dtype": "float"
}

Response samples

Content type
application/json
{
  • "id": "cmpl-e5cc70bb28c444948073e77776eb30ef",
  • "object": "chat.completion",
  • "model": "mistral-small-latest",
  • "usage": {
    },
  • "data": [
    ]
}

Classifiers

Classifiers API.

Moderations

Authorizations:
ApiKey
Request Body schema: application/json
required
model
required
string (Model)

ID of the model to use.

required
Input (string) or Array of Input (strings) (Input)

Text to classify.

Responses

Request samples

Content type
application/json
{
  • "model": "string",
  • "input": "string"
}

Response samples

Content type
application/json
{
  • "id": "mod-e5cc70bb28c444948073e77776eb30ef",
  • "model": "string",
  • "results": [
    ]
}

Chat Moderations

Authorizations:
ApiKey
Request Body schema: application/json
required
required
Array of Input (any) or Array of Input (any) (Input)

Chat to classify

model
required
string (Model)

Responses

Request samples

Content type
application/json
{
  • "input": [
    ],
  • "model": "string"
}

Response samples

Content type
application/json
{
  • "id": "mod-e5cc70bb28c444948073e77776eb30ef",
  • "model": "string",
  • "results": [
    ]
}

Classifications

Authorizations:
ApiKey
Request Body schema: application/json
required
model
required
string (Model)

ID of the model to use.

required
Input (string) or Array of Input (strings) (Input)

Text to classify.

Responses

Request samples

Content type
application/json
{
  • "model": "string",
  • "input": "string"
}

Response samples

Content type
application/json
{
  • "id": "mod-e5cc70bb28c444948073e77776eb30ef",
  • "model": "string",
  • "results": [
    ]
}

Chat Classifications

Authorizations:
ApiKey
Request Body schema: application/json
required
model
required
string (Model)
required
InstructRequest (object) or Array of ChatClassificationRequestInputs (objects) (ChatClassificationRequestInputs)

Chat to classify

Responses

Request samples

Content type
application/json
{
  • "model": "string",
  • "input": {
    }
}

Response samples

Content type
application/json
{
  • "id": "mod-e5cc70bb28c444948073e77776eb30ef",
  • "model": "string",
  • "results": [
    ]
}

Files

Files API

Upload File

Upload a file that can be used across various endpoints.

The size of individual files can be a maximum of 512 MB. The Fine-tuning API only supports .jsonl files.

Please contact us if you need to increase these storage limits.

Authorizations:
ApiKey
Request Body schema: multipart/form-data
required
purpose
string (FilePurpose)
Enum: "fine-tune" "batch" "ocr"
file
required
string <binary> (File)

The File object (not file name) to be uploaded. To upload a file and specify a custom file name you should format your request as such:

file=@path/to/your/file.jsonl;filename=custom_name.jsonl

Otherwise, you can just keep the original file name:

file=@path/to/your/file.jsonl

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f09",
  • "object": "file",
  • "bytes": 13000,
  • "created_at": 1716963433,
  • "filename": "files_upload.jsonl",
  • "purpose": "fine-tune",
  • "sample_type": "pretrain",
  • "num_lines": 0,
  • "mimetype": "string",
  • "source": "upload",
  • "signature": "string"
}

List Files

Returns a list of files that belong to the user's organization.

Authorizations:
ApiKey
query Parameters
page
integer (Page)
Default: 0
page_size
integer (Page Size)
Default: 100
Array of Sample Type (strings) or Sample Type (null) (Sample Type)
Array of Source (strings) or Source (null) (Source)
Search (string) or Search (null) (Search)
FilePurpose (string) or null

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "string",
  • "total": 0
}

Retrieve File

Returns information about a specific file.

Authorizations:
ApiKey
path Parameters
file_id
required
string <uuid> (File Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f09",
  • "object": "file",
  • "bytes": 13000,
  • "created_at": 1716963433,
  • "filename": "files_upload.jsonl",
  • "purpose": "fine-tune",
  • "sample_type": "pretrain",
  • "num_lines": 0,
  • "mimetype": "string",
  • "source": "upload",
  • "signature": "string",
  • "deleted": true
}

Delete File

Delete a file.

Authorizations:
ApiKey
path Parameters
file_id
required
string <uuid> (File Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f09",
  • "object": "file",
  • "deleted": false
}

Download File

Download a file

Authorizations:
ApiKey
path Parameters
file_id
required
string <uuid> (File Id)

Responses

Get Signed Url

Authorizations:
ApiKey
path Parameters
file_id
required
string <uuid> (File Id)
query Parameters
expiry
integer (Expiry)
Default: 24

Number of hours before the url becomes invalid. Defaults to 24h

Responses

Response samples

Content type
application/json
{
  • "url": "string"
}

Fine Tuning

Fine-tuning API

Get Fine Tuning Jobs

Get a list of fine-tuning jobs for your organization and user.

Authorizations:
ApiKey
query Parameters
page
integer (Page)
Default: 0

The page number of the results to be returned.

page_size
integer (Page Size)
Default: 100

The number of items to return per page.

Model (string) or Model (null) (Model)

The model name used for fine-tuning to filter on. When set, the other results are not displayed.

Created After (string) or Created After (null) (Created After)

The date/time to filter on. When set, the results for previous creation times are not displayed.

Created Before (string) or Created Before (null) (Created Before)
created_by_me
boolean (Created By Me)
Default: false

When set, only return results for jobs created by the API caller. Other results are not displayed.

Status (string) or Status (null) (Status)

The current job state to filter on. When set, the other results are not displayed.

Wandb Project (string) or Wandb Project (null) (Wandb Project)

The Weights and Biases project to filter on. When set, the other results are not displayed.

Wandb Name (string) or Wandb Name (null) (Wandb Name)

The Weight and Biases run name to filter on. When set, the other results are not displayed.

Suffix (string) or Suffix (null) (Suffix)

The model suffix to filter on. When set, the other results are not displayed.

Responses

Response samples

Content type
application/json
{
  • "data": [ ],
  • "object": "list",
  • "total": 0
}

Create Fine Tuning Job

Create a new fine-tuning job, it will be queued for processing.

Authorizations:
ApiKey
query Parameters
Dry Run (boolean) or Dry Run (null) (Dry Run)
  • If true the job is not spawned, instead the query returns a handful of useful metadata for the user to perform sanity checks (see LegacyJobMetadataOut response).
  • Otherwise, the job is started and the query returns the job ID along with some of the input parameters (see JobOut response).
Request Body schema: application/json
required
model
required
string (FineTuneableModel)
Enum: "ministral-3b-latest" "ministral-8b-latest" "open-mistral-7b" "open-mistral-nemo" "mistral-small-latest" "mistral-medium-latest" "mistral-large-latest" "pixtral-12b-latest" "codestral-latest"

The name of the model to fine-tune.

Array of objects (Training Files)
Default: []
Array of Validation Files (strings) or Validation Files (null) (Validation Files)

A list containing the IDs of uploaded files that contain validation data. If you provide these files, the data is used to generate validation metrics periodically during fine-tuning. These metrics can be viewed in checkpoints when getting the status of a running fine-tuning job. The same data should not be present in both train and validation files.

Suffix (string) or Suffix (null) (Suffix)

A string that will be added to your fine-tuning model name. For example, a suffix of "my-great-model" would produce a model name like ft:open-mistral-7b:my-great-model:xxx...

Array of Integrations (any) or Integrations (null) (Integrations)

A list of integrations to enable for your fine-tuning job.

auto_start
boolean (Auto Start)

This field will be required in a future release.

invalid_sample_skip_percentage
number (Invalid Sample Skip Percentage) [ 0 .. 0.5 ]
Default: 0
FineTuneableModelType (string) or null
required
CompletionTrainingParametersIn (object) or ClassifierTrainingParametersIn (object) (Hyperparameters)
Array of Repositories (any) or Repositories (null) (Repositories)
Array of Classifier Targets (objects) or Classifier Targets (null) (Classifier Targets)

Responses

Request samples

Content type
application/json
{
  • "model": "ministral-3b-latest",
  • "training_files": [ ],
  • "validation_files": [
    ],
  • "suffix": "string",
  • "integrations": [
    ],
  • "auto_start": true,
  • "invalid_sample_skip_percentage": 0,
  • "job_type": "completion",
  • "hyperparameters": {
    },
  • "repositories": [
    ],
  • "classifier_targets": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "auto_start": true,
  • "model": "ministral-3b-latest",
  • "status": "QUEUED",
  • "created_at": 0,
  • "modified_at": 0,
  • "training_files": [
    ],
  • "validation_files": [ ],
  • "object": "job",
  • "fine_tuned_model": "string",
  • "suffix": "string",
  • "integrations": [
    ],
  • "trained_tokens": 0,
  • "metadata": {
    },
  • "job_type": "completion",
  • "hyperparameters": {
    },
  • "repositories": [ ]
}

Get Fine Tuning Job

Get a fine-tuned job details by its UUID.

Authorizations:
ApiKey
path Parameters
job_id
required
string <uuid> (Job Id)

The ID of the job to analyse.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "auto_start": true,
  • "model": "ministral-3b-latest",
  • "status": "QUEUED",
  • "created_at": 0,
  • "modified_at": 0,
  • "training_files": [
    ],
  • "validation_files": [ ],
  • "object": "job",
  • "fine_tuned_model": "string",
  • "suffix": "string",
  • "integrations": [
    ],
  • "trained_tokens": 0,
  • "metadata": {
    },
  • "job_type": "classifier",
  • "hyperparameters": {
    },
  • "events": [ ],
  • "checkpoints": [ ],
  • "classifier_targets": [
    ]
}

Cancel Fine Tuning Job

Request the cancellation of a fine tuning job.

Authorizations:
ApiKey
path Parameters
job_id
required
string <uuid> (Job Id)

The ID of the job to cancel.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "auto_start": true,
  • "model": "ministral-3b-latest",
  • "status": "QUEUED",
  • "created_at": 0,
  • "modified_at": 0,
  • "training_files": [
    ],
  • "validation_files": [ ],
  • "object": "job",
  • "fine_tuned_model": "string",
  • "suffix": "string",
  • "integrations": [
    ],
  • "trained_tokens": 0,
  • "metadata": {
    },
  • "job_type": "classifier",
  • "hyperparameters": {
    },
  • "events": [ ],
  • "checkpoints": [ ],
  • "classifier_targets": [
    ]
}

Start Fine Tuning Job

Request the start of a validated fine tuning job.

Authorizations:
ApiKey
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "auto_start": true,
  • "model": "ministral-3b-latest",
  • "status": "QUEUED",
  • "created_at": 0,
  • "modified_at": 0,
  • "training_files": [
    ],
  • "validation_files": [ ],
  • "object": "job",
  • "fine_tuned_model": "string",
  • "suffix": "string",
  • "integrations": [
    ],
  • "trained_tokens": 0,
  • "metadata": {
    },
  • "job_type": "classifier",
  • "hyperparameters": {
    },
  • "events": [ ],
  • "checkpoints": [ ],
  • "classifier_targets": [
    ]
}

Models

Model Management API

List Models

List all models available to the user.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "data": [
    ]
}

Retrieve Model

Retrieve information about a model.

Authorizations:
ApiKey
path Parameters
model_id
required
string (Model Id)
Example: ft:open-mistral-7b:587a6b29:20240514:7e773925

The ID of the model to retrieve.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "object": "model",
  • "created": 0,
  • "owned_by": "mistralai",
  • "capabilities": {
    },
  • "name": "string",
  • "description": "string",
  • "max_context_length": 32768,
  • "aliases": [ ],
  • "deprecation": "2019-08-24T14:15:22Z",
  • "deprecation_replacement_model": "string",
  • "default_model_temperature": 0,
  • "type": "base"
}

Delete Model

Delete a fine-tuned model.

Authorizations:
ApiKey
path Parameters
model_id
required
string (Model Id)
Example: ft:open-mistral-7b:587a6b29:20240514:7e773925

The ID of the model to delete.

Responses

Response samples

Content type
application/json
{
  • "id": "ft:open-mistral-7b:587a6b29:20240514:7e773925",
  • "object": "model",
  • "deleted": true
}

Update Fine Tuned Model

Update a model name or description.

Authorizations:
ApiKey
path Parameters
model_id
required
string (Model Id)
Example: ft:open-mistral-7b:587a6b29:20240514:7e773925

The ID of the model to update.

Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "object": "model",
  • "created": 0,
  • "owned_by": "string",
  • "workspace_id": "string",
  • "root": "string",
  • "root_version": "string",
  • "archived": true,
  • "name": "string",
  • "description": "string",
  • "capabilities": {
    },
  • "max_context_length": 32768,
  • "aliases": [ ],
  • "job": "4bbaedb0-902b-4b27-8218-8f40d3470a54",
  • "classifier_targets": [
    ],
  • "model_type": "classifier"
}

Archive Fine Tuned Model

Archive a fine-tuned model.

Authorizations:
ApiKey
path Parameters
model_id
required
string (Model Id)
Example: ft:open-mistral-7b:587a6b29:20240514:7e773925

The ID of the model to archive.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "model",
  • "archived": true
}

Unarchive Fine Tuned Model

Un-archive a fine-tuned model.

Authorizations:
ApiKey
path Parameters
model_id
required
string (Model Id)
Example: ft:open-mistral-7b:587a6b29:20240514:7e773925

The ID of the model to unarchive.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "model",
  • "archived": false
}

Batch

Batch API

Get Batch Jobs

Get a list of batch jobs for your organization and user.

Authorizations:
ApiKey
query Parameters
page
integer (Page)
Default: 0
page_size
integer (Page Size)
Default: 100
Model (string) or Model (null) (Model)
Agent Id (string) or Agent Id (null) (Agent Id)
Metadata (object) or Metadata (null) (Metadata)
Created After (string) or Created After (null) (Created After)
created_by_me
boolean (Created By Me)
Default: false
Array of Status (strings) or Status (null) (Status)

Responses

Response samples

Content type
application/json
{
  • "data": [ ],
  • "object": "list",
  • "total": 0
}

Create Batch Job

Create a new batch job, it will be queued for processing.

Authorizations:
ApiKey
Request Body schema: application/json
required
input_files
required
Array of strings <uuid> (Input Files) [ items <uuid > ]
endpoint
required
string (ApiEndpoint)
Enum: "/v1/chat/completions" "/v1/embeddings" "/v1/fim/completions" "/v1/moderations" "/v1/chat/moderations"
Model (string) or Model (null) (Model)
Agent Id (string) or Agent Id (null) (Agent Id)
Metadata (object) or Metadata (null) (Metadata)
timeout_hours
integer (Timeout Hours)
Default: 24

Responses

Request samples

Content type
application/json
{
  • "input_files": [
    ],
  • "endpoint": "/v1/chat/completions",
  • "model": "string",
  • "agent_id": "string",
  • "metadata": {
    },
  • "timeout_hours": 24
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "batch",
  • "input_files": [
    ],
  • "metadata": { },
  • "endpoint": "string",
  • "model": "string",
  • "agent_id": "string",
  • "output_file": "c7c9cb17-f818-4ee3-85de-0d2f8954882c",
  • "error_file": "6b79e6a4-c3aa-4da1-8fb4-9e2520d26bfa",
  • "errors": [
    ],
  • "status": "QUEUED",
  • "created_at": 0,
  • "total_requests": 0,
  • "completed_requests": 0,
  • "succeeded_requests": 0,
  • "failed_requests": 0,
  • "started_at": 0,
  • "completed_at": 0
}

Get Batch Job

Get a batch job details by its UUID.

Authorizations:
ApiKey
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "batch",
  • "input_files": [
    ],
  • "metadata": { },
  • "endpoint": "string",
  • "model": "string",
  • "agent_id": "string",
  • "output_file": "c7c9cb17-f818-4ee3-85de-0d2f8954882c",
  • "error_file": "6b79e6a4-c3aa-4da1-8fb4-9e2520d26bfa",
  • "errors": [
    ],
  • "status": "QUEUED",
  • "created_at": 0,
  • "total_requests": 0,
  • "completed_requests": 0,
  • "succeeded_requests": 0,
  • "failed_requests": 0,
  • "started_at": 0,
  • "completed_at": 0
}

Cancel Batch Job

Request the cancellation of a batch job.

Authorizations:
ApiKey
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "batch",
  • "input_files": [
    ],
  • "metadata": { },
  • "endpoint": "string",
  • "model": "string",
  • "agent_id": "string",
  • "output_file": "c7c9cb17-f818-4ee3-85de-0d2f8954882c",
  • "error_file": "6b79e6a4-c3aa-4da1-8fb4-9e2520d26bfa",
  • "errors": [
    ],
  • "status": "QUEUED",
  • "created_at": 0,
  • "total_requests": 0,
  • "completed_requests": 0,
  • "succeeded_requests": 0,
  • "failed_requests": 0,
  • "started_at": 0,
  • "completed_at": 0
}

OCR API

OCR API

OCR

Authorizations:
ApiKey
Request Body schema: application/json
required
required
Model (string) or Model (null) (Model)
id
string (Id)
required
FileChunk (object) or DocumentURLChunk (object) or ImageURLChunk (object) (Document)

Document to run OCR on

Array of Pages (integers) or Pages (null) (Pages)

Specific pages user wants to process in various formats: single number, range, or list of both. Starts from 0

Include Image Base64 (boolean) or Include Image Base64 (null) (Include Image Base64)

Include image URLs in response

Image Limit (integer) or Image Limit (null) (Image Limit)

Max images to extract

Image Min Size (integer) or Image Min Size (null) (Image Min Size)

Minimum height and width of image to extract

ResponseFormat (object) or null

Structured output class for extracting useful information from each extracted bounding box / image from document. Only json_schema is valid for this field

ResponseFormat (object) or null

Structured output class for extracting useful information from the entire document. Only json_schema is valid for this field

Responses

Request samples

Content type
application/json
{
  • "model": "string",
  • "id": "string",
  • "document": {
    },
  • "pages": [
    ],
  • "include_image_base64": true,
  • "image_limit": 0,
  • "image_min_size": 0,
  • "bbox_annotation_format": {
    },
  • "document_annotation_format": {
    }
}

Response samples

Content type
application/json
{
  • "pages": [
    ],
  • "model": "string",
  • "document_annotation": "string",
  • "usage_info": {
    }
}

Transcriptions API

API for audio transcription.

Create Transcription

Authorizations:
ApiKey
Request Body schema: multipart/form-data
required
model
required
string (Model)
File (string) or File (null) (File)
Default: null
File Url (string) or File Url (null) (File Url)
Default: null

Url of a file to be transcribed

File Id (string) or File Id (null) (File Id)
Default: null

ID of a file uploaded to /v1/files

Language (string) or Language (null) (Language)
Default: null

Language of the audio, e.g. 'en'. Providing the language can boost accuracy.

Temperature (number) or Temperature (null) (Temperature)
Default: null
stream
boolean (Stream)
Default: false
timestamp_granularities
Array of strings (Timestamp Granularities)
Items Value: "segment"

Granularities of timestamps to include in the response.

Responses

Response samples

Content type
application/json
{
  • "model": "string",
  • "text": "string",
  • "language": "string",
  • "segments": [
    ],
  • "usage": {
    }
}

Create streaming transcription (SSE)

Authorizations:
ApiKey
Request Body schema: multipart/form-data
required
model
required
string (Model)
File (string) or File (null) (File)
Default: null
File Url (string) or File Url (null) (File Url)
Default: null

Url of a file to be transcribed

File Id (string) or File Id (null) (File Id)
Default: null

ID of a file uploaded to /v1/files

Language (string) or Language (null) (Language)
Default: null

Language of the audio, e.g. 'en'. Providing the language can boost accuracy.

Temperature (number) or Temperature (null) (Temperature)
Default: null
stream
boolean (Stream)
Default: true
Value: true
timestamp_granularities
Array of strings (Timestamp Granularities)
Items Value: "segment"

Granularities of timestamps to include in the response.

Responses

(beta) Agents API

(beta) Agents API

Create a agent that can be used within a conversation.

Create a new agent giving it instructions, tools, description. The agent is then available to be used as a regular assistant in a conversation or as part of an agent pool from which it can be used.

Authorizations:
ApiKey
Request Body schema: application/json
required
Instructions (string) or Instructions (null) (Instructions)

Instruction prompt the model will follow during the conversation.

Array of any (Tools)

List of tools which are available to the model during the conversation.

object (CompletionArgs)

Completion arguments that will be used to generate assistant responses. Can be overridden at each message request.

model
required
string (Model)
name
required
string (Name)
Description (string) or Description (null) (Description)
Array of Handoffs (strings) or Handoffs (null) (Handoffs)

Responses

Request samples

Content type
application/json
{
  • "instructions": "string",
  • "tools": [
    ],
  • "completion_args": {
    },
  • "model": "string",
  • "name": "string",
  • "description": "string",
  • "handoffs": [
    ]
}

Response samples

Content type
application/json
{
  • "instructions": "string",
  • "tools": [
    ],
  • "completion_args": {
    },
  • "model": "string",
  • "name": "string",
  • "description": "string",
  • "handoffs": [
    ],
  • "object": "agent",
  • "id": "string",
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List agent entities.

Retrieve a list of agent entities sorted by creation time.

Authorizations:
ApiKey
query Parameters
page
integer (Page)
Default: 0
page_size
integer (Page Size)
Default: 20

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve an agent entity.

Given an agent retrieve an agent entity with its attributes.

Authorizations:
ApiKey
path Parameters
agent_id
required
string (Agent Id)

Responses

Response samples

Content type
application/json
{
  • "instructions": "string",
  • "tools": [
    ],
  • "completion_args": {
    },
  • "model": "string",
  • "name": "string",
  • "description": "string",
  • "handoffs": [
    ],
  • "object": "agent",
  • "id": "string",
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update an agent entity.

Update an agent attributes and create a new version.

Authorizations:
ApiKey
path Parameters
agent_id
required
string (Agent Id)
Request Body schema: application/json
required
Instructions (string) or Instructions (null) (Instructions)

Instruction prompt the model will follow during the conversation.

Array of any (Tools)

List of tools which are available to the model during the conversation.

object (CompletionArgs)

Completion arguments that will be used to generate assistant responses. Can be overridden at each message request.

Model (string) or Model (null) (Model)
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Handoffs (strings) or Handoffs (null) (Handoffs)

Responses

Request samples

Content type
application/json
{
  • "instructions": "string",
  • "tools": [
    ],
  • "completion_args": {
    },
  • "model": "string",
  • "name": "string",
  • "description": "string",
  • "handoffs": [
    ]
}

Response samples

Content type
application/json
{
  • "instructions": "string",
  • "tools": [
    ],
  • "completion_args": {
    },
  • "model": "string",
  • "name": "string",
  • "description": "string",
  • "handoffs": [
    ],
  • "object": "agent",
  • "id": "string",
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update an agent version.

Switch the version of an agent.

Authorizations:
ApiKey
path Parameters
agent_id
required
string (Agent Id)
query Parameters
version
required
integer (Version)

Responses

Response samples

Content type
application/json
{
  • "instructions": "string",
  • "tools": [
    ],
  • "completion_args": {
    },
  • "model": "string",
  • "name": "string",
  • "description": "string",
  • "handoffs": [
    ],
  • "object": "agent",
  • "id": "string",
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

(beta) Conversations API

(beta) Conversations API

Create a conversation and append entries to it.

Create a new conversation, using a base model or an agent and append entries. Completion and tool executions are run and the response is appended to the conversation.Use the returned conversation_id to continue the conversation.

Authorizations:
ApiKey
Request Body schema: application/json
required
required
ConversationInputs (string) or (Array of InputEntries (MessageInputEntry (object) or MessageOutputEntry (object) or FunctionResultEntry (object) or FunctionCallEntry (object) or ToolExecutionEntry (object) or AgentHandoffEntry (object))) (ConversationInputs)
Stream (boolean) or Stream (boolean) (Stream)
Default: false
Value: false
Store (boolean) or Store (null) (Store)
Default: null
Handoff Execution (string) or Handoff Execution (null) (Handoff Execution)
Default: null
Instructions (string) or Instructions (null) (Instructions)
Default: null
Array of Tools (any) or Tools (null) (Tools)
Default: null
CompletionArgs (object) or null
Default: null
Name (string) or Name (null) (Name)
Default: null
Description (string) or Description (null) (Description)
Default: null
Agent Id (string) or Agent Id (null) (Agent Id)
Default: null
Model (string) or Model (null) (Model)
Default: null

Responses

Request samples

Content type
application/json
{
  • "inputs": "string",
  • "stream": false,
  • "store": null,
  • "handoff_execution": null,
  • "instructions": null,
  • "tools": null,
  • "completion_args": null,
  • "name": null,
  • "description": null,
  • "agent_id": null,
  • "model": null
}

Response samples

Content type
application/json
{
  • "object": "conversation.response",
  • "conversation_id": "string",
  • "outputs": [
    ],
  • "usage": {
    }
}

List all created conversations.

Retrieve a list of conversation entities sorted by creation time.

Authorizations:
ApiKey
query Parameters
page
integer (Page)
Default: 0
page_size
integer (Page Size)
Default: 100

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a conversation information.

Given a conversation_id retrieve a conversation entity with its attributes.

Authorizations:
ApiKey
path Parameters
conversation_id
required
string (Conversation Id)

ID of the conversation from which we are fetching metadata.

Responses

Response samples

Content type
application/json
Example
{
  • "instructions": "string",
  • "tools": [
    ],
  • "completion_args": {
    },
  • "name": "string",
  • "description": "string",
  • "object": "conversation",
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "model": "string"
}

Append new entries to an existing conversation.

Run completion on the history of the conversation and the user entries. Return the new created entries.

Authorizations:
ApiKey
path Parameters
conversation_id
required
string (Conversation Id)

ID of the conversation to which we append entries.

Request Body schema: application/json
required
required
ConversationInputs (string) or (Array of InputEntries (MessageInputEntry (object) or MessageOutputEntry (object) or FunctionResultEntry (object) or FunctionCallEntry (object) or ToolExecutionEntry (object) or AgentHandoffEntry (object))) (ConversationInputs)
stream
boolean (Stream)
Default: false
Value: false

Whether to stream back partial progress. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.

store
boolean (Store)
Default: true

Whether to store the results into our servers or not.

handoff_execution
string (Handoff Execution)
Default: "server"
Enum: "client" "server"
object (CompletionArgs)

Completion arguments that will be used to generate assistant responses. Can be overridden at each message request.

Responses

Request samples

Content type
application/json
{
  • "inputs": "string",
  • "stream": false,
  • "store": true,
  • "handoff_execution": "client",
  • "completion_args": {
    }
}

Response samples

Content type
application/json
{
  • "object": "conversation.response",
  • "conversation_id": "string",
  • "outputs": [
    ],
  • "usage": {
    }
}

Retrieve all entries in a conversation.

Given a conversation_id retrieve all the entries belonging to that conversation. The entries are sorted in the order they were appended, those can be messages, connectors or function_call.

Authorizations:
ApiKey
path Parameters
conversation_id
required
string (Conversation Id)

ID of the conversation from which we are fetching entries.

Responses

Response samples

Content type
application/json
{
  • "object": "conversation.history",
  • "conversation_id": "string",
  • "entries": [
    ]
}

Retrieve all messages in a conversation.

Given a conversation_id retrieve all the messages belonging to that conversation. This is similar to retrieving all entries except we filter the messages only.

Authorizations:
ApiKey
path Parameters
conversation_id
required
string (Conversation Id)

ID of the conversation from which we are fetching messages.

Responses

Response samples

Content type
application/json
{
  • "object": "conversation.messages",
  • "conversation_id": "string",
  • "messages": [
    ]
}

Restart a conversation starting from a given entry.

Given a conversation_id and an id, recreate a conversation from this point and run completion. A new conversation is returned with the new entries returned.

Authorizations:
ApiKey
path Parameters
conversation_id
required
string (Conversation Id)

ID of the original conversation which is being restarted.

Request Body schema: application/json
required
required
ConversationInputs (string) or (Array of InputEntries (MessageInputEntry (object) or MessageOutputEntry (object) or FunctionResultEntry (object) or FunctionCallEntry (object) or ToolExecutionEntry (object) or AgentHandoffEntry (object))) (ConversationInputs)
stream
boolean (Stream)
Default: false
Value: false

Whether to stream back partial progress. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.

store
boolean (Store)
Default: true

Whether to store the results into our servers or not.

handoff_execution
string (Handoff Execution)
Default: "server"
Enum: "client" "server"
object (CompletionArgs)

Completion arguments that will be used to generate assistant responses. Can be overridden at each message request.

from_entry_id
required
string (From Entry Id)

Responses

Request samples

Content type
application/json
{
  • "inputs": "string",
  • "stream": false,
  • "store": true,
  • "handoff_execution": "client",
  • "completion_args": {
    },
  • "from_entry_id": "string"
}

Response samples

Content type
application/json
{
  • "object": "conversation.response",
  • "conversation_id": "string",
  • "outputs": [
    ],
  • "usage": {
    }
}

Create a conversation and append entries to it.

Create a new conversation, using a base model or an agent and append entries. Completion and tool executions are run and the response is appended to the conversation.Use the returned conversation_id to continue the conversation.

Authorizations:
ApiKey
Request Body schema: application/json
required
required
ConversationInputs (string) or (Array of InputEntries (MessageInputEntry (object) or MessageOutputEntry (object) or FunctionResultEntry (object) or FunctionCallEntry (object) or ToolExecutionEntry (object) or AgentHandoffEntry (object))) (ConversationInputs)
Stream (boolean) or Stream (boolean) (Stream)
Default: true
Value: true
Store (boolean) or Store (null) (Store)
Default: null
Handoff Execution (string) or Handoff Execution (null) (Handoff Execution)
Default: null
Instructions (string) or Instructions (null) (Instructions)
Default: null
Array of Tools (any) or Tools (null) (Tools)
Default: null
CompletionArgs (object) or null
Default: null
Name (string) or Name (null) (Name)
Default: null
Description (string) or Description (null) (Description)
Default: null
Agent Id (string) or Agent Id (null) (Agent Id)
Default: null
Model (string) or Model (null) (Model)
Default: null

Responses

Request samples

Content type
application/json
{
  • "inputs": "string",
  • "stream": true,
  • "store": null,
  • "handoff_execution": null,
  • "instructions": null,
  • "tools": null,
  • "completion_args": null,
  • "name": null,
  • "description": null,
  • "agent_id": null,
  • "model": null
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Append new entries to an existing conversation.

Run completion on the history of the conversation and the user entries. Return the new created entries.

Authorizations:
ApiKey
path Parameters
conversation_id
required
string (Conversation Id)

ID of the conversation to which we append entries.

Request Body schema: application/json
required
required
ConversationInputs (string) or (Array of InputEntries (MessageInputEntry (object) or MessageOutputEntry (object) or FunctionResultEntry (object) or FunctionCallEntry (object) or ToolExecutionEntry (object) or AgentHandoffEntry (object))) (ConversationInputs)
stream
boolean (Stream)
Default: true
Value: true

Whether to stream back partial progress. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.

store
boolean (Store)
Default: true

Whether to store the results into our servers or not.

handoff_execution
string (Handoff Execution)
Default: "server"
Enum: "client" "server"
object (CompletionArgs)

Completion arguments that will be used to generate assistant responses. Can be overridden at each message request.

Responses

Request samples

Content type
application/json
{
  • "inputs": "string",
  • "stream": true,
  • "store": true,
  • "handoff_execution": "client",
  • "completion_args": {
    }
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Restart a conversation starting from a given entry.

Given a conversation_id and an id, recreate a conversation from this point and run completion. A new conversation is returned with the new entries returned.

Authorizations:
ApiKey
path Parameters
conversation_id
required
string (Conversation Id)

ID of the original conversation which is being restarted.

Request Body schema: application/json
required
required
ConversationInputs (string) or (Array of InputEntries (MessageInputEntry (object) or MessageOutputEntry (object) or FunctionResultEntry (object) or FunctionCallEntry (object) or ToolExecutionEntry (object) or AgentHandoffEntry (object))) (ConversationInputs)
stream
boolean (Stream)
Default: true
Value: true

Whether to stream back partial progress. Otherwise, the server will hold the request open until the timeout or until completion, with the response containing the full result as JSON.

store
boolean (Store)
Default: true

Whether to store the results into our servers or not.

handoff_execution
string (Handoff Execution)
Default: "server"
Enum: "client" "server"
object (CompletionArgs)

Completion arguments that will be used to generate assistant responses. Can be overridden at each message request.

from_entry_id
required
string (From Entry Id)

Responses

Request samples

Content type
application/json
{
  • "inputs": "string",
  • "stream": true,
  • "store": true,
  • "handoff_execution": "client",
  • "completion_args": {
    },
  • "from_entry_id": "string"
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

(beta) Libraries API - Main

(beta) Libraries API to create and manage libraries - index your documents to enhance agent capabilities.

List all libraries you have access to.

List all libraries that you have created or have been shared with you.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a new Library.

Create a new Library, you will be marked as the owner and only you will have the possibility to share it with others. When first created this will only be accessible by you.

Authorizations:
ApiKey
Request Body schema: application/json
required
name
required
string (Name)
Description (string) or Description (null) (Description)
Chunk Size (integer) or Chunk Size (null) (Chunk Size)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "chunk_size": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "owner_type": "string",
  • "total_size": 0,
  • "nb_documents": 0,
  • "chunk_size": 0,
  • "emoji": "string",
  • "description": "string",
  • "generated_name": "string",
  • "generated_description": "string",
  • "explicit_user_members_count": 0,
  • "explicit_workspace_members_count": 0,
  • "org_sharing_role": "string"
}

Detailed information about a specific Library.

Given a library id, details information about that Library.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "owner_type": "string",
  • "total_size": 0,
  • "nb_documents": 0,
  • "chunk_size": 0,
  • "emoji": "string",
  • "description": "string",
  • "generated_name": "string",
  • "generated_description": "string",
  • "explicit_user_members_count": 0,
  • "explicit_workspace_members_count": 0,
  • "org_sharing_role": "string"
}

Delete a library and all of it's document.

Given a library id, deletes it together with all documents that have been uploaded to that library.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "owner_type": "string",
  • "total_size": 0,
  • "nb_documents": 0,
  • "chunk_size": 0,
  • "emoji": "string",
  • "description": "string",
  • "generated_name": "string",
  • "generated_description": "string",
  • "explicit_user_members_count": 0,
  • "explicit_workspace_members_count": 0,
  • "org_sharing_role": "string"
}

Update a library.

Given a library id, you can update the name and description.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "owner_type": "string",
  • "total_size": 0,
  • "nb_documents": 0,
  • "chunk_size": 0,
  • "emoji": "string",
  • "description": "string",
  • "generated_name": "string",
  • "generated_description": "string",
  • "explicit_user_members_count": 0,
  • "explicit_workspace_members_count": 0,
  • "org_sharing_role": "string"
}

(beta) Libraries API - Documents

(beta) Libraries API - manage documents in a library.

List document in a given library.

Given a library, lists the document that have been uploaded to that library.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
query Parameters
Search (string) or Search (null) (Search)
page_size
integer (Page Size)
Default: 100
page
integer (Page)
Default: 0
sort_by
string (Sort By)
Default: "created_at"
sort_order
string (Sort Order)
Default: "desc"

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "data": [
    ]
}

Upload a new document.

Given a library, upload a new document to that library. It is queued for processing, it status will change it has been processed. The processing has to be completed in order be discoverable for the library search

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
Request Body schema: multipart/form-data
required
file
required
string <binary> (File)

The File object (not file name) to be uploaded. To upload a file and specify a custom file name you should format your request as such:

file=@path/to/your/file.jsonl;filename=custom_name.jsonl

Otherwise, you can just keep the original file name:

file=@path/to/your/file.jsonl

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "library_id": "21f784c9-c915-48d4-a805-f15b3e01b084",
  • "hash": "string",
  • "mime_type": "string",
  • "extension": "string",
  • "size": 0,
  • "name": "string",
  • "summary": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_processed_at": "2019-08-24T14:15:22Z",
  • "number_of_pages": 0,
  • "processing_status": "string",
  • "uploaded_by_id": "890d2c95-7e66-4f6f-803c-a2ce12e35ae3",
  • "uploaded_by_type": "string",
  • "tokens_processing_main_content": 0,
  • "tokens_processing_summary": 0,
  • "tokens_processing_total": 0
}

Retrieve the metadata of a specific document.

Given a library and a document in this library, you can retrieve the metadata of that document.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
document_id
required
string <uuid> (Document Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "library_id": "21f784c9-c915-48d4-a805-f15b3e01b084",
  • "hash": "string",
  • "mime_type": "string",
  • "extension": "string",
  • "size": 0,
  • "name": "string",
  • "summary": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_processed_at": "2019-08-24T14:15:22Z",
  • "number_of_pages": 0,
  • "processing_status": "string",
  • "uploaded_by_id": "890d2c95-7e66-4f6f-803c-a2ce12e35ae3",
  • "uploaded_by_type": "string",
  • "tokens_processing_main_content": 0,
  • "tokens_processing_summary": 0,
  • "tokens_processing_total": 0
}

Update the metadata of a specific document.

Given a library and a document in that library, update the name of that document.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
document_id
required
string <uuid> (Document Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Any of
string (Name)

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "library_id": "21f784c9-c915-48d4-a805-f15b3e01b084",
  • "hash": "string",
  • "mime_type": "string",
  • "extension": "string",
  • "size": 0,
  • "name": "string",
  • "summary": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_processed_at": "2019-08-24T14:15:22Z",
  • "number_of_pages": 0,
  • "processing_status": "string",
  • "uploaded_by_id": "890d2c95-7e66-4f6f-803c-a2ce12e35ae3",
  • "uploaded_by_type": "string",
  • "tokens_processing_main_content": 0,
  • "tokens_processing_summary": 0,
  • "tokens_processing_total": 0
}

Delete a document.

Given a library and a document in that library, delete that document. The document will be deleted from the library and the search index.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
document_id
required
string <uuid> (Document Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Retrieve the text content of a specific document.

Given a library and a document in that library, you can retrieve the text content of that document if it exists. For documents like pdf, docx and pptx the text content results from our processing using Mistral OCR.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
document_id
required
string <uuid> (Document Id)

Responses

Response samples

Content type
application/json
{
  • "text": "string"
}

Retrieve the processing status of a specific document.

Given a library and a document in that library, retrieve the processing status of that document.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
document_id
required
string <uuid> (Document Id)

Responses

Response samples

Content type
application/json
{
  • "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
  • "processing_status": "string"
}

Retrieve the signed URL of a specific document.

Given a library and a document in that library, retrieve the signed URL of a specific document.The url will expire after 30 minutes and can be accessed by anyone with the link.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
document_id
required
string <uuid> (Document Id)

Responses

Response samples

Content type
application/json
"string"

Retrieve the signed URL of text extracted from a given document.

Given a library and a document in that library, retrieve the signed URL of text extracted. For documents that are sent to the OCR this returns the result of the OCR queries.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
document_id
required
string <uuid> (Document Id)

Responses

Response samples

Content type
application/json
"string"

Reprocess a document.

Given a library and a document in that library, reprocess that document, it will be billed again.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
document_id
required
string <uuid> (Document Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

(beta) Libraries API - Access

(beta) Libraries API - manage access to a library.

List all of the access to this library.

Given a library, list all of the Entity that have access and to what level.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create or update an access level.

Given a library id, you can create or update the access level of an entity. You have to be owner of the library to share a library. An owner cannot change their own role. A library cannot be shared outside of the organization.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
Request Body schema: application/json
required
org_id
required
string <uuid> (Org Id)
level
required
string (ShareEnum)
Enum: "Viewer" "Editor"
share_with_uuid
required
string <uuid>

The id of the entity (user, workspace or organization) to share with

share_with_type
required
string (EntityType)
Enum: "User" "Workspace" "Org"

The type of entity, used to share a library.

Responses

Request samples

Content type
application/json
{
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "level": "Viewer",
  • "share_with_uuid": "eefaa7a1-01a4-4caf-bd17-b410bd83c9fd",
  • "share_with_type": "User"
}

Response samples

Content type
application/json
{
  • "library_id": "21f784c9-c915-48d4-a805-f15b3e01b084",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "role": "string",
  • "share_with_type": "string",
  • "share_with_uuid": "eefaa7a1-01a4-4caf-bd17-b410bd83c9fd"
}

Delete an access level.

Given a library id, you can delete the access level of an entity. An owner cannot delete it's own access. You have to be the owner of the library to delete an acces other than yours.

Authorizations:
ApiKey
path Parameters
library_id
required
string <uuid> (Library Id)
Request Body schema: application/json
required
org_id
required
string <uuid> (Org Id)
share_with_uuid
required
string <uuid>

The id of the entity (user, workspace or organization) to share with

share_with_type
required
string (EntityType)
Enum: "User" "Workspace" "Org"

The type of entity, used to share a library.

Responses

Request samples

Content type
application/json
{
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "share_with_uuid": "eefaa7a1-01a4-4caf-bd17-b410bd83c9fd",
  • "share_with_type": "User"
}

Response samples

Content type
application/json
{
  • "library_id": "21f784c9-c915-48d4-a805-f15b3e01b084",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "role": "string",
  • "share_with_type": "string",
  • "share_with_uuid": "eefaa7a1-01a4-4caf-bd17-b410bd83c9fd"
}