# Tags API Endpoint Documentation

Role taxonomy tags (ROLE1/ROLE2/ROLE3) with recursive parent hierarchy.

---

## Introduction

This endpoint provides access to the role taxonomy used in job classification.  
Each tag belongs to one of three role levels:

- `1` = ROLE1 (broad role family)
- `2` = ROLE2 (more specific role category)
- `3` = ROLE3 (high-resolution role label)

Tags include a recursively nested `parent` chain, so you can traverse from a ROLE3 tag up to ROLE2 and ROLE1 in one response.

## Endpoint Overview

**Endpoint (list):** `/api/tags/`  
**Endpoint (single element):** `/api/tags/{id}/`  
**Method:** `GET`  
**Authorization Required:** Yes  
**Description:** Returns role tags with optional filtering by type, name, and parent relationship.

## Access Requirements

This endpoint requires an API key with **access pro+** subscription.

Requests without pro+ access return a permission error.

## Request

### Using curl

```bash
curl -X GET "https://jobdataapi.com/api/tags/?tag_type=3&name=engineer" \
     -H "Authorization: Api-Key YOUR_API_KEY"
```

### Using Python

```python
import requests

url = "https://jobdataapi.com/api/tags/"
params = {
    "tag_type": "3",
    "name": "engineer"
}
headers = {"Authorization": "Api-Key YOUR_API_KEY"}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

## Parameters

The Tags endpoint supports the following query parameters:

- **tag_type** [[mc](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filter by tag level. Accepted values: `1`, `2`, `3`, or aliases like `ROLE1`, `ROLE2`, `ROLE3`. Supports multi-value include/exclude syntax.
- **name** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Case-insensitive name search (`icontains`). Supports multi-keyword include/exclude syntax.
- **parent_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filter by direct parent tag ID. Supports multi-value include/exclude syntax.
- **page**: Page number in paginated result set.
- **page_size**: Results per page (default and limits follow global API pagination behavior).

### Multi-value behavior

This endpoint follows the same multi-value conventions used in other API endpoints:

- Pipe-separated include values: `value1|value2`
- Exclude values with `-`: `-value3`
- Mixed include/exclude is supported.

Examples:

- `tag_type=2|3`
- `tag_type=ROLE3|-ROLE1`
- `parent_id=12|34|-56`
- `name=engineer|developer|-intern`

## Response

The response is paginated and contains tags in `results`.

### Top-Level Response Structure

- **count**: Total number of matching tags.
- **next**: URL for next page, or `null`.
- **previous**: URL for previous page, or `null`.
- **results**: Array of tag objects.

### Tag Object Structure

Each tag object includes:

- **id**: Unique tag identifier.
- **tag_type**: Role level (`1`, `2`, `3`).
- **name**: Canonical tag name.
- **parent**: Parent tag object or `null`.

`parent` is recursively nested through all available ancestors:

- ROLE3 -> parent ROLE2 -> parent ROLE1 -> `null`
- ROLE2 -> parent ROLE1 -> `null`
- ROLE1 -> `null`

### Example Response

```json
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 9301,
      "tag_type": 3,
      "name": "Backend Python Engineer",
      "parent": {
        "id": 510,
        "tag_type": 2,
        "name": "Backend Engineer",
        "parent": {
          "id": 42,
          "tag_type": 1,
          "name": "Software Engineering",
          "parent": null
        }
      }
    },
    {
      "id": 510,
      "tag_type": 2,
      "name": "Backend Engineer",
      "parent": {
        "id": 42,
        "tag_type": 1,
        "name": "Software Engineering",
        "parent": null
      }
    }
  ]
}
```

## Notes

- Tag hierarchy is represented via `parent`; children are not included in this endpoint response.
- Use `/api/tags/` to discover taxonomy IDs, then apply them in `/api/jobs/` filters (`tag_id`, `role1_id`, `role2_id`, `role3_id`).
- For best performance in job queries, only request `tags=true` when you need nested tag output.