Lista o catálogo

Busca no título e no texto do anúncio (full-text do Postgres). Entre 2 e 80 caracteres. A ordem: com q, as vagas que casam o termo no título vêm primeiro, depois as que o citam só na descrição, e a data de publicação (da mais nova pra mais antiga) ordena dentro de cada grupo; sem q, é só a data. A mesma ordem do site e do buscar_vagas do MCP.

Sinônimo de onde=titulo, mantido por compatibilidade (era o único jeito até 2026-10-06). Com true, q casa só no título da vaga. Prefira onde. Se vier junto com onde, vale o onde. Aceita true/false (e 1/0); outro valor responde 422 com code invalid_params.

Onde q casa. Sem onde (o padrão): no título ou na descrição, com as que casam no título primeiro e as que só citam o termo na descrição depois, a data ordenando dentro de cada grupo. titulo: só no título, com o mesmo stemming do inglês da busca normal (managers acha "Manager"); serve pra achar vaga de um cargo: q=manager&onde=titulo traz "Engineering Manager", e não a vaga de engenheiro que "trabalha com Product Management". O stemming corta fundo, então "manager" também casa "Management" no título. tudo: título ou descrição numa lista só, da mais nova pra mais antiga, sem pôr as do título na frente. Com q, a resposta traz meta.busca (onde que valeu: titulo, tudo ou padrao; total; total_no_outro_modo; e uma dica): se vier pouco ou nada, tente o outro modo antes de dizer que não há vagas. Sem q, não muda nada. Outro valor responde 422 com code invalid_params.

Com true, tira as vagas que você (a conta dona do token) ocultou, no site ou por PUT /api/v1/eu/ocultas/{slug}: some da lista e do meta.total, como a caixa "Esconder vagas ocultadas" do site. Sem ele (o padrão, como no site), as ocultas vêm na lista com oculta: true. A lista das ocultas está em GET /api/v1/eu/ocultas. Aceita true/false (e 1/0); outro valor responde 422 com code invalid_params.

Com true, usa as skills do perfil da conta dona do token (GET /api/v1/eu/skills): só vêm vagas que citam pelo menos uma delas (com 4 ou mais skills no perfil, pelo menos 2, ou uma delas no título), e cada vaga traz skills_em_comum. A ordem passa a ser o match: mais skills em comum primeiro; no empate, a maior fração das skills da vaga que você cobre (a vaga que pede 3 e você tem as 3 antes da que pede 10); depois o termo no título (com q), a skill de skill no título, uma skill do perfil no título e, por fim, a data. Combina por "e" com os outros filtros (skill continua exigindo todas). Não liga sozinho pela preferência do perfil do site. Conta sem skills responde 422 com code invalid_params; não booleano, também.

O slug da empresa, exatamente como sai em GET /api/v1/companies ou em company.slug de cada vaga. Só o slug: o nome não casa. Slug que não existe responde 422 com code invalid_params, nunca lista vazia, pelo mesmo motivo de skill.

Um ou mais slugs do dicionário de skills, repetindo o parâmetro (?skill=typescript&skill=nextjs), até 10. Com vários, a vaga tem que citar todos. A ordem: com skill, as vagas que têm alguma das skills pedidas no título vêm primeiro, depois as que só a citam no texto, e a data ordena dentro de cada grupo (com q no padrão, a ordem do termo vale primeiro; cada vaga traz skills_no_titulo). Valor fora da lista responde 422, nunca lista vazia: lista vazia faria você concluir que não existe vaga, quando o que houve foi slug errado. A lista com contagem sai em GET /api/v1/meta.

O nível da vaga (o que o título anuncia, ou pleno quando o título não diz e o anúncio pede de 2 a 4 anos de experiência), em slug sem acento: junior, pleno, senior, staff ou lideranca (Manager, Head, Director, Lead, CTO). Repita o parâmetro pra mais de um (?nivel=senior&nivel=staff): entre níveis vale qualquer um (a vaga tem um nível só), e com q e skill vale e. Vaga sem nível detectado não entra em nenhum. O rótulo correspondente sai no campo seniority de cada vaga, e a contagem por nível em GET /api/v1/meta. Valor fora da lista responde 422.

O modelo de contrato no Brasil: clt (CLT, pago em reais), pj (PJ ou contractor), eor (contratado por um employer of record) ou nao-informado. Repita o parâmetro pra mais de um (?modelo=pj&modelo=eor): entre modelos vale qualquer um, e com os outros filtros vale e. Vale o modelo efetivo: o que o anúncio afirma ou, quando ele não diz, o da empresa (a soma do que as vagas abertas dela afirmam com a curadoria). Cada vaga traz hiring_models, e a contagem por modelo sai em GET /api/v1/meta. A sigla em qualquer caixa (CLT) também vale. Valor fora da lista responde 422.

A página, a partir de 1. Número inteiro: fração é recusada. Acima de 500 responde 422 com code invalid_params; pra ir mais fundo, estreite o filtro.

Itens por página, número inteiro. Acima de 50 a API recusa com 422 em vez de truncar: página clampada responde 200 com linhas que ninguém pediu, e quem pagina não tem como perceber.