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

# Public API: read campaign and user statistics from your frontend

> Generate a Public token to read campaign and user statistics directly from your frontend with read-only GET endpoints.

Use the Public API to read campaign and user statistics directly from your frontend. It uses a separate **Public token** that you can generate in the dashboard.

## Generate and manage your Public token

<Steps>
  <Step title="Go to Settings">
    Go to **Settings → Public API**.
  </Step>

  <Step title="Generate a token">
    If no token exists, select **Generate token**.

    <Frame>
      <img src="https://mintcdn.com/claimr/XRiO9IZ9z1Cg9XR7/images/api-guide/public-api-generate-token.png?fit=max&auto=format&n=XRiO9IZ9z1Cg9XR7&q=85&s=034361269ded77003ce3396c067dbc45" alt="Generate a Public API token" width="2870" height="396" data-path="images/api-guide/public-api-generate-token.png" />
    </Frame>
  </Step>

  <Step title="Copy the token">
    Copy the value shown under **Public token** and use it in your requests.
  </Step>

  <Step title="Revoke if needed">
    To immediately invalidate the token, select **Revoke token**. You can generate a new token at any time.

    <Frame>
      <img src="https://mintcdn.com/claimr/XRiO9IZ9z1Cg9XR7/images/api-guide/public-api-revoke-token.png?fit=max&auto=format&n=XRiO9IZ9z1Cg9XR7&q=85&s=69d10781e4523d1de4eb4080eeed6074" alt="Revoke a Public API token" width="2854" height="528" data-path="images/api-guide/public-api-revoke-token.png" />
    </Frame>
  </Step>
</Steps>

The Public token only allows read access to the endpoints listed below. It cannot modify data.

### Authentication and request format

All Public API endpoints are **GET** requests. Provide the token and context using query parameters:

* `pid` — Campaign ID (string or number).
* `account` — A unique identifier for the user within your system (for example, user ID or email hash).
* `platform` — A short name representing your organization or platform.
* `pub` — Your Public token.

<Note>
  Base URL: use your assigned environment base (for example, `https://{base}/public/api/...`). Paths below are shown without host for clarity.
</Note>

## API methods

### GET /public/api/user

Get basic user info and stats for an account in a campaign.

Example request:

```json theme={"dark"}
{
  "pid": "string",
  "account": "string",
  "platform": "string",
  "pub": "string"
}
```

Field explanations:

* `pid`: The campaign ID.
* `account`: The user's ID.
* `platform`: The user's platform.
* `pub`: Your Public token.

Example response:

```json theme={"dark"}
{
  "id": "string",
  "name": "string",
  "ref_id": "string",
  "ref_xp": 0,
  "ugc_xp": 0,
  "xp": 0,
  "xp_mul": 0,
  "rank": 0
}
```

### GET /public/api/user/refs

Get user info plus the user's referrals.

Example request:

```json theme={"dark"}
{
  "pid": "string",
  "account": "string",
  "platform": "string",
  "pub": "string"
}
```

Field explanations:

* `pid`: The campaign ID.
* `account`: The user's ID.
* `platform`: The user's platform.
* `pub`: Your Public token.

Example response:

```json theme={"dark"}
{
  "id": "string",
  "name": "string",
  "ref_id": "string",
  "ref_xp": 0,
  "ugc_xp": 0,
  "xp": 0,
  "xp_mul": 0,
  "rank": 0,
  "referrals": [
    {
      "id": "string",
      "name": "string",
      "valid": true,
      "ref_xp": 0,
      "xp": 0,
      "cts": "2024-01-01T00:00:00Z"
    }
  ]
}
```

### GET /public/api/entries/count

Get the number of entries for the provided context.

Example request:

```json theme={"dark"}
{
  "pid": "string",
  "platform": "string",
  "pub": "string"
}
```

Field explanations:

* `pid`: The campaign ID.
* `platform`: The user's platform.
* `pub`: Your Public token.

Example response:

```json theme={"dark"}
{ "count": 0 }
```

### GET /public/api/campaign/stats

Get aggregated statistics for a campaign.

Example request:

```json theme={"dark"}
{
  "pid": "string",
  "platform": "string",
  "pub": "string"
}
```

Field explanations:

* `pid`: The campaign ID.
* `platform`: The user's platform.
* `pub`: Your Public token.

Example response:

```json theme={"dark"}
{
  "participants": 0,
  "tasks_completed": 0,
  "quests_completed": 0,
  "xp": 0
}
```

### Security notes

* The Public token is safe to use on the frontend for the endpoints listed here, but treat it as a secret for your organization. Rotate it by using **Revoke token** and **Generate token** if it is exposed.
* Do not use the Public API for any sensitive queries. Use the server-side API for those cases.

## Troubleshooting

* **401/403**: Verify `pub` is present and correct. If you revoked the token, generate a new one and update your site.
* **429**: Reduce frequency of calls or cache responses on the client.
* **CORS**: Ensure you are calling the correct base domain for your environment.

For troubleshooting or support, contact claimr support at [yo@claimr.io](mailto:yo@claimr.io).