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

# Tags API

> Find and create tags in your Zapnito community through the API, so you can organise and assign content.

Find and create tags. To assign content to a tag, see [Tag content](/api/v1/tag-contents).

Before you start, read the [API overview](/api/v1/overview) for how authentication, headers, pagination and errors work.

## Create a tag

Create a new tag, optionally under a parent tag.

<ParamField body="tag.name" type="string" required>
  The name of the tag.
</ParamField>

<ParamField body="tag.parent_name" type="string">
  The name of the parent tag. The parent tag must already exist.
</ParamField>

<ParamField body="tag.external_id" type="string">
  An external unique ID for the tag.
</ParamField>

<ParamField body="tag.external_url" type="string">
  The URL that the tag links to.
</ParamField>

```bash title="Create a tag" theme={null}
curl -X POST "https://your-community.zapnito.com/api/v1/tags" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "tag": {
      "name": "Compliance",
      "external_url": "https://example.com/regulation/compliance",
      "external_id": "1221",
      "parent_name": "Regulation"
    }
  }'
```

`POST https://your-community.zapnito.com/api/v1/tags`

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "tag": {
      "name": "Compliance",
      "external_url": "https://example.com/regulation/compliance",
      "external_id": "1221",
      "parent_name": "Regulation"
    }
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "errors": {
      "message": "Tag named Compliance was not created because no parent tag already exists with name: Regulation"
    }
  }
  ```
</ResponseExample>

* `201 Created`: the tag was created.
* `422 Unprocessable Entity`: the tag wasn't created. Either no parent tag matches `parent_name`, or a tag with that name already exists. In the second case the response is `{"errors": {"name": "has already been taken"}}`.

## List tags

Return the existing tags.

<ParamField query="parent_name" type="string">
  Only return tags with this parent tag name.
</ParamField>

```bash title="List tags" theme={null}
curl "https://your-community.zapnito.com/api/v1/tags?parent_name=Regulation" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8"
```

`GET https://your-community.zapnito.com/api/v1/tags`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "tags": [
      { "name": "Compliance", "external_url": "https://example.com/regulation/compliance", "external_id": "", "parent_name": "Regulation" },
      { "name": "Licensing", "external_url": "", "external_id": "", "parent_name": "Regulation" },
      { "name": "Reporting", "external_url": "", "external_id": "", "parent_name": "Regulation" },
      { "name": "Audit", "external_url": "", "external_id": "", "parent_name": "Regulation" }
    ]
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.