API connection guide

Choose the correct service

These examples target a running local or self-hosted rikoko runtime. The default local origin is http://127.0.0.1:4310. Public website login, a provider key and a runtime workspace key are different credentials. The website Dashboard does not currently issue public API keys; do not substitute a guessed rikoko cloud URL. Use the actual address and workspace key supplied by your installation.

Transport and authentication

HTTP tools use POST /api/tools/<tool_name>, Content-Type: application/json and Authorization: Bearer <workspace-key>. Send the tool arguments directly as the JSON body. Successful HTTP tool calls return {"result": ...}. MCP clients connect to /mcp using the MCP protocol; a raw HTTP tools body is not an MCP request. JSON tool bodies are limited to 2 MiB in this runtime.

First request with cURL

Start the runtime and set RIKOKO_WORKSPACE_KEY in your shell using your installation’s secret-management method. Keep it out of source control and browser JavaScript. This request only reads capabilities; it does not generate media. A successful /health response alone does not validate credentials or model access.

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 '{}'

Call from Node.js

Use server-side code with the fetch API (Node.js 22 or later for this package). Check the HTTP status and error envelope before reading result. Do not automatically retry mutations in this helper. A read timeout or network error after job submission does not prove the submission failed.

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);

Common read operations