> ## 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 List API

> Retrieve the list of organization tags available for tagging invoices, vendors, and line items

## Authentication

All requests require an API key in the request headers.

**Headers:**

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

This endpoint takes no query, path, or body parameters.

## Code Examples

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

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/tags', {
    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"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  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 list response data                                                                                                                       |
| `data.tags`               | array   | List of tags configured for the organization                                                                                                              |
| `data.tags[].id`          | string  | Unique slug identifier for the tag (use this as `tagId` in the [Tag Detail API](/apis/tag-detail) and [Tag Value Creation API](/apis/tag-value-creation)) |
| `data.tags[].name`        | string  | Display name of the tag                                                                                                                                   |
| `data.tags[].description` | string  | Description of the tag                                                                                                                                    |
| `data.tags[].dataType`    | string  | Data type of the tag (e.g., `DROPDOWN`, `VARCHAR`, `NUMBER`, `NUMERIC`, `DATETIME`)                                                                       |
| `data.context`            | object  | Response metadata                                                                                                                                         |
| `data.context.count`      | number  | Total number of tags returned                                                                                                                             |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "tags": [
      {
        "id": "cost-center",
        "name": "Cost Center",
        "description": "Cost center the expense belongs to",
        "dataType": "DROPDOWN"
      },
      {
        "id": "project",
        "name": "Project",
        "description": "Project reference",
        "dataType": "VARCHAR"
      },
      {
        "id": "invoice-received-on",
        "name": "Invoice Received On",
        "description": "Date the invoice was received",
        "dataType": "DATETIME"
      }
    ],
    "context": {
      "count": 3
    }
  }
}
```

## Error Responses

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

* Use the `id` (slug) returned for a tag as the `tagId` path parameter in the [Tag Detail API](/apis/tag-detail) to retrieve the available values for a `DROPDOWN` tag
* Check `dataType` to understand how a tag is used — only `DROPDOWN` tags carry a fixed list of selectable values
* Tags are organization-scoped — only tags configured under your organization are returned
* Access is limited to users with tag read permission and an admin or bookkeeper role