> For the complete documentation index, see [llms.txt](https://docs.claimr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claimr.io/api/public-api.md).
# Public API
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
1. Go to **Settings → Public API**.
2. If no token exists, select **Generate token**.
3. Copy the value shown under **Public token** and use it in your requests.
4. To immediately invalidate the token, select **Revoke token**. You can generate a new token at any time.
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.
> Base URL: use your assigned environment base (for example, `https://{base}/public/api/...`). Paths below are shown without host for clarity.
## API methods
### GET /public/api/user
Get basic user info and stats for an account in a campaign.
Example request:
```json
{
"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
{
"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
{
"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
{
"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
{
"pid": "string",
"platform": "string",
"pub": "string"
}
```
Field explanations:
`pid`: The campaign ID.
`platform`: The user’s platform.
`pub`: Your Public token.
Example response:
```
{ "count": 0 }
```
### GET /public/api/campaign/stats
Get aggregated statistics for a campaign.
Example request:
```json
{
"pid": "string",
"platform": "string",
"pub": "string"
}
```
Field explanations:
pid: The campaign ID.
platform: The user’s platform.
pub: Your Public token.
Example response:
```json
{
"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).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.claimr.io/api/public-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.