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

# Third-party resources API

> Link resources held in your external systems to your Zapnito community: list, create, update and delete them through the API.

Manage resources that live in your own systems and appear in your community. Each resource has a `third_party_ref`, which is its ID in your external system.

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

## List resources

Return the third-party resources in your community.

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

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

<ParamField query="query" type="string">
  A search term to reduce the number of results. Matches title or `third_party_ref`.
</ParamField>

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

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

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "third_party_resources": [
      {
        "id": 1,
        "third_party_ref": "1",
        "title": "Audit readiness toolkit",
        "description": "Templates and checklists for preparing for an audit.",
        "canonical_url": "https://docs.example.com/audit-readiness-toolkit",
        "thumbnail_url": "https://docs.example.com/audit-readiness-toolkit.png",
        "open_in_new_tab": true,
        "category": "Toolkits",
        "tags": ["Audit"]
      },
      {
        "id": 2,
        "third_party_ref": "ABC123",
        "title": "Data protection guide",
        "description": "A plain-English guide to handling personal data.",
        "canonical_url": "https://docs.example.com/data-protection-guide",
        "thumbnail_url": "https://docs.example.com/data-protection-guide.png",
        "open_in_new_tab": true,
        "category": "Guides",
        "tags": ["Compliance"]
      }
    ]
  }
  ```
</ResponseExample>

## Get a resource

Return a single resource by its ID in your external system.

<ParamField path="third_party_ref" type="string" required>
  The ID of the resource in your external system.
</ParamField>

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

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

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "third_party_resource": {
      "id": 5,
      "third_party_ref": "ABC123",
      "title": "Data protection guide",
      "description": "A plain-English guide to handling personal data.",
      "canonical_url": "https://docs.example.com/data-protection-guide",
      "thumbnail_url": "https://docs.example.com/data-protection-guide.png",
      "open_in_new_tab": false,
      "category": "Guides",
      "tags": ["Compliance"]
    }
  }
  ```
</ResponseExample>

* `200 OK`: the resource was returned.
* `404 Not Found`: no resource matches the ID. The message reads `Resource not found for ID: 1`.

## Create a resource

Create a new resource. Tags aren't created for you, so any tags you assign must already exist. You can [create tags](/api/v1/tags#create-a-tag) first.

<ParamField body="third_party_resource.third_party_ref" type="string">
  The ID of the resource in your external system.
</ParamField>

<ParamField body="third_party_resource.title" type="string" required>
  The title of the resource.
</ParamField>

<ParamField body="third_party_resource.description" type="string">
  The description, about text or body of the resource.
</ParamField>

<ParamField body="third_party_resource.canonical_url" type="string" required>
  The URL of the external resource.
</ParamField>

<ParamField body="third_party_resource.thumbnail_url" type="string">
  The URL of the resource's thumbnail.
</ParamField>

<ParamField body="third_party_resource.category_name" type="string" required>
  The category the resource belongs to.
</ParamField>

<ParamField body="third_party_resource.open_in_new_tab" type="boolean" default={false}>
  Whether the canonical URL opens in a new tab.
</ParamField>

<ParamField body="third_party_resource.published_at" type="string">
  The date and time the resource was published. ISO 8601 format is best for accuracy.
</ParamField>

<ParamField body="third_party_resource.tags" type="string[]" required>
  The names of the tags to assign to the resource.
</ParamField>

```bash title="Create a resource" theme={null}
curl -X POST "https://your-community.zapnito.com/api/v1/third_party_resources" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "third_party_resource": {
      "third_party_ref": "ABC123",
      "title": "Data protection guide",
      "description": "A plain-English guide to handling personal data.",
      "canonical_url": "https://docs.example.com/data-protection-guide",
      "thumbnail_url": "https://docs.example.com/data-protection-guide.png",
      "category_name": "Guides",
      "open_in_new_tab": true,
      "published_at": "2026-03-04T09:25:00",
      "tags": ["Compliance"]
    }
  }'
```

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

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "third_party_resource": {
      "id": 1,
      "third_party_ref": "ABC123",
      "title": "Data protection guide",
      "description": "A plain-English guide to handling personal data.",
      "canonical_url": "https://docs.example.com/data-protection-guide",
      "thumbnail_url": "https://docs.example.com/data-protection-guide.png",
      "open_in_new_tab": false,
      "category": "Guides",
      "tags": ["Compliance"]
    }
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "errors": {
      "title": ["can't be blank"]
    }
  }
  ```
</ResponseExample>

* `200 OK`: the resource was created.
* `422 Unprocessable Entity`: a required parameter is missing.

## Update a resource

Update an existing resource. Send only the attributes you want to change. As when you create a resource, any tags you assign must already exist.

<ParamField path="third_party_ref" type="string" required>
  The ID of the resource in your external system.
</ParamField>

<ParamField body="third_party_resource.third_party_ref" type="string">
  The ID of the resource in your external system.
</ParamField>

<ParamField body="third_party_resource.title" type="string">
  The title of the resource.
</ParamField>

<ParamField body="third_party_resource.description" type="string">
  The description, about text or body of the resource.
</ParamField>

<ParamField body="third_party_resource.canonical_url" type="string">
  The URL of the external resource.
</ParamField>

<ParamField body="third_party_resource.thumbnail_url" type="string">
  The URL of the resource's thumbnail.
</ParamField>

<ParamField body="third_party_resource.category_name" type="string">
  The category the resource belongs to.
</ParamField>

<ParamField body="third_party_resource.open_in_new_tab" type="boolean" default={false}>
  Whether the canonical URL opens in a new tab.
</ParamField>

<ParamField body="third_party_resource.published_at" type="string">
  The date and time the resource was published. ISO 8601 format is best for accuracy.
</ParamField>

<ParamField body="third_party_resource.tags" type="string[]">
  The names of the tags to assign to the resource.
</ParamField>

```bash title="Update a resource" theme={null}
curl -X PUT "https://your-community.zapnito.com/api/v1/third_party_resources/ABC123" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "third_party_resource": {
      "title": "Data protection guide",
      "description": "A plain-English guide to handling personal data.",
      "canonical_url": "https://docs.example.com/data-protection-guide",
      "category_name": "Guides",
      "open_in_new_tab": true,
      "tags": ["Compliance"]
    }
  }'
```

`PUT https://your-community.zapnito.com/api/v1/third_party_resources/:third_party_ref`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "third_party_resource": {
      "id": 1,
      "third_party_ref": "ABC123",
      "title": "Data protection guide",
      "description": "A plain-English guide to handling personal data.",
      "canonical_url": "https://docs.example.com/data-protection-guide",
      "thumbnail_url": "https://docs.example.com/data-protection-guide.png",
      "open_in_new_tab": false,
      "category": "Guides",
      "tags": ["Compliance"]
    }
  }
  ```

  ```json 422 Unprocessable Entity theme={null}
  {
    "errors": {
      "title": ["can't be blank"]
    }
  }
  ```
</ResponseExample>

* `200 OK`: the resource was updated.
* `422 Unprocessable Entity`: a required parameter is missing.

## Delete a resource

Delete a resource.

<ParamField path="third_party_ref" type="string" required>
  The ID of the resource in your external system.
</ParamField>

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

`DELETE https://your-community.zapnito.com/api/v1/third_party_resources/:third_party_ref`

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "Resource ABC123 deleted"
  }
  ```
</ResponseExample>

* `200 OK`: the resource was deleted.
* `404 Not Found`: no resource matches the ID. The message reads `Resource not found for ID: 1`.


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