Documentação Sofia AI

A Sofia AI fornece uma API REST para gerenciar e executar orquestrações de agentes programaticamente. Use a API para integrar IA multi-agente diretamente nos seus sistemas, pipelines e aplicações.

API Key auth

Autenticação simples via header X-API-Key

REST JSON

Endpoints REST padrão com resposta JSON

Qualquer linguagem

Funciona com curl, Python, JS, Go, etc.

Getting Started

Crie agente, orquestração e execute via API em 10min

Plugins

Funções JavaScript customizadas para agentes

Agent-to-Agent

Protocolo de delegação entre agentes

API Reference

Todos os endpoints REST com exemplos

Quick Start

Em menos de 5 minutos você executa sua primeira orquestração via API.

1. Crie sua conta e acesse o dashboard
Registre-se em sofiaia.roilabs.com.br/register e crie sua primeira orquestração.
2. Gere uma API Key
Acesse Dashboard → Settings → API Keys e crie uma chave.

3. Liste suas orquestrações

curl https://sofiaia.roilabs.com.br/api/public/orchestrations \
  -H "X-API-Key: SUA_API_KEY"

4. Execute uma orquestração

curl -X POST https://sofiaia.roilabs.com.br/api/public/orchestrations/ID/run \
  -H "X-API-Key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Crie um relatório de mercado sobre IA no Brasil"}'

Autenticação

Todas as requisições à API pública requerem um header X-API-Key com sua chave de API.

X-API-Key: sk_live_xxxxxxxxxxxxxxxx

Importante: Nunca exponha sua API key em código client-side ou repositórios públicos. Use variáveis de ambiente.

Orquestrações

GET/api/public/orchestrations

Lista todas as orquestrações ativas da sua conta.

Resposta:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Pipeline de Marketing",
      "description": "Pesquisador → Copywriter → Revisor",
      "strategy": "sequential",
      "agents": [...],
      "createdAt": "2026-02-23T..."
    }
  ],
  "meta": { "count": 1 }
}

POST/api/public/orchestrations/:id/run

Executa uma orquestração com o input fornecido. Retorna um execution ID para polling.

Body:

{ "input": "Sua mensagem ou contexto aqui" }

Resposta (202 Accepted):

{
  "success": true,
  "data": {
    "executionId": "uuid",
    "orchestrationId": "uuid",
    "status": "pending",
    "message": "Execution queued. Poll /api/public/executions/:id"
  }
}

Agentes

GET/api/public/agents

Lista todos os agentes ativos da sua conta.

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Copywriter",
      "description": "Especialista em copy persuasivo",
      "model": "llama-3.3-70b-versatile",
      "temperature": 0.7
    }
  ],
  "meta": { "count": 1 }
}

Execuções

GET/api/public/executions/:id

Retorna status e resultado de uma execução. Faça polling até status ser completed ou failed.

{
  "success": true,
  "data": {
    "id": "uuid",
    "status": "completed",  // pending | running | completed | failed
    "output": { "result": "Texto final gerado pela orquestração" },
    "durationMs": 4200,
    "tokensUsed": 1850,
    "completedAt": "2026-02-23T12:01:00Z"
  }
}

Códigos de Erro

Status	Significado
`401`	API key inválida ou ausente
`404`	Recurso não encontrado ou não pertence à sua conta
`400`	Parâmetros inválidos ou ausentes no body
`429`	Rate limit atingido — aguarde antes de tentar novamente
`500`	Erro interno — tente novamente ou contate o suporte

SDKs & Exemplos

Python

import requests

API_KEY = "SUA_API_KEY"
BASE = "https://sofiaia.roilabs.com.br/api/public"
headers = {"X-API-Key": API_KEY}

# Listar orquestrações
r = requests.get(f"{BASE}/orchestrations", headers=headers)
orchestrations = r.json()["data"]

# Executar a primeira
orch_id = orchestrations[0]["id"]
r = requests.post(f"{BASE}/orchestrations/{orch_id}/run",
    headers={**headers, "Content-Type": "application/json"},
    json={"input": "Analise o mercado de SaaS no Brasil"})
execution_id = r.json()["data"]["executionId"]

# Fazer polling
import time
while True:
    r = requests.get(f"{BASE}/executions/{execution_id}", headers=headers)
    data = r.json()["data"]
    if data["status"] in ("completed", "failed"):
        print(data["output"])
        break
    time.sleep(2)

JavaScript / Node.js

const API_KEY = process.env.SOFIA_API_KEY;
const BASE = "https://sofiaia.roilabs.com.br/api/public";
const h = { "X-API-Key": API_KEY, "Content-Type": "application/json" };

// Executar orquestração
const run = await fetch(`${BASE}/orchestrations/ORCH_ID/run`, {
  method: "POST",
  headers: h,
  body: JSON.stringify({ input: "Sua mensagem aqui" }),
}).then(r => r.json());

const execId = run.data.executionId;

// Polling
let result;
while (true) {
  result = await fetch(`${BASE}/executions/${execId}`, { headers: h }).then(r => r.json());
  if (["completed","failed"].includes(result.data.status)) break;
  await new Promise(r => setTimeout(r, 2000));
}
console.log(result.data.output);

Precisa de ajuda?

Abra uma issue no GitHub ou entre em contato pelo formulário de suporte.