API Overview

REST API for PRIV Protocol services.

Base URL

https://api.priv.io/v1

For development and testing:

https://api-dev.priv.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.priv.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.priv.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

SDKs

Official SDKs handle API communication automatically:

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.