API Overview

REST API for PRIV Protocol services.

Base URL

https://api.privlabs.io/v1

For development and testing:

https://api-dev.privlabs.io/v1

Authentication

All requests require an API key or JWT token in the Authorization header.

API Key Authentication

curl -H "Authorization: Bearer pk_live_xxx" \
  https://api.privlabs.io/v1/events

JWT Authentication

For user-specific endpoints, you can use a JWT token obtained from Supabase Auth:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.privlabs.io/v1/user/balance

API Key Types

Get your API key from the PRIV Dashboard.

Rate Limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1704067200

Response Format

Success Response

All successful responses follow this structure:

{
  "success": true,
  "data": { ... }
}

Error Response

Error responses include a code and message:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Error Codes

API Endpoints

Events (SDK Integration)

• POST /events - Track events (supports batch)
• POST /identify - Identify a user
• POST /page - Track a page view

Analytics

• GET /analytics - Query analytics data with filtering

User Endpoints

• GET /user/balance - Get PRIV token balance
• GET /user/consent - Get consent preferences
• POST /user/consent - Update consent preferences
• GET /user/reputation - Get reputation details
• GET /user/earnings - Get earnings history
• POST /user/earnings/claim - Claim pending earnings

Data Contributions

• POST /contributions/upload - Upload a contribution
• GET /contributions - List user's contributions
• GET /contributions/:id - Get contribution details
• DELETE /contributions/:id - Delete a contribution

Wallet Marketplace

• GET /marketplace/wallet/listings - Browse listings
• POST /marketplace/wallet/listings - Create a listing
• GET /marketplace/wallet/listings/:id - Get listing details
• PUT /marketplace/wallet/listings/:id - Update a listing
• POST /marketplace/wallet/listings/:id/purchase - Purchase a listing
• GET /marketplace/wallet/purchases - List purchases
• GET /marketplace/wallet/purchases/:id/download - Download purchased data

Labeling Tasks

• GET /tasks - Get available tasks
• POST /tasks/:id/submit - Submit task answer
• GET /tasks/history - Get task submission history

Data Marketplace

• GET /data/listings - Browse data listings
• POST /data/purchase - Purchase a data listing

Mobile (VPN App)

• POST /mobile/session/start - Start VPN session
• POST /mobile/session/end - End VPN session
• GET /mobile/session/current - Get active session
• GET /mobile/sessions - List session history
• GET /mobile/earnings/summary - Get earnings summary
• GET /mobile/earnings/history - Get earnings history
• POST /mobile/earnings/claim - Claim mobile earnings
• POST /mobile/events - Track mobile events
• POST /mobile/sync - Sync offline data

Billing (Stripe)

• GET /billing/pricing - Get plan pricing (public)
• POST /billing/create-checkout - Create checkout session
• GET /billing/subscription - Get subscription details
• POST /billing/portal - Open customer portal

Storage (IPFS)

• POST /storage/upload - Upload file (max 10MB)
• POST /storage/signed-url - Get signed URL for large files
• GET /storage/:cid - Get file metadata

Utility

• GET /health - API health check

SDKs

Official SDKs handle API communication automatically:

MCP Server

PRIV also exposes all marketplace operations via an MCP (Model Context Protocol) server. This enables AI agents to interact with the API using the standardized MCP protocol instead of direct REST calls.

See the MCP Server documentation for details.

CORS

Public SDK endpoints (/events, /analytics, /identify) support CORS with Access-Control-Allow-Origin: *.

Authenticated user endpoints (/user/*, /contributions/*, etc.) require specific origin configuration and support credentials.

Versioning

The API is versioned via the URL path (/v1/). Breaking changes will be introduced in new versions while maintaining backward compatibility in existing versions.