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

# Tag Detail API

> Retrieve the list of values configured under a specific dropdown tag

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
```

## Request

### Path Parameters

| Parameter | Type   | Required | Description                                                                                                                         |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `tagId`   | string | Yes      | The unique slug identifier of the dropdown tag whose values are to be fetched. Obtain this from the [Tag List API](/apis/tag-list). |

### Query Parameters

| Parameter | Type   | Required | Description                                      |
| --------- | ------ | -------- | ------------------------------------------------ |
| `value`   | string | No       | Filter tag values by value text (partial match). |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.pazy.io/v1.0/tags/cost-center/values?value=Eng" \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const params = new URLSearchParams({ value: 'Eng' });
  const response = await fetch(`https://api.pazy.io/v1.0/tags/cost-center/values?${params}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY'
    }
  });

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/tags/cost-center/values"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }
  params = { "value": "Eng" }

  response = requests.get(url, headers=headers, params=params)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                | Type    | Description                                                                                                                              |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `ok`                 | boolean | Indicates whether the request was successful                                                                                             |
| `data`               | object  | Contains the tag values response data                                                                                                    |
| `data.tags`          | array   | List of values configured for the tag                                                                                                    |
| `data.tags[].id`     | number  | Unique identifier for the tag value (use this as `tagId` in the [Invoice List API](/apis/invoice-list) to filter invoices by this value) |
| `data.tags[].value`  | string  | The tag value text                                                                                                                       |
| `data.tags[].status` | string  | State of the tag value (e.g., `ENABLED`, `DISABLED`)                                                                                     |
| `data.context`       | object  | Response metadata                                                                                                                        |
| `data.context.count` | number  | Total number of tag values returned                                                                                                      |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "tags": [
      {
        "id": 1024,
        "value": "Engineering",
        "status": "ENABLED"
      },
      {
        "id": 1025,
        "value": "Marketing",
        "status": "ENABLED"
      },
      {
        "id": 1026,
        "value": "Legacy Ops",
        "status": "DISABLED"
      }
    ],
    "context": {
      "count": 3
    }
  }
}
```

## Error Responses

### Tag Not Found

Returned when the tag does not exist or is not a dropdown tag.

**HTTP Status:** `404 Not Found`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "TAG_NOT_FOUND",
    "message": "Dropdown tag not found."
  }
}
```

### Access Denied

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied: Only admin and bookkeeper can view this resources"
  }
}
```

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

### Internal Error

**HTTP Status:** `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}
```

## Best Practices

* This endpoint returns values only for `DROPDOWN` tags; requesting values for a non-dropdown tag returns a `TAG_NOT_FOUND` error
* Use the `id` from a tag value as the `tagId` parameter in the [Invoice List API](/apis/invoice-list) to filter invoices that carry this tag value
* The `status` field indicates whether the value is currently usable — `DISABLED` values are returned for historical reference but should not be used on new transactions
* Use `value` to narrow down results — partial matching is supported (e.g., `Eng` matches `Engineering`)
* Add new values to a dropdown tag with the [Tag Value Creation API](/apis/tag-value-creation)