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

# Integration API Overview

> User-facing API for community engagement, challenge participation, and reward redemption

## Overview

The Integration API powers your user-facing applications, providing secure access to challenges, rewards, achievements, and community features. Built for mobile apps, web frontends, and third-party integrations, it enables users to engage with your gamified community while maintaining data security and user privacy.

## Base URL

```bash theme={null}
https://{subdomain}.nudj.cx/api/v2/integration
```

> [!NOTE]
>
> Replace `{subdomain}` with your organization's subdomain (e.g., `acme-corp.nudj.cx`).

## Authentication

```bash theme={null}
x-api-token: YOUR_INTEGRATION_TOKEN
```

> [!NOTE]
>
> Integration tokens are scoped to specific organizations and provide user-level access. Each request operates within the context of the authenticated user. See the [Authentication guide](https://docs.nudj.cx/api-reference/authentication.md) for token management.

## Core Capabilities

> **Challenge Participation**
>
> Join challenges, complete actions, track progress

> **Reward System**
>
> Browse catalog, purchase with points, redeem prizes

> **Social Features**
>
> Create posts, comment, like, follow community activity

> **Achievement Tracking**
>
> Unlock achievements, claim badges, view progress

> **Leaderboard Competition**
>
> View rankings, track position, compete with others

> **Profile Management**
>
> Update profile, view stats, manage preferences

## User Experience Areas

## 🎮 Challenge & Action System

Complete actions within challenges to earn points, XP, and rewards.

> **Challenges**
>
> **User challenge lifecycle**
>
> * Browse available challenges
> * View challenge details and requirements
> * Start/unlock challenges
> * Track progress through actions
> * Complete challenges for rewards
>
> **Key Endpoints:**
>
> * `GET /challenges` - List available challenges
> * `GET /challenges/{id}` - Challenge details
> * `POST /challenges/{id}/start` - Begin challenge
> * `POST /challenges/{id}/complete` - Submit completion
> * `POST /challenges/{id}/unlock` - Unlock restricted challenges
>
> ```typescript theme={null}
> // Start a challenge
> await integration.challenges.start({
>   challengeId: "challenge_123"
> });
> ```

> **Actions**
>
> **Action participation system**
>
> * View action requirements
> * Submit action responses
> * Track completion status
> * Earn immediate rewards
>
> **Action Types:**
>
> * Social media actions (follow, share, post)
> * Content engagement (read, watch, interact)
> * Community participation (post, comment, like)
> * External activities (surveys, links)
> * Custom actions
>
> **Key Endpoints:**
>
> * `GET /actions` - List all actions
> * `GET /actions/{id}` - Action details
> * `POST /action-participations` - Submit action completion
> * `GET /action-participations` - View your participations

> **Challenge Groups**
>
> **Organized challenge collections**
>
> * Browse challenge categories
> * View group progress
> * Access themed challenges
> * Track group achievements
>
> **Key Endpoints:**
>
> * `GET /challenge-groups` - List groups
> * `GET /challenge-groups/{id}` - Group details with challenges

## 🏆 Rewards & Incentives

Earn and redeem rewards through participation and achievements.

> **Reward Catalog**
>
> **Browse and acquire rewards**
>
> * View available rewards
> * Check point requirements
> * Purchase with points
> * View reward details
>
> **Key Endpoints:**
>
> * `GET /rewards` - Browse catalog
> * `GET /rewards/{id}` - Reward details
> * `POST /rewards/{id}/purchase` - Buy with points
>
> ```typescript theme={null}
> // Purchase a reward
> await integration.rewards.purchase({
>   rewardId: "reward_456",
>   quantity: 1
> });
> ```

> **My Rewards**
>
> **Personal reward management**
>
> * View owned rewards (assets)
> * Check giveaway entries
> * Redeem reward codes
> * Track reward history
>
> **Key Endpoints:**
>
> * `GET /me/rewards` - Your reward assets
> * `GET /me/rewards/{assetId}` - Asset details
> * `POST /me/rewards/{assetId}/redeem` - Redeem reward
> * `GET /me/reward-entries` - Giveaway entries
> * `POST /me/reward-entries/{id}/check` - Check entry status

## 🎖️ Achievements & Progress

Track milestones and unlock achievements through engagement.

> **Achievements**
>
> **Milestone tracking system**
>
> * View all achievements
> * Track progress toward unlocking
> * Claim unlocked achievements
> * Earn badges and rewards
>
> **Key Endpoints:**
>
> * `GET /achievements` - List all achievements
> * `GET /achievements/{id}` - Achievement details
> * `POST /achievements/{id}/claim` - Claim unlocked achievement
>
> ```typescript theme={null}
> // Claim an achievement
> await integration.achievements.claim({
>   achievementId: "achievement_789"
> });
> ```

> **Badges & Streaks**
>
> **Recognition systems**
>
> * View earned badges
> * Track active streaks
> * Monitor consistency bonuses
>
> **Key Endpoints:**
>
> * `GET /me/badges` - Your badges
> * `GET /me/streaks` - Active streaks

## 📊 Leaderboards & Competition

Compete with other community members for top positions.

> **Leaderboard Rankings**
>
> **Competitive standings**
>
> * View multiple leaderboard types
> * Check current rankings
> * Track your position
> * See nearby competitors
>
> **Key Endpoints:**
>
> * `GET /leaderboards/configs` - Available leaderboards
> * `GET /leaderboards/{id}/data` - Full rankings
> * `GET /leaderboards/{id}/position` - Your position
>
> ```typescript theme={null}
> // Get your leaderboard position
> const position = await integration.leaderboards.getPosition({
>   configId: "weekly_points"
> });
> ```

## 💬 Social & Community

Engage with the community through posts, comments, and interactions.

> **Posts & Content**
>
> **Community content interaction**
>
> * View community posts
> * Like and react to content
> * Create comments
> * Share thoughts
>
> **Key Endpoints:**
>
> * `GET /posts` - List posts
> * `GET /posts/{id}` - Post details
> * `POST /posts/{id}/like` - Like a post
> * `DELETE /posts/{id}/like` - Unlike
> * `GET /posts/{id}/comments` - View comments
> * `POST /posts/{id}/comments` - Add comment

> **Comments**
>
> **Discussion participation**
>
> * Create new comments
> * Edit your comments
> * Reply to others
> * Engage in discussions
>
> **Key Endpoints:**
>
> * `POST /comments` - Create comment
> * `PUT /comments/{id}` - Edit comment
> * `PUT /posts/{postId}/comments/{commentId}` - Update post comment

> **Community Info**
>
> **Community details and settings**
>
> * View community information
> * Check active campaigns
> * See community themes
> * Access community links
>
> **Key Endpoints:**
>
> * `GET /communities` - List communities
> * `GET /communities/{identifier}` - Community details
> * `GET /campaigns` - Active campaigns

## 👤 User Profile

Manage your profile and track personal progress.

> **Profile Management**
>
> **Personal information and settings**
>
> * View profile details
> * Update information
> * Manage preferences
> * Track statistics
>
> **Key Endpoints:**
>
> * `GET /me` - Your profile
> * `PATCH /me` - Update profile
>
> ```typescript theme={null}
> // Update profile
> await integration.me.update({
>   displayName: "NewUsername",
>   bio: "Updated bio"
> });
> ```

> **Events & Bonuses**
>
> **Special events and bonuses**
>
> * View available events
> * Claim event rewards
> * Track special bonuses
>
> **Key Endpoints:**
>
> * `GET /events` - Available events
> * `POST /events/claim` - Claim event rewards

## API Resource Groups

**Engagement**

| Resource | Operations | Purpose |
| - | - | - |
| **Challenges** | GET, POST (start/complete/unlock) | Challenge participation |
| **Actions** | GET | View available actions |
| **Action Participations** | GET, POST | Submit and track action completions |
| **Challenge Groups** | GET | Browse challenge categories |
| **Achievements** | GET, POST (claim) | Milestone tracking |
| **Events** | GET, POST (claim) | Special events and bonuses |

**Rewards**

| Resource | Operations | Purpose |
| - | - | - |
| **Rewards** | GET, POST (purchase) | Reward catalog and purchasing |
| **Me/Rewards** | GET, POST (redeem) | Personal reward assets |
| **Me/Reward Entries** | GET, POST (check) | Giveaway entries |

**Social**

| Resource | Operations | Purpose |
| - | - | - |
| **Posts** | GET, POST (like), DELETE (like) | Content interaction |
| **Comments** | GET, POST, PUT | Discussion participation |
| **Communities** | GET | Community information |
| **Campaigns** | GET | Active campaigns |

**User**

| Resource | Operations | Purpose |
| - | - | - |
| **Me** | GET, PATCH | Profile management |
| **Me/Badges** | GET | Earned badges |
| **Me/Streaks** | GET | Active streaks |
| **Leaderboards** | GET | Rankings and position |

**Configuration**

| Resource | Operations | Purpose |
| - | - | - |
| **Auth Config** | GET | Authentication settings |
| **Feature Flags** | GET | Enabled features |
| **Languages** | GET | Available languages |
| **Legal Policies** | GET | Terms and privacy |
| **Themes** | GET | UI themes |
| **Third Party Config** | GET | Integration settings |
| **Tags** | GET | Content tags |
| **Variables** | GET, POST | Dynamic values |

## Quick Start Examples

```typescript TypeScript theme={null}
import { createIntegrationClient } from '@nudj-digital/api/integration';

const integration = createIntegrationClient({
  baseUrl: 'https://acme-corp.nudj.cx/api/v2/integration',
  headers: {
    'x-api-token': process.env.NUDJ_INTEGRATION_TOKEN
  }
});

// Get user profile and stats
const profile = await integration.me.get();
console.log(`Points: ${profile.points}, XP: ${profile.xp}`);

// Browse and join a challenge
const challenges = await integration.challenges.list({
  params: { status: 'active' }
});

const challenge = challenges.data[0];
await integration.challenges.start({
  challengeId: challenge.id
});

// Complete an action
await integration.actionParticipations.create({
  actionId: challenge.actions[0].id,
  data: {
    response: "completed"
  }
});

// Check leaderboard position
const position = await integration.leaderboards.getPosition({
  configId: "weekly_points"
});
console.log(`Rank: ${position.rank} with ${position.score} points`);
```

```javascript JavaScript theme={null}
// Get available challenges
const response = await fetch('https://acme-corp.nudj.cx/api/v2/integration/challenges', {
  headers: {
    'x-api-token': 'YOUR_INTEGRATION_TOKEN'
  }
});

const challenges = await response.json();

// Start a challenge
await fetch(`https://acme-corp.nudj.cx/api/v2/integration/challenges/${challengeId}/start`, {
  method: 'POST',
  headers: {
    'x-api-token': 'YOUR_INTEGRATION_TOKEN',
    'Content-Type': 'application/json'
  }
});
```

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

# Setup headers
headers = {
    'x-api-token': 'YOUR_INTEGRATION_TOKEN'
}

# Get user profile
profile = requests.get(
    'https://acme-corp.nudj.cx/api/v2/integration/me',
    headers=headers
).json()

# Browse rewards catalog
rewards = requests.get(
    'https://acme-corp.nudj.cx/api/v2/integration/rewards',
    headers=headers
).json()

# Purchase a reward
purchase = requests.post(
    f'https://acme-corp.nudj.cx/api/v2/integration/rewards/{reward_id}/purchase',
    headers=headers,
    json={'quantity': 1}
)
```

