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

# API Reference

> Complete reference for Nudj Platform APIs

The Nudj Platform exposes three JSON-over-HTTPS APIs for building gamification experiences, managing communities, and analysing engagement data. Every endpoint lives under your organisation's subdomain and accepts either `Authorization: Bearer` or `x-api-token` for authentication — see [Authentication](/api-reference/authentication) for the full matrix.

## Available APIs

<CardGroup cols={3}>
  <Card title="Integration API" icon="plug" href="/api-reference/integration/get-me">
    User-scoped operations — challenges, rewards, achievements, and profile data for logged-in members
  </Card>

  <Card title="Admin API" icon="shield" href="/api-reference/admin/get-communities">
    Administrative operations for platform configuration, content management, and RBAC
  </Card>

  <Card title="Analytics API" icon="chart-line" href="/api-reference/analytics/get-users-overview">
    Reporting endpoints for engagement metrics, leaderboards, and challenge performance
  </Card>
</CardGroup>

## Base URL

Every request is scoped to your organisation's subdomain:

```
https://{your-subdomain}.nudj.cx/api/v2/{api-type}/{endpoint}
```

* **`{your-subdomain}`** is assigned when your organisation is provisioned (e.g. `acme-corp`). White-label custom domains are configurable via the Admin API's `/domains` endpoints — see [Custom Domains](/api-reference/custom-domains).
* **`{api-type}`** is one of `integration`, `admin`, or `analytics`.
* All requests must hit the subdomain that matches the token — cross-tenant token reuse is rejected at the auth middleware.

## Making Your First Request

The example below uses `Authorization: Bearer` (recommended for new integrations). The legacy `x-api-token` header is also accepted everywhere — the runtime strips the `Bearer ` prefix automatically if present.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Replace '{subdomain}' with your organisation's subdomain
  const response = await fetch('https://{subdomain}.nudj.cx/api/v2/integration/challenges', {
    headers: {
      'Authorization': `Bearer ${process.env.NUDJ_API_TOKEN}`,
      'Content-Type': 'application/json'
    }
  });

  const challenges = await response.json();
  console.log(challenges);
  ```

  ```python Python theme={null}
  import os
  import requests

  # Replace '{subdomain}' with your organisation's subdomain
  API_TOKEN = os.environ['NUDJ_API_TOKEN']
  response = requests.get(
      'https://{subdomain}.nudj.cx/api/v2/integration/challenges',
      headers={
          'Authorization': f'Bearer {API_TOKEN}',
          'Content-Type': 'application/json'
      }
  )

  challenges = response.json()
  print(challenges)
  ```

  ```bash cURL theme={null}
  # Replace '{subdomain}' with your organisation's subdomain
  curl -X GET https://{subdomain}.nudj.cx/api/v2/integration/challenges \
    -H "Authorization: Bearer ${NUDJ_API_TOKEN}" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Bearer tokens, legacy `x-api-token`, per-API auth matrix, and best practices
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    The tRPC error envelope and common status codes
  </Card>

  <Card title="Pagination" icon="list-ol" href="/api-reference/pagination">
    The `limit` / `skip` contract and `totalCount` + `edges` response shape
  </Card>

  <Card title="Custom Domains" icon="globe" href="/api-reference/custom-domains">
    Domain patterns, white-label URLs, and how tokens are scoped to hosts
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Outbound events, signing, retries, and idempotency
  </Card>

  <Card title="Internationalization" icon="language" href="/api-reference/internationalization">
    The `x-language` header and translated response bodies
  </Card>
</CardGroup>