Pular para conteúdo principal
API v1 — Referência Completa

API REST do Sofia AI

Integre agentes e orquestrações de IA em qualquer aplicação usando nossa API REST. Autentique com uma API key e comece em minutos.

Autenticação

Todas as requisições à API v1 requerem autenticação via Bearer token. Gere sua API key no dashboard.

bash
# Adicione o header Authorization em todas as requisições
curl -H "Authorization: Bearer sk_live_sua_api_key_aqui" \
  https://sofiaia.roilabs.com.br/api/v1/agents

Rate Limits

Free
100 req/dia
Pro
10.000 req/dia
Business
Ilimitado

Agentes

GET
/api/v1/agents

Lista todos os agentes ativos do seu tenant.

bash
curl -H "Authorization: Bearer sk_live_..." \
  https://sofiaia.roilabs.com.br/api/v1/agents
json
{
  "data": [
    {
      "id": "agent-uuid",
      "name": "Atendimento ao Cliente",
      "description": "Agente de suporte",
      "model": "llama-3.3-70b-versatile",
      "status": "active",
      "memoryEnabled": true,
      "createdAt": "2026-02-24T10:00:00Z"
    }
  ],
  "total": 1
}
POST
/api/v1/agents/[id]/chat

Envia uma mensagem para um agente e recebe a resposta.

bash
curl -X POST https://sofiaia.roilabs.com.br/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Olá, preciso de ajuda", "conversationId": "conv_123"}'
json
{
  "reply": "Olá! Estou aqui para ajudar. Qual é a sua dúvida?",
  "conversationId": "conv_123",
  "tokens": 156,
  "model": "llama-3.3-70b-versatile"
}

Exemplo com JavaScript

javascript
const response = await fetch('https://sofiaia.roilabs.com.br/api/v1/agents/AGENT_ID/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Quais são os planos disponíveis?',
    conversationId: 'minha-sessao-123',
  }),
});

const { reply, conversationId, tokens } = await response.json();
console.log(reply);

Orquestrações

GET
/api/v1/orchestrations

Lista todas as orquestrações ativas do seu tenant.

bash
curl -H "Authorization: Bearer sk_live_..." \
  https://sofiaia.roilabs.com.br/api/v1/orchestrations
POST
/api/v1/orchestrations/[id]/execute

Executa uma orquestração de forma assíncrona. Retorna um executionId para consultar o status.

bash
curl -X POST https://sofiaia.roilabs.com.br/api/v1/orchestrations/ORCH_ID/execute \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input": "Crie um relatório de vendas do mês", "variables": {"mes": "fevereiro"}}'
json
{
  "executionId": "exec-uuid",
  "status": "pending",
  "orchestrationId": "ORCH_ID"
}

Execuções

GET
/api/v1/executions/[id]

Consulta o status e resultado de uma execução.

bash
curl -H "Authorization: Bearer sk_live_..." \
  https://sofiaia.roilabs.com.br/api/v1/executions/EXECUTION_ID
json
{
  "id": "exec-uuid",
  "orchestrationId": "ORCH_ID",
  "status": "completed",
  "output": "Relatório de vendas de fevereiro 2026...",
  "tokensUsed": 2847,
  "durationMs": 8432,
  "createdAt": "2026-02-24T10:00:00Z",
  "completedAt": "2026-02-24T10:00:08Z"
}

Polling para execuções

Como as execuções são assíncronas, use polling para verificar quando concluem. Recomendamos intervalos de 2-5 segundos com timeout de 5 minutos.

Polling com JavaScript

javascript
async function executeAndWait(orchestrationId, input) {
  const API_KEY = 'sk_live_...';
  const BASE = 'https://sofiaia.roilabs.com.br';

  // Iniciar execução
  const { executionId } = await fetch(`${BASE}/api/v1/orchestrations/${orchestrationId}/execute`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ input }),
  }).then(r => r.json());

  // Aguardar conclusão via polling
  for (let i = 0; i < 60; i++) {
    await new Promise(r => setTimeout(r, 5000)); // 5s

    const execution = await fetch(`${BASE}/api/v1/executions/${executionId}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` },
    }).then(r => r.json());

    if (execution.status === 'completed') return execution.output;
    if (execution.status === 'failed') throw new Error(execution.error);
  }

  throw new Error('Timeout: execução demorou mais de 5 minutos');
}

const output = await executeAndWait('orch-id', 'Relatório do mês');
console.log(output);

Códigos de Resposta

200OKRequisição bem-sucedida
201CreatedRecurso criado com sucesso
202AcceptedExecução iniciada (assíncrono)
400Bad RequestParâmetros inválidos ou ausentes
401UnauthorizedAPI key ausente ou inválida
403ForbiddenSem permissão para acessar o recurso
404Not FoundRecurso não encontrado
429Too Many RequestsLimite de requisições atingido
500Internal Server ErrorErro interno do servidor

Pronto para integrar?

Gere sua API key gratuitamente e comece a integrar em minutos.