API pública

Una API REST versionada para su propio código: conversaciones con un agente, adjuntos, valoraciones, búsqueda en el conocimiento y pipelines de texto, autenticada con claves de API de proyecto.

La API pública vive bajo /api/v1 y solo acepta claves de API. Allí nunca se acepta una sesión de navegador, y nunca se acepta una clave en los endpoints propios del Studio, bajo /api/internal. Las dos superficies se mantienen separadas a propósito, y la pública es más reducida: crear agentes, publicar versiones y gestionar miembros se hace en el Studio.

Qué expone

Ámbito	Rutas	Alcance
Conversaciones	POST /api/v1/agents/{agentId}/conversations envía un mensaje, en una conversación nueva o en la que indique conversationId. GET sobre la misma ruta lista las conversaciones del agente, GET …/conversations/{conversationId} devuelve un hilo.	full para enviar, read para listar
Transmisión continua	GET …/conversations/{conversationId}/runs/{runId}/stream, como Server-Sent Events	read
Adjuntos	POST …/conversations/attachments (multipart) deposita un archivo que un mensaje cita después en attachmentIds. GET …/conversations/attachments/{attachmentId}/download devuelve una URL de descarga de corta duración.	full / read
Valoraciones	POST …/conversations/{conversationId}/feedback, una puntuación de 1 o -1 y un comentario opcional	full
Búsqueda en el conocimiento	POST /api/v1/knowledge/search inicia una búsqueda en colecciones, GET /api/v1/knowledge/search/{searchId} devuelve sus resultados	read
Pipelines	POST /api/v1/pipelines/execute ejecuta summarize, classify, translate o extract_entities sobre un texto. GET /api/v1/pipelines/results lista los resultados.	full / read
Entorno aislado	GET /api/v1/sandbox/requirement lee la política de entorno aislado de la instancia, POST /api/v1/sandbox/validate-mcp comprueba la ejecución MCP en un entorno aislado	read / full

{agentId} es el UUID del agente. La tarjeta Headless API de la pestaña Deploy del agente muestra el endpoint completo.

Claves

• Una clave pertenece a un proyecto y lleva un alcance: read, o full, que también cubre las rutas read.
• Su prefijo fija el entorno, rk_live_ o rk_test_, y el agente necesita un despliegue de API activo en ese mismo entorno. Desactivar el interruptor de la API en la pestaña Deploy corta el tráfico /api/v1 del agente, incluida la lectura.
• Puede restringirse a agentes concretos, para que una integración solo alcance lo que necesita.
• Puede llevar una fecha de caducidad.
• Su valor completo se muestra una sola vez, al crearla. Rikoo solo guarda un hash SHA-256 de ella.
• La revocación de una clave surte efecto en la siguiente petición.

Envíela en la cabecera Authorization, con o sin el prefijo Bearer.

curl -X POST "https://rikoo.example.com/api/v1/agents/$AGENT_ID/conversations" \
  -H "Authorization: Bearer $RIKOO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-question-0001" \
  -d '{"message":"My invoice is wrong","sync":true}'

Con "sync": true, la llamada espera a que termine la ejecución y devuelve la respuesta. Sin esa opción, la llamada devuelve de inmediato el conversationId y el runId, y usted sigue la ejecución en su flujo. La cabecera Idempotency-Key es opcional: un reintento con la misma clave obtiene la misma respuesta en lugar de crear un segundo turno.

Transmisión continua

El flujo de una ejecución es un flujo Server-Sent Events de sus eventos: la respuesta a medida que el modelo la produce (message.delta), las llamadas a herramientas cuando se hacen y un evento terminal (run.completed, run.failed, run.aborted o run.refused) que lo cierra. Empieza reproduciendo lo que la ejecución ya ha registrado, así que un cliente que se conecta tarde o se reconecta no pierde nada, y las conversaciones largas no necesitan un bucle de sondeo.

El contrato se genera desde el código

La instancia sirve su descripción OpenAPI en /api/openapi.json, con una vista interactiva en /api/docs. Se genera desde el código que sirve las rutas, no se escribe a mano. Las rutas bajo /api/v1 forman el contrato público.