> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mypilotindex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vagas

> Busque as vagas abertas, publique as vagas da sua empresa e mostre a um piloto as vagas que mais combinam com ele.

As vagas funcionam de três formas. Qualquer parceiro com `jobs.read` busca as vagas abertas. Uma empresa com `jobs.write` publica as próprias. Um app de piloto com um grant que tem `jobs.match` pergunta quais vagas abertas combinam com esse piloto.

## Busque as vagas abertas

```bash theme={null}
curl "https://{api-host}/v1/partner/jobs?q=citation&position_type=first_officer&page=1&page_size=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "id": "6f1c2a9e-3b7d-4c51-9e2a-0d4b8f6a1c33",
      "title": "First Officer, Citation Latitude",
      "company": { "id": "9a7e2c10-5b3d-4f6a-8c21-7d0e4b6f1a52", "name": "Example Air", "logo_url": null },
      "position_type": "first_officer",
      "base_airport_code": "KTEB",
      "min_total_hours": 1500,
      "required_licenses": ["ATP"],
      "posted_at": "2026-11-05T14:00:00Z",
      "url": "https://mypilotindex.com/jobs/6f1c2a9e-3b7d-4c51-9e2a-0d4b8f6a1c33?src=share"
    }
  ],
  "page": 1,
  "page_size": 20,
  "has_more": false
}
```

A lista traz vagas ativas e não expiradas, primeiro as em destaque, depois as mais novas. `page_size` vai até 50. `GET /v1/partner/jobs/{job_id}` lê uma vaga; uma vaga que não está ativa responde `404 not_found`.

## Publique uma vaga

O MyPilotIndex vincula o seu parceiro à sua empresa, e a vaga é publicada em nome dessa empresa. Sem o vínculo, a resposta é `403 forbidden` com o motivo `partner_not_bound`.

```bash theme={null}
curl -X POST https://{api-host}/v1/partner/jobs \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_ref": "req-2291",
    "title": "First Officer, Citation Latitude",
    "position_type": "first_officer",
    "base_airport_code": "KTEB",
    "min_total_hours": 1500,
    "min_pic_hours": 500,
    "required_licenses": ["ATP"],
    "application_url": "https://careers.example.com/2291",
    "status": "active"
  }'
```

```json theme={null}
{ "job_id": "6f1c2a9e-3b7d-4c51-9e2a-0d4b8f6a1c33", "replayed": false }
```

`title` e `position_type` são obrigatórios. `status` é `active`, e a vaga entra no ar na hora, ou `draft`, e ninguém a lê até que uma alteração a torne ativa. A [referência da API](https://developers.mypilotindex.com/pt-br/api-reference/introduction.md) lista cada campo; um membro fora dessa lista, como `company_id` ou `featured`, responde `400 invalid_request`.

`client_ref` funciona como na [publicação](https://developers.mypilotindex.com/pt-br/publishing.md#repetindo-sem-risco): uma repetição com o mesmo corpo responde `200` com `replayed: true` e não publica nada. Um parceiro publica no máximo 50 vagas em 24 horas; passado isso, a resposta é `429 rate_limited` com o motivo `publication_throttled` e `Retry-After`.

## Altere ou encerre uma vaga

`PATCH /v1/partner/jobs/{job_id}` altera os membros que você envia e responde com a vaga. `POST /v1/partner/jobs/{job_id}/close` arquiva a vaga, e encerrar uma vaga já encerrada responde `200`.

Você altera apenas as vagas que criou, para a empresa à qual está vinculado. Qualquer outra responde `404 not_found`, exatamente como uma vaga que não existe.

Voltar uma vaga encerrada para `active` a reabre por mais 30 dias, a menos que você envie o seu próprio `expires_at`.

## Mostre a um piloto as vagas que combinam

```bash theme={null}
curl "https://{api-host}/v1/partner/grants/{grant_id}/job-matches?limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "id": "6f1c2a9e-3b7d-4c51-9e2a-0d4b8f6a1c33",
      "title": "First Officer, Citation Latitude",
      "match": {
        "overall": 86,
        "matchLabel": "good_match",
        "engine_version": "jobmatch.web.1",
        "detail": "plan_required"
      }
    }
  ]
}
```

A resposta parte das 50 vagas ativas mais novas e as ordena por compatibilidade, da maior para a menor. `limit` vai até 20.

A compatibilidade é a mesma que o piloto vê no MyPilotIndex, no plano dele. A compatibilidade de um piloto do plano gratuito traz `overall`, `matchLabel` e `detail: "plan_required"`. A de um piloto pagante troca `detail` por `breakdown` e `missingRequirements`. `match` é null para uma vaga que o motor não pontua, como uma de mecânico, e essas vagas vêm por último.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.