> ## 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.

# Response Structure

> Understanding special fields and API response structure

## Response Format

Responses are in **JSON** format with the `Content-Type: application/json` header.

## Special Fields

The following fields have special meaning in all API responses:

### `_status`

Response status:

* **`"OK"`**: Data was extracted correctly
* **`"INVALID"`**: Request parameters are invalid (HTTP status remains 200)

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

### `_self`

URI of the current resource.

* At the root of the response: corresponds to the request URL
* In a nested object: URL to obtain all data for this resource

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

### `_schema`

URI of the resource description in **JSON-Schema** format.

This URL provides a comprehensive and up-to-date description of the resource schema.

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

<Note>
  Schemas are automatically updated with the API and are therefore more accurate than this documentation.
</Note>

### `_actions`

List of possible actions on the current data.

This field is only provided when actions are available. Content depends on user permissions.

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

### `_next`

URI of the next page for paginated resources.

If this field is empty or absent, you've reached the last page.

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

### `items`

List containing response elements for collections.

```json theme={null}
{
  "_self": "/restapi/v1/job",
  "_next": "/restapi/v1/job?pagecursor=10",
  "items": [
    {
      "id": 1,
      "title": "Full-Stack Developer"
    },
    {
      "id": 2,
      "title": "Project Manager"
    }
  ]
}
```

## Error Handling

### Validation Errors

When `_status` equals `"INVALID"`, an `invalid` field details the errors:

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

### HTTP Codes

The API uses standard HTTP codes:

* **200**: Success (also check `_status`)
* **307**: Temporary redirect (e.g., CV download)
* **404**: Resource not found
* **401**: Authentication required
* **403**: Access denied
* **429**: Too Many Requests (45 req/min per IP limit exceeded)
* **500**: Server error

## Complete Response Example

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