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

# Badges API

> List, view, create, update and delete content and user badges in your Zapnito community through the API.

Manage the badges in your community. Each badge is for either content or users. To give a badge to a piece of content or a user, see [Badge assignments](/api/v1/badge-assignments).

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

## List badges

Return the badges in your community.

<ParamField query="page" type="integer">
  The page of results to return.
</ParamField>

<ParamField query="per_page" type="integer" default={20}>
  The number of results to return per page.
</ParamField>

<ParamField query="query" type="string">
  A search term to reduce the number of results. Matches the badge text.
</ParamField>

<ParamField query="type" type="string">
  Only return badges of this type. Accepts `Content` or `User`.
</ParamField>

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

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

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "badges": [
      {
        "id": 1,
        "type": "Content",
        "text": "Audit ready",
        "color": "#88FED8",
        "text_color": "#18181B",
        "cta_label": "Read the audit checklist",
        "cta_url": "https://example.com/audit-checklist",
        "available_to_anyone": false,
        "position": 0,
        "brand_image_url": "https://example.com/audit-ready-image.png",
        "brand_logo_url": "https://example.com/audit-ready-logo.png"
      },
      {
        "id": 2,
        "type": "User",
        "text": "Compliance expert",
        "color": "#A28BFE",
        "text_color": "#18181B",
        "cta_label": "Meet our experts",
        "cta_url": "https://example.com/our-experts",
        "available_to_anyone": false,
        "position": 0,
        "brand_image_url": "https://example.com/compliance-expert-image.png",
        "brand_logo_url": "https://example.com/compliance-expert-logo.png"
      }
    ]
  }
  ```
</ResponseExample>

## Get a badge

Return a single badge.

<ParamField path="id" type="string" required>
  The ID of the badge.
</ParamField>

```bash title="Get a badge" theme={null}
curl "https://your-community.zapnito.com/api/v1/badges/1" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8"
```

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

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "badge": {
      "id": 1,
      "type": "Content",
      "text": "Audit ready",
      "color": "#88FED8",
      "text_color": "#18181B",
      "cta_label": "Read the audit checklist",
      "cta_url": "https://example.com/audit-checklist",
      "available_to_anyone": false,
      "position": 0,
      "brand_image_url": "https://example.com/audit-ready-image.png",
      "brand_logo_url": "https://example.com/audit-ready-logo.png"
    }
  }
  ```
</ResponseExample>

## Create a badge

Create a new badge.

<ParamField body="badge.type" type="string">
  The type of record the badge is for. Accepts `Content` or `User`.
</ParamField>

<ParamField body="badge.text" type="string" required>
  The text displayed on the badge.
</ParamField>

<ParamField body="badge.color" type="string" required>
  The hex code for the badge colour.
</ParamField>

<ParamField body="badge.text_color" type="string" required>
  The hex code for the text colour.
</ParamField>

<ParamField body="badge.cta_label" type="string">
  The text displayed for the call to action.
</ParamField>

<ParamField body="badge.cta_url" type="string">
  The URL the call to action links to.
</ParamField>

<ParamField body="badge.position" type="integer">
  The position of the badge in badge lists. Defaults to the end of the list.
</ParamField>

<ParamField body="badge.remote_brand_image_url" type="string">
  The URL of the brand image. Note the `remote_` prefix.
</ParamField>

<ParamField body="badge.remote_brand_logo_url" type="string">
  The URL of the brand logo. Note the `remote_` prefix.
</ParamField>

```bash title="Create a badge" theme={null}
curl -X POST "https://your-community.zapnito.com/api/v1/badges" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "badge": {
      "type": "Content",
      "text": "Expert reviewed",
      "color": "#88FED8",
      "text_color": "#18181B",
      "cta_label": "Meet the reviewers",
      "cta_url": "https://example.com/expert-reviewers"
    }
  }'
```

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

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "badge": {
      "id": 3,
      "type": "Content",
      "text": "Expert reviewed",
      "color": "#88FED8",
      "text_color": "#18181B",
      "cta_label": "Meet the reviewers",
      "cta_url": "https://example.com/expert-reviewers",
      "available_to_anyone": false,
      "position": 0,
      "brand_image_url": "https://example.com/expert-reviewed-image.png",
      "brand_logo_url": "https://example.com/expert-reviewed-logo.png"
    }
  }
  ```
</ResponseExample>

## Update a badge

Update an existing badge. Send only the attributes you want to change.

<ParamField path="id" type="string" required>
  The ID of the badge.
</ParamField>

<ParamField body="badge.type" type="string">
  The type of record the badge is for. Accepts `Content` or `User`.
</ParamField>

<ParamField body="badge.text" type="string">
  The text displayed on the badge.
</ParamField>

<ParamField body="badge.color" type="string">
  The hex code for the badge colour.
</ParamField>

<ParamField body="badge.text_color" type="string">
  The hex code for the text colour.
</ParamField>

<ParamField body="badge.cta_label" type="string">
  The text displayed for the call to action.
</ParamField>

<ParamField body="badge.cta_url" type="string">
  The URL the call to action links to.
</ParamField>

<ParamField body="badge.position" type="integer">
  The position of the badge in badge lists.
</ParamField>

<ParamField body="badge.remote_brand_image_url" type="string">
  The URL of the brand image. Note the `remote_` prefix.
</ParamField>

<ParamField body="badge.remote_brand_logo_url" type="string">
  The URL of the brand logo. Note the `remote_` prefix.
</ParamField>

```bash title="Update a badge" theme={null}
curl -X PUT "https://your-community.zapnito.com/api/v1/badges/3" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"badge": {"text": "Expert verified", "cta_label": "Meet the reviewers"}}'
```

`PUT https://your-community.zapnito.com/api/v1/badges/:id`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "badge": {
      "id": 3,
      "type": "Content",
      "text": "Expert verified",
      "color": "#88FED8",
      "text_color": "#18181B",
      "cta_label": "Meet the reviewers",
      "cta_url": "https://example.com/expert-reviewers",
      "available_to_anyone": false,
      "position": 0,
      "brand_image_url": "https://example.com/expert-reviewed-image.png",
      "brand_logo_url": "https://example.com/expert-reviewed-logo.png"
    }
  }
  ```
</ResponseExample>

## Delete a badge

Delete a badge.

<ParamField path="id" type="string" required>
  The ID of the badge.
</ParamField>

```bash title="Delete a badge" theme={null}
curl -X DELETE "https://your-community.zapnito.com/api/v1/badges/1" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8"
```

`DELETE https://your-community.zapnito.com/api/v1/badges/:id`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "Badge #1 deleted"
  }
  ```
</ResponseExample>


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