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

# Structure des réponses

> Comprendre les champs spéciaux et la structure des réponses de l'API

## Format des réponses

Les réponses sont au format **JSON** avec l'en-tête `Content-Type: application/json`.

## Champs spéciaux

Les champs suivants ont une signification particulière dans toutes les réponses de l'API :

### `_status`

Statut de la réponse :

* **`"OK"`** : Les données ont été extraites correctement
* **`"INVALID"`** : Les paramètres de la requête sont invalides (le statut HTTP reste 200)

```json theme={null}
{
  "_status": "OK",
  "data": { ... }
}
```

### `_self`

URI de la ressource actuelle.

* À la racine de la réponse : correspond à l'URL de la requête
* Dans un objet imbriqué : URL permettant d'obtenir l'ensemble des données de cette ressource

```json theme={null}
{
  "_self": "/restapi/v1/job/42",
  "candidate": {
    "_self": "/restapi/v1/candidate/123"
  }
}
```

### `_schema`

URI de la description de la ressource au format **JSON-Schema**.

Cette URL fournit une description exhaustive et à jour du schéma de la ressource.

```json theme={null}
{
  "_schema": "/restapi/schemav1/job"
}
```

<Note>
  Les schémas sont mis à jour automatiquement avec l'API et sont donc plus fidèles que cette documentation.
</Note>

### `_actions`

Liste des actions possibles sur les données courantes.

Ce champ n'est fourni que lorsque des actions sont disponibles. Le contenu dépend des droits de l'utilisateur.

```json theme={null}
{
  "_actions": [
    {
      "_self": "/restapi/v1/note",
      "doc": "Add a new note",
      "method": "POST"
    }
  ]
}
```

### `_next`

URI de la page suivante pour les ressources paginées.

Si ce champ est vide ou absent, vous avez atteint la dernière page.

```json theme={null}
{
  "_next": "/restapi/v1/job?pagecursor=42"
}
```

### `items`

Liste contenant les éléments de la réponse pour les collections.

```json theme={null}
{
  "_self": "/restapi/v1/job",
  "_next": "/restapi/v1/job?pagecursor=10",
  "items": [
    {
      "id": 1,
      "title": "Développeur Full-Stack"
    },
    {
      "id": 2,
      "title": "Chef de projet"
    }
  ]
}
```

## Gestion des erreurs

### Erreurs de validation

Lorsque `_status` vaut `"INVALID"`, un champ `invalid` détaille les erreurs :

```json theme={null}
{
  "_status": "INVALID",
  "invalid": {
    "candidate_id": {
      "code": null,
      "message": "Permission denied"
    },
    "organisation_id": {
      "code": null,
      "message": "Permission denied"
    }
  }
}
```

### Codes HTTP

L'API utilise les codes HTTP standards :

* **200** : Succès (vérifiez aussi `_status`)
* **307** : Redirection temporaire (ex: téléchargement de CV)
* **404** : Ressource non trouvée
* **401** : Authentification requise
* **403** : Accès refusé
* **429** : Trop de requêtes (limite de 45 req/min par IP dépassée)
* **500** : Erreur serveur

## Exemple de réponse complète

```json theme={null}
{
  "_status": "OK",
  "_self": "/restapi/v1/job/42",
  "_schema": "/restapi/schemav1/job",
  "id": 42,
  "title": "Développeur Full-Stack",
  "status": "OPEN",
  "applications": {
    "_self": "/restapi/v1/job/42/application"
  },
  "process": {
    "_self": "/restapi/v1/process/72",
    "id": 72
  }
}
```