Referência da API

Visão Geral

Uma API REST para ler e movimentar suas vagas e candidatos. Ela foi criada para que um agente de IA — Claude, ChatGPT, um script seu — possa trabalhar no seu pipeline com um token que tem apenas as permissões que você conceder.

curl https://hireaan.com.br/api/v1/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Autenticação

A API usa tokens bearer. Crie um no app em Organização → API, dê a ele um nome que você reconheça depois e marque apenas os escopos de que essa integração precisa. O token é exibido uma única vez, quando você o cria. Copie-o nesse momento, porque ele não pode ser recuperado depois.

Os tokens expiram seis meses após serem criados, e você pode revogar qualquer um a qualquer momento na mesma página. Proprietários e administradores da equipe veem todos os tokens criados na equipe, com quem os criou e quando foram usados pela última vez.

{ "error": { "code": "unauthenticated", "message": "Unauthenticated.", "details": null } }

Escopos

Um token tem apenas os escopos que você marcar. Chamar um endpoint sem o escopo dele retorna 403 insufficient_scope, e a requisição nunca chega aos seus dados. Comece só com leitura e adicione escopos de escrita quando precisar.

messages:send e scheduling:write já podem ser concedidos, mas ainda não têm endpoints.

Convenções

• A URL base é https://hireaan.com.br. Todos os caminhos desta referência são relativos a ela.
• Um único registro vem em data. Listas vêm em data, com links e meta. Navegue pelas páginas com ?page=2. Cada página tem 15 registros.
• Um token acessa apenas o que o dono dele acessa no app: todas as vagas das equipes que ele possui ou administra e, nas outras equipes, só as vagas que são dele ou às quais foi atribuído. Qualquer outra coisa retorna 404, e não 403, então a API nunca confirma que existe uma vaga que você não pode ver.
• Toda gravação fica registrada do nosso lado com o usuário, o token e o endereço IP que a fizeram.

Erros

Todos os erros usam o mesmo envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "The title field is required.",
    "details": { "title": ["The title field is required."] }
  }
}

details traz as mensagens de cada campo quando a validação falha e é null nos demais casos.

Limites de taxa

60 requisições por minuto, contadas por usuário e não por token, então dois tokens da mesma pessoa compartilham o mesmo limite. As respostas bem-sucedidas trazem X-RateLimit-Limit e X-RateLimit-Remaining. Quando a contagem restante chegar a zero, espere o minuto passar antes de enviar mais.

{ "error": { "code": "rate_limited", "message": "Too Many Attempts.", "details": null } }

Idempotência

Toda gravação aceita um cabeçalho opcional Idempotency-Key. Envie a mesma chave duas vezes e a segunda chamada retorna a resposta armazenada da primeira, em vez de executar a ação de novo. Útil quando um erro de rede deixa você sem saber se uma vaga foi criada.

curl -X POST https://hireaan.com.br/api/v1/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ea6a-4c3b-9f2d-1b7c0a5e6d90" \
  -d '{"title": "Backend Engineer"}'

• Uma resposta repetida traz Idempotent-Replay: true.
• As chaves valem para a sua equipe e ficam guardadas por 24 horas.
• Só as respostas bem-sucedidas são armazenadas, então uma chamada que falhou pode ser repetida com a mesma chave. Use um UUID novo para cada ação.

Endpoints

Está faltando algo?

Se você precisa de um endpoint que ainda não está aqui, fale com a gente e conte o que está construindo.