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

# API Reference

> High-level overview of the main REST API endpoints used by Winstory.io.

## Overview

This page documents the **most important REST endpoints** exposed by `app.winstory.io`.\
It is intended for **internal engineering use** and for agency partners who need to integrate directly.

Base URL: `https://app.winstory.io/api`

Authentication:

* Most endpoints used by the app are **server-side** and authenticated via **Supabase JWT** (handled internally).
* Public endpoints are explicitly marked below.

> Full OpenAPI/Swagger generation is planned as a next step. This page is the canonical source of truth until then.

## Campaigns

### `GET /campaigns/moderation`

Fetch moderation data for one campaign or all campaigns of a creator.

Query params:

* `campaignId` (optional): string — specific campaign
* `walletAddress` (optional): string — creator wallet
* `page` / `pageSize` (optional): server-side pagination when querying by `walletAddress`

Response:

* `moderationData[]` with:
  * `campaignId`, `campaignTitle`, `campaignStatus`, `creatorType`, `campaignType`
  * `progress` (votes, staking, hybrid score)
  * `sessions[]` (individual moderator votes)
  * `blockchainMapping` (on-chain mapping info)

### `GET /campaigns/dashboard?campaignId={id}`

Unified dashboard endpoint used by the **Validated Campaign** view.

Returns:

* `metrics` (ROI, completions, validated/refused history, vote history)
* `platformFeeInfo`
* `validationStatus`

### `GET /campaigns/metrics?campaignId={id}`

Detailed metrics for a single campaign.\
Used internally by `metricsService` and `CampaignEconomics`.

### `GET /campaigns/metrics/batch?campaignIds=a,b,c`

Batch metrics endpoint (used by MyWin/Creations):

* Input: comma-separated list of `campaignIds`
* Output: `{ metrics: Record<campaignId, CampaignMetrics>, errors?: Record<campaignId, string> }`

### `POST /campaigns`

Campaign creation endpoint (`/campaigns/create` in the codebase):

* Validates pricing, duration, rewards, and payment
* For B2C/Agency, **crypto/Stripe payment must be verified** before creation in production

## Completions

### `GET /completions/community-completions`

Public endpoint used by community moderation tooling.\
Returns a curated list of completions with moderation and reward data.

### `POST /completions/submit`

Create a new completion for a given campaign (B2C or Individual):

* Validates user authentication
* Validates that the campaign is open and budget is available
* Handles payment (if required)

### `GET /completions/details?completionId={id}`

Returns full moderation/score details for a single completion.

## Rewards

### `GET /rewards/individual/distribution-status`

Returns detailed reward distribution status for **individual** campaigns:

* Rankings, expected vs actual amounts
* On-chain distribution status and tx hashes

### `GET /campaigns/[id]/rewards-monitoring`

B2C/Agency reward monitoring endpoint used by the **Rewards Monitoring** dashboard.

## Short Links

### `GET /campaigns/short-link?campaignId={id}&devMode={true|false}`

Returns or creates a **short completion link** for a campaign.

* In production, only available when the campaign is **fully validated**
* In development, `devMode=true` bypasses validation for faster testing

### `GET /campaigns/short-link/redirect?shortCode={code}`

Resolves a short code to the full completion URL.\
Used by `https://app.winstory.io/c/{code}`.

## Cron & Monitoring

### `GET /cron/monitor-resources`

Periodic resource monitoring (CPU, DB connections, storage).\
Configured via `vercel.json` cron.

### `GET /cron/monitor-onchain`

On-chain consistency checker:

* Samples recent crypto payments
* Verifies on-chain status via RPC
* Logs anomalies into `system_error_logs`