API · v1

API para empresas

Publique e gerencie suas vagas no EmpregoAI por API — do seu ATS ou sistema de RH direto para a nossa plataforma — e leia o catálogo completo de vagas do site. Vagas criadas pela API são nativas: sua empresa é a fonte e elas entram no Google for Jobs.

⭐ A API é um recurso para assinantes. Contas no plano grátis não geram nem usam API keys — veja os planos. O limite de vagas ativas é o do seu plano (Start, Pro, Scale…).

1. Gerar sua API key

No painel da empresa, vá em Configurações → API e clique em Gerar chave. A chave aparece uma única vez — copie e guarde num lugar seguro. Guardamos apenas o hash; se perder, gere outra e revogue a antiga.

Formato da chave: ea_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Autenticação

Envie a chave no header Authorization em toda requisição:

# todas as chamadas exigem este header
Authorization: Bearer ea_live_sua_chave_aqui

3. Base URL

https://empregoai.com/api/v1

Todas as respostas são JSON com success: true|false. Erros trazem error e o status HTTP correto (401, 402, 403, 404, 429).

4. Endpoints

Método	Rota	O que faz
POST	`/vagas`	Cria uma vaga
GET	`/vagas`	Lista suas vagas
GET	`/vagas/{id}`	Detalhe de uma vaga
PATCH	`/vagas/{id}`	Edita campos da vaga
DELETE	`/vagas/{id}`	Fecha a vaga
GET	`/catalogo`	Lê TODAS as vagas do site (nativas + agregadas com link da fonte)

Campos da vaga

Campo	Tipo	Obrigatório	Observação
`titulo`	string	Sim	Cargo (ex.: "Desenvolvedor(a) PHP Pleno")
`descricao`	string	—	Descrição da vaga
`requisitos`	string	—	Requisitos
`salario`	string	—	Ex.: "R$ 6.000" ou "A combinar"
`local`	string	—	Cidade/UF (ex.: "São Paulo - SP")
`modelo`	string	—	`presencial` · `hibrido` · `remoto` (padrão: presencial)

POST /api/v1/vagas — criar vaga

curl -X POST https://empregoai.com/api/v1/vagas \
  -H "Authorization: Bearer ea_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "titulo": "Desenvolvedor(a) PHP Pleno",
    "descricao": "Trabalhe no backend do nosso produto...",
    "requisitos": "PHP 8, MySQL, APIs REST",
    "salario": "R$ 6.000 a R$ 8.000",
    "local": "São Paulo - SP",
    "modelo": "hibrido"
  }'

Resposta 201:

{
  "success": true,
  "vaga": {
    "id": 123,
    "titulo": "Desenvolvedor(a) PHP Pleno",
    "modelo": "hibrido",
    "status": "ativa",
    "url": "https://empregoai.com/vaga?id=123"
  }
}

GET /api/v1/vagas — listar

curl https://empregoai.com/api/v1/vagas \
  -H "Authorization: Bearer ea_live_sua_chave"
# → { "success": true, "vagas": [ ... ], "total": 7 }

PATCH /api/v1/vagas/{id} — editar

curl -X PATCH https://empregoai.com/api/v1/vagas/123 \
  -H "Authorization: Bearer ea_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{ "salario": "R$ 9.000", "modelo": "remoto" }'

DELETE /api/v1/vagas/{id} — fechar

curl -X DELETE https://empregoai.com/api/v1/vagas/123 \
  -H "Authorization: Bearer ea_live_sua_chave"
# → { "success": true, "fechada": true, "id": 123 }

Catálogo — todas as vagas do site

Lê o catálogo inteiro do EmpregoAI: vagas nativas (nossas) e agregadas (de ATS externo). A agregada vem com o link da fonte em fonte.url e em candidatar_url — o candidato aplica na origem. Paginado em 50 por página (use offset); total vem só na 1ª página.

GET /api/v1/catalogo — ler o catálogo

curl "https://empregoai.com/api/v1/catalogo?offset=0&pais=BR" \
  -H "Authorization: Bearer ea_live_sua_chave"

Filtros opcionais: pais (ISO-2, ex. BR/US), origem (app = nativa | agregada), q (busca em título/descrição/local). Resposta:

{
  "success": true,
  "total": 11764,
  "limite": 50,
  "tem_mais": true,
  "offset": 0,
  "vagas": [
    {
      "id": 4821,
      "origem": "agregada",
      "titulo": "Growth Account Executive",
      "empresa": "Webflow",
      "resumo": "...",
      "local": "U.S. Remote",
      "pais": "US",
      "modelo": "remoto",
      "candidatar_url": "https://job-boards.greenhouse.io/webflow/jobs/7833360",
      "fonte": { "nome": "Greenhouse", "url": "https://job-boards.greenhouse.io/webflow/..." }
    }
  ]
}
# vaga nativa: "fonte": null e "candidatar_url": "https://empregoai.com/vaga?id=123"

5. Erros e limites

Status	Significado
`401`	API key ausente ou inválida
`402`	Não assinante, ou limite de vagas do plano atingido (`upgrade: true`)
`403`	A chave não é de uma conta de empresa
`404`	Vaga não encontrada (ou não é sua)
`429`	Muitas requisições — aguarde e repita

Limite de requisições: 600/min por chave e 120/min por IP. O /catalogo tem teto próprio de 60/min por chave (é leitura em massa). Cada empresa pode ter até 10 chaves ativas — revogue as que não usar. Revogar uma chave é imediato.

Por que publicar por API?

Vaga publicada pela API é nativa: o EmpregoAI é a fonte oficial, então ela recebe página própria com dados estruturados (JobPosting) e entra no Google for Jobs e no sitemap. É diferente de vaga agregada de outras fontes, que fica só na vitrine.

Gerar minha primeira chave →