Guía de conexión a la API

Elige el servicio correcto

Estos ejemplos usan un runtime rikoko local o autoalojado. El origen local predeterminado es http://127.0.0.1:4310. El inicio de sesión del sitio, la clave del proveedor y la clave del espacio de trabajo son credenciales diferentes. El Dashboard todavía no emite claves públicas de API; no inventes una URL de nube rikoko. Usa la dirección real y la clave proporcionadas por la instalación.

Transporte y autenticación

Las herramientas HTTP usan POST /api/tools/<tool_name>, Content-Type: application/json y Authorization: Bearer <workspace-key>. Envía los argumentos directamente en el cuerpo JSON. Las llamadas HTTP exitosas devuelven {"result": ...}. Los clientes MCP se conectan a /mcp mediante el protocolo MCP; el cuerpo de una herramienta HTTP no es una solicitud MCP. El límite del cuerpo JSON es de 2 MiB en este runtime.

Primera llamada con cURL

Inicia el runtime y define RIKOKO_WORKSPACE_KEY en el shell mediante el método de gestión de secretos de la instalación. No incluyas la clave en código versionado ni en JavaScript del navegador. Esta llamada solo consulta capacidades; no genera medios. Una respuesta positiva de /health no valida credenciales ni acceso a modelos.

export RIKOKO_BASE_URL="http://127.0.0.1:4310"
curl --fail-with-body "$RIKOKO_BASE_URL/api/tools/capabilities" \
  -H "Authorization: Bearer $RIKOKO_WORKSPACE_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'

Llama desde Node.js

Usa código del servidor con la API fetch de Node.js (versión 22 o posterior para este paquete). Revisa el estado HTTP y el objeto error antes de leer result. No repitas mutaciones automáticamente en este helper. Un timeout o error de red después de enviar un job no demuestra que el envío haya fallado.

const base = process.env.RIKOKO_BASE_URL || "http://127.0.0.1:4310";
const key = process.env.RIKOKO_WORKSPACE_KEY;
if (!key) throw new Error("Set RIKOKO_WORKSPACE_KEY");

async function callTool(name, args = {}) {
  const response = await fetch(`${base}/api/tools/${encodeURIComponent(name)}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(args),
    signal: AbortSignal.timeout(30_000),
  });
  const body = await response.json();
  if (!response.ok || body.error) {
    throw new Error(`${body.error?.code || response.status}: ${body.error?.message || "Request failed"}`);
  }
  return body.result;
}

const capabilities = await callTool("capabilities");
console.log(capabilities);
const guide = await callTool("rikoko_guide", { topic: "overview" });
console.log(guide);

Operaciones comunes de lectura