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/agentsRate Limits
Free
100 req/dia
Pro
10.000 req/dia
Business
Ilimitado
Agentes
GET
/api/v1/agentsLista todos os agentes ativos do seu tenant.
bash
curl -H "Authorization: Bearer sk_live_..." \
https://sofiaia.roilabs.com.br/api/v1/agentsjson
{
"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]/chatEnvia 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/orchestrationsLista todas as orquestrações ativas do seu tenant.
bash
curl -H "Authorization: Bearer sk_live_..." \
https://sofiaia.roilabs.com.br/api/v1/orchestrationsPOST
/api/v1/orchestrations/[id]/executeExecuta 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_IDjson
{
"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.