```bash cURL theme={null}
# Get your profile
curl -X GET https://acme-corp.nudj.cx/api/v2/integration/me \
  -H "x-api-token: YOUR_INTEGRATION_TOKEN"

# List available challenges
curl -X GET https://acme-corp.nudj.cx/api/v2/integration/challenges \
  -H "x-api-token: YOUR_INTEGRATION_TOKEN"

# Start a challenge
curl -X POST https://acme-corp.nudj.cx/api/v2/integration/challenges/{challengeId}/start \
  -H "x-api-token: YOUR_INTEGRATION_TOKEN"
```

## Common User Flows

> **New User Onboarding**
>
> 1. Get user profile (`GET /me`)
> 2. View available challenges (`GET /challenges`)
> 3. Start onboarding challenge (`POST /challenges/{id}/start`)
> 4. Complete profile action (`POST /action-participations`)
> 5. Claim welcome achievement (`POST /achievements/{id}/claim`)
> 6. Check initial rewards (`GET /me/rewards`)

> **Daily Engagement**
>
> 1. Check active events (`GET /events`)
> 2. View daily challenges (`GET /challenges?type=daily`)
> 3. Complete daily actions (`POST /action-participations`)
> 4. Check streak status (`GET /me/streaks`)
> 5. View leaderboard position (`GET /leaderboards/{id}/position`)
> 6. Browse and interact with posts (`GET /posts`, `POST /posts/{id}/like`)

