API Reference

Gerencie seus agentes de IA. Crie agentes a partir de templates e delete quando não precisar mais. Cada agente criado é único e independente.

POST /v1/agents

Cria um novo agente de IA a partir de um template. Cada agente é único e independente.

curl -X POST https://v3.iakyra.com/v1/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sua_api_key_aqui" \
  -d '{
    "templateId": "c7ce2f00-a08d-491f-a6a1-7168ca31b532",
    "agentName": "meu-agente-personalizado"
  }'

DELETE /v1/agents/:agentId

Deleta um agente permanentemente. O agente será removido da plataforma KYRA AI e do banco de dados.

curl -X DELETE https://v3.iakyra.com/v1/agents/agent-4e696070-d9cb-45c9-9bad-f4591c90ca0a \
  -H "Authorization: Bearer sua_api_key_aqui"

Crie conversas com seus agentes e inclua informações de anamnese para respostas personalizadas.

POST /v1/conversations

Cria uma nova conversa com um agente específico. Você pode opcionalmente incluir dados de anamnese do aluno para que o agente tenha contexto desde o início.

curl -X POST https://v3.iakyra.com/v1/conversations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sua_api_key_aqui" \
  -d '{
    "agentId": "agent-4e696070-d9cb-45c9-9bad-f4591c90ca0a",
    "title": "Avaliação Postural - João Silva",
    "anamnesis": {
      "name": "João Silva",
      "age": 30,
      "weight": 80,
      "height": 175,
      "goal": "Ganhar massa muscular"
    }
  }'

Envie mensagens para seus agentes e recupere o histórico de conversas. Suporta texto e imagens para análise multimodal.

POST /v1/conversations/:conversationId/messages

Envia uma mensagem para o agente da conversa. Suporta texto e imagens para análise multimodal.

curl -X POST https://v3.iakyra.com/v1/conversations/cf2e0fb1-6b56-456f-9966-8350b279e91f/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sua_api_key_aqui" \
  -d '{
    "message": "Olá! Como posso melhorar minha postura?",
    "images": ["https://seu-bucket.supabase.co/chat-images/path/to/image.jpg"]
  }'

GET /v1/conversations/:conversationId/messages

Recupera todas as mensagens de uma conversa em ordem cronológica.

curl https://v3.iakyra.com/v1/conversations/cf2e0fb1-6b56-456f-9966-8350b279e91f/messages \
  -H "Authorization: Bearer sua_api_key_aqui"

Faça upload de imagens para análise postural e outras funcionalidades multimodais.

curl -X POST https://v3.iakyra.com/v1/upload/images \
  -H "Authorization: Bearer sua_api_key_aqui" \
  -F "files=@/caminho/para/imagem1.jpg" \
  -F "files=@/caminho/para/imagem2.jpg"

const formData = new FormData();
formData.append('files', file1);
formData.append('files', file2);

const response = await fetch('https://v3.iakyra.com/v1/upload/images', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sua_api_key_aqui'
  },
  body: formData
});

const result = await response.json();
console.log(result.data.files);

Rate Limiting

A API implementa limites de requisições para garantir estabilidade, prevenir abuso e garantir que todos os usuários tenham acesso justo aos recursos. Os limites são aplicados por API Key e contam todas as requisições feitas para qualquer endpoint.

Limites Aplicados

Headers de Rate Limit

Todas as respostas da API incluem headers informativos sobre os limites. Use esses headers para monitorar seu uso e evitar atingir os limites:

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 53
X-RateLimit-Limit-Hour: 1000
X-RateLimit-Remaining-Hour: 993
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 9993

Códigos de Status

A API retorna códigos de status HTTP padrão para indicar o resultado de cada requisição. Todos os códigos seguem o padrão HTTP.

Tratamento de Erros

A API retorna respostas de erro padronizadas com informações detalhadas sobre o problema. Todas as respostas de erro seguem o formato ErrorResponse.

{
  "error": "Error Type",
  "message": "Descrição detalhada do erro",
  "code": "ERROR_CODE"
}

try {
  const response = await fetch('https://v3.iakyra.com/v1/agents', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer sua_api_key_aqui'
    },
    body: JSON.stringify({ templateId: '...' })
  });

  if (!response.ok) {
    const errorData = await response.json();
    console.error('Erro:', errorData.error);
    console.error('Código:', errorData.code);
    // Tratar erro conforme código
    if (errorData.code === 'UNAUTHORIZED') {
      // API Key inválida
    } else if (errorData.code === 'INVALID_REQUEST') {
      // Campos faltando
    }
    return;
  }

  const data = await response.json();
  console.log('Sucesso:', data.data);
} catch (error) {
  console.error('Erro de rede:', error);
}