Guia de conexão à API

Escolha o serviço correto

Estes exemplos usam um runtime rikoko local ou em hospedagem própria. A origem local padrão é http://127.0.0.1:4310. Login do site, chave do provedor e chave do espaço de trabalho são credenciais diferentes. O Dashboard do site ainda não emite chaves públicas de API; não invente uma URL de nuvem rikoko. Use o endereço real e a chave fornecidos pela instalação.

Transporte e autenticação

As ferramentas HTTP usam POST /api/tools/<tool_name>, Content-Type: application/json e Authorization: Bearer <workspace-key>. Envie os argumentos diretamente no corpo JSON. Chamadas HTTP bem-sucedidas retornam {"result": ...}. Clientes MCP conectam-se a /mcp pelo protocolo MCP; o corpo de uma ferramenta HTTP não é uma requisição MCP. O limite de corpo JSON é 2 MiB neste runtime.

Primeira chamada com cURL

Inicie o runtime e defina RIKOKO_WORKSPACE_KEY no shell pelo método de gerenciamento de segredos da instalação. Não coloque a chave no código versionado ou no JavaScript do navegador. Esta chamada apenas consulta capacidades; não gera mídia. Uma resposta positiva de /health não valida credenciais ou acesso 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 '{}'

Chame pelo Node.js

Use código no servidor com a API fetch do Node.js (versão 22 ou superior para este pacote). Verifique o status HTTP e o objeto error antes de ler result. Não repita mutações automaticamente neste helper. Um timeout ou erro de rede após o envio de um job não comprova falha no envio.

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

Operações comuns de leitura