> **Reward Redemption**
>
> 1. Browse reward catalog (`GET /rewards`)
> 2. Check point balance (`GET /me`)
> 3. Purchase reward (`POST /rewards/{id}/purchase`)
> 4. View owned rewards (`GET /me/rewards`)
> 5. Redeem reward code (`POST /me/rewards/{assetId}/redeem`)

> **Social Participation**
>
> 1. View community posts (`GET /posts`)
> 2. Like interesting content (`POST /posts/{id}/like`)
> 3. Add comments (`POST /posts/{id}/comments`)
> 4. Complete social actions (`POST /action-participations`)
> 5. Check social achievements (`GET /achievements`)

## Response Format

All Integration API responses follow a consistent structure:

```json theme={null}
{
  "data": {
    "id": "resource_123",
    "type": "challenge",
    "attributes": {
      "title": "Daily Challenge",
      "points": 100,
      "status": "active"
    },
    "relationships": {
      "actions": {
        "data": [
          { "id": "action_456", "type": "action" }
        ]
      }
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

## Error Handling

**Error Codes**

| Code | Description | Resolution |
| - | - | - |
| `UNAUTHORIZED` | Invalid or missing token | Check authentication |
| `FORBIDDEN` | Insufficient permissions | Verify user access |
| `NOT_FOUND` | Resource not found | Check resource ID |
| `VALIDATION_ERROR` | Invalid input | Review request data |
| `ALREADY_COMPLETED` | Action/challenge completed | No action needed |
| `INSUFFICIENT_POINTS` | Not enough points | User needs more points |

**Error Response**

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid action response",
    "details": {
      "field": "response",
      "issue": "Required field missing"
    }
  }
}
```

## Best Practices

**Performance**

* **Cache responses** appropriately (challenges, rewards catalog)
* **Paginate requests** for large datasets
* **Batch where possible** to reduce API calls
* **Use conditional requests** with ETags when available

**User Experience**

* **Handle offline mode** gracefully
* **Optimistic updates** for better perceived performance
* **Progressive loading** for content lists
* **Error recovery** with retry logic
* **Real-time updates** via webhooks when available

**Security**

* **Never expose tokens** in client-side code
* **Validate input** before API calls
* **Handle errors** without exposing sensitive details
* **Rate limit** client-side requests

## Pagination

Most list endpoints support pagination:

```typescript theme={null}
// Pagination parameters
const params = {
  limit: 20,      // Items per page (max 100)
  skip: 40,       // Offset for pagination
  sort: '-created' // Sort by created date descending
};

const challenges = await integration.challenges.list({ params });

// Response includes pagination metadata
{
  data: [...],
  meta: {
    total: 150,
    limit: 20,
    skip: 40,
    hasMore: true
  }
}
```

## Localization

The API supports multiple languages via headers:

```typescript theme={null}
// Set language preference
const integration = createIntegrationClient({
  headers: {
    'x-api-token': token,
    'x-language': 'es-ES' // Spanish
  }
});
```

## Rate Limiting

The Integration API enforces rate limits to ensure fair usage:

* Check response headers for current limits
* `X-RateLimit-Remaining`: Requests remaining
* `X-RateLimit-Reset`: When limit resets
* Implement exponential backoff on 429 responses

## Webhooks

Configure webhooks to receive real-time updates:

* Challenge completed
* Achievement unlocked
* Reward redeemed
* Leaderboard position changed

Configure webhook endpoints in the Admin dashboard.

## Support & Resources

> **[API Reference](https://docs.nudj.cx/api-reference/integration/get-challenges.md)**
>
> Detailed endpoint documentation

> **[Authentication](https://docs.nudj.cx/api-reference/authentication.md)**
>
> Token management guide

> **[SDKs](https://github.com/nudj-digital/sdks)**
>
> Client libraries


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