API HTTP

Una referencia completa para la API RESTful de olabox. Antes de continuar, asegúrate de tener tu clave de API de olabox lista para la autenticación.

Códigos de Error

Código	Mensaje	Descripción
400	Bad Request	Parámetros de solicitud inválidos
401	Unauthorized	Acceso no autorizado
403	Forbidden	Acceso denegado
404	Not Found	Recurso no encontrado
500	Internal Server Error	Error interno del servidor
1001	Invalid Chunk ID	ID de Chunk inválido
1002	Chunk Update Failed	Falló la actualización del Chunk

API Compatible con OpenAI

Crear finalización de chat

Crea una respuesta del modelo para una conversación de chat dada. Esta API sigue el mismo formato de solicitud y respuesta que la API de OpenAI.

POST

/api/v1/chats_openai/{chat_id}/chat/completions

Parámetros

Nombre	Tipo	Descripción
model*	string	El modelo utilizado para generar la respuesta. El servidor lo analizará automáticamente, por lo que puedes establecer cualquier valor por ahora.
messages*	list[object]	Una lista de mensajes de chat históricos utilizados para generar la respuesta. Debe contener al menos un mensaje con el rol de usuario.
stream	boolean	Si se debe recibir la respuesta como un stream. Establécelo en `false` explícitamente si prefieres recibir la respuesta completa de una vez.

Ejemplo de Solicitud

curl --request POST \
     --url http://{address}/api/v1/chats_openai/{chat_id}/chat/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "model": "model",
        "messages": [{"role": "user", "content": "Say this is a test!"}],
        "stream": true
      }'

Ejemplos de Respuesta

Respuesta (Stream)

{
  "id": "chatcmpl-3a9c3572f29311efa69751e139332ced",
  "choices": [ { "delta": { "content": "This is a test...", "role": "assistant" } } ],
  "created": 1740543996,
  "model": "model",
  "object": "chat.completion.chunk"
}

Respuesta (No-Stream)

{
  "choices":[ { "finish_reason":"stop", "message":{ "content":"This is a test...", "role":"assistant" } } ],
  "created":1740543499,
  "id":"chatcmpl-3a9c3572f29311efa69751e139332ced",
  "model":"model",
  "object":"chat.completion"
}

Respuesta (Fallo)

{
  "code": 102,
  "message": "The last content of this conversation is not from user."
}

Crear finalización de agente

Crea una respuesta del modelo para una conversación de chat de agente dada. Esta API sigue el mismo formato que la API de OpenAI.

POST

/api/v1/agents_openai/{agent_id}/chat/completions

Parámetros

Nombre	Tipo	Descripción
model*	string	El modelo utilizado para generar la respuesta.
messages*	list[object]	Una lista de mensajes de chat históricos. Debe contener al menos un mensaje con el rol de usuario.
stream	boolean	Si se debe recibir la respuesta como un stream.

Ejemplo de Solicitud

curl --request POST \
     --url http://{address}/api/v1/agents_openai/{agent_id}/chat/completions \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
        "model": "model",
        "messages": [{"role": "user", "content": "Say this is a test!"}],
        "stream": true
      }'

Gestión de Datasets

Crear dataset

Crea un nuevo conjunto de datos.

POST

/api/v1/datasets

Parámetros

Nombre	Tipo	Descripción
name*	string	Nombre único del dataset. Máx 128 caracteres, no distingue mayúsculas/minúsculas.
description	string	Breve descripción del dataset.
embedding_model	string	Nombre del modelo de embedding a usar. Ej: "BAAI/bge-large-zh-v1.5@BAAI".
permission	string	Permisos de acceso. Opciones: "me" (defecto), "team".
chunk_method	enum<string>	Método de chunking. Opciones: "naive" (defecto), "book", "email", "manual", etc.
parser_config	object	Configuración para el parser, varía según `chunk_method`.

Ejemplo de Solicitud

curl --request POST \
     --url http://{address}/api/v1/datasets \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
      "name": "test_1"
      }'

Ejemplos de Respuesta

Respuesta (Éxito)

{
  "code": 0,
  "data": {
      "id": "3b4de7d4241d11f0a6a79f24fc270c7f",
      "name": "Tbox Veritas example",
      "chunk_method": "naive",
      "embedding_model": "BAAI/bge-large-zh-v1.5@BAAI",
      "permission": "me",
      "status": "1"
  }
}

Respuesta (Fallo)

{
  "code": 101,
  "message": "Dataset name 'Tbox Veritas example' already exists"
}

Listar datasets

Obtiene una lista de los conjuntos de datos.

GET

/api/v1/datasets

Parámetros

Nombre	Tipo	Descripción
page	integer	Número de página. Defecto: 1.
page_size	integer	Tamaño de página. Defecto: 30.
order_by	string	Campo de ordenación. Opciones: `create_time` (defecto), `update_time`.
desc	boolean	Orden descendente. Defecto: true.
name	string	Filtrar por nombre de dataset.
id	string	Filtrar por ID de dataset.

Ejemplo de Solicitud

curl --request GET \
     --url http://{address}/api/v1/datasets?page=1&page_size=10 \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Actualizar dataset

Actualiza la configuración de un dataset específico.

PUT

/api/v1/datasets/{dataset_id}

Parámetros

Nombre	Tipo	Descripción
dataset_id*	string	ID del dataset a actualizar (en la ruta).
name	string	Nuevo nombre para el dataset.
description	string	Nueva descripción.

Ejemplo de Solicitud

curl --request PUT \
     --url http://{address}/api/v1/datasets/{dataset_id} \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
          "name": "updated_dataset"
     }'

Eliminar datasets

Elimina uno o más datasets por su ID.

DELETE

/api/v1/datasets

Parámetros

Nombre	Tipo	Descripción
ids*	list[string]	Lista de IDs de datasets a eliminar. Si es `null`, se eliminan todos.

Ejemplo de Solicitud

curl --request DELETE \
     --url http://{address}/api/v1/datasets \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
     "ids": ["d94a8dc02c9711f0930f7fbc369eab6d"]
     }'

Gestión de Archivos

Subir documentos

Sube uno o más documentos a un dataset específico.

POST

/api/v1/datasets/{dataset_id}/documents

Parámetros

Nombre	Tipo	Descripción
dataset_id*	string	ID del dataset (en la ruta).
file*	file	Documento a subir (form-data). Se pueden enviar múltiples archivos.

Ejemplo de Solicitud

curl --request POST \
     --url http://{address}/api/v1/datasets/{dataset_id}/documents \
     --header 'Content-Type: multipart/form-data' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --form 'file=@./test1.txt'