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.

1. Copy the value shown under Public token and use it in your requests.

2. 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "pid": "string",
  "platform": "string",
  "pub": "string"
}

Field explanations:

pid: The campaign ID.

platform: The user’s platform.

pub: Your Public token.

Example response:

{
  "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 [e-mail].