Quick Start

Get up and running in three steps. No credit card required for the free tier.

Get your API key

Make your first request

Call any endpoint with your token. Try GET /api/v1/campaigns to list active campaigns or GET /api/v1/actions to browse the 107 marketing actions.

Handle the response

Every response follows a consistent { success, data } envelope. Errors include a machine-readable code and a human-readable message.

Authentication

Social Perks supports two authentication methods. Use whichever fits your use case.

Bearer Token (JWT)

Authenticate via POST /api/v1/auth with email and password. The response includes an accessToken and a refreshToken. Pass the access token in the Authorization header.

bashLogin

curl -X POST https://socialperks.io/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "action": "login",
    "email": "you@example.com",
    "password": "your-password"
  }'

API Key

Generate an API key from your business dashboard. Pass it via the X-API-Key header or as a Bearer token. API keys are scoped to a single business and never expire until rotated.

bashUsing API Key

curl https://socialperks.io/api/v1/campaigns \
  -H "Authorization: Bearer sk_live_abc123..."

# or

curl https://socialperks.io/api/v1/campaigns \
  -H "X-API-Key: sk_live_abc123..."

Response format: All responses include X-Request-Id and X-Response-Time headers for tracing. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included on every response.

API Endpoints

35+ RESTful endpoints organized by domain. All routes live under /api/v1. The full OpenAPI 3.1 spec is available at /api/v1/docs.

Authentication

Method	Path	Description
GET	/api/v1/auth	Validate current session (Bearer token)
POST	/api/v1/auth	Login, signup, logout, refresh, or reset password

Campaigns

Method	Path	Description
GET	/api/v1/campaigns	List campaigns with filters and pagination
POST	/api/v1/campaigns	Create and launch a new campaign
PUT	/api/v1/campaigns	Update campaign or change lifecycle state

Submissions

Method	Path	Description
GET	/api/v1/submissions	List submissions with filters
POST	/api/v1/submissions	Create submission with proof
POST	/api/v1/submissions/review	Approve or reject a submission

AI (Backend-Only)

Method	Path	Description
POST	/api/v1/ai/generate	Generate campaign suggestions
POST	/api/v1/ai/recommend	Optimization recommendations
POST	/api/v1/ai/review	AI submission review pipeline
POST	/api/v1/ai/campaign-agent	Full AI marketing plan
POST	/api/v1/ai/quick-start	Quick-start single recommendation

Perk Programs

Method	Path	Description
GET	/api/v1/programs	List perk programs
POST	/api/v1/programs	Create a perk program
GET	/api/v1/programs/:id	Get program details
PUT	/api/v1/programs/:id	Update a program
DELETE	/api/v1/programs/:id	End a program
GET	/api/v1/programs/:id/progress	Member progress tracking
POST	/api/v1/programs/:id/submit	Submit an action
GET	/api/v1/programs/:id/cashback	List payouts
POST	/api/v1/programs/:id/cashback	Request or manage cashback
GET	/api/v1/programs/:id/members	List enrolled members
POST	/api/v1/programs/:id/members	Enroll a member

Exchange

Method	Path	Description
GET	/api/v1/exchange/opportunities	Market opportunities (public)
GET	/api/v1/exchange/market	Real-time market data (public)
GET	/api/v1/exchange/orders	List orders
POST	/api/v1/exchange/orders	Place buy/sell order
GET	/api/v1/exchange/trades	List trades
POST	/api/v1/exchange/trades	Trade lifecycle actions
POST	/api/v1/exchange/enroll	Agent auto-enrollment

Billing

Method	Path	Description
POST	/api/v1/billing	Subscription management
POST	/api/v1/billing/webhook	Stripe webhook handler

Reference Data

Method	Path	Description
GET	/api/v1/pricing	Pricing oracle (public, cached)
GET	/api/v1/actions	Action library — 107 marketing actions
GET	/api/v1/benchmarks	Industry benchmarks (public, cached)
GET	/api/v1/influencers	Search influencers
POST	/api/v1/influencers	Register an influencer
GET	/api/v1/recommendations	ML-powered recommendations
GET	/api/v1/legal	Legal compliance briefings

Infrastructure

Method	Path	Description
GET	/api/v1/events	SSE real-time event stream
GET	/api/v1/health	Health check
GET	/api/v1/docs	OpenAPI 3.1 specification
GET	/api/v1/mcp	MCP server definition
POST	/api/v1/oauth/connect	Start OAuth flow
GET	/api/v1/oauth/:platform	OAuth callback
POST	/api/v1/verification/webhook	Platform webhook receiver

Example Requests

Common operations with curl. Replace $TOKEN with your Bearer token or API key.

List active campaigns

bashGET /api/v1/campaigns

curl "https://socialperks.io/api/v1/campaigns?state=active&page=1&perPage=10" \
  -H "Authorization: Bearer $TOKEN"

jsonResponse

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "camp_abc123",
        "name": "Summer Review Drive",
        "state": "active",
        "platform": "google",
        "actionType": "review",
        "reward": { "type": "percentage", "value": 15 },
        "createdAt": "2026-03-01T00:00:00Z"
      }
    ],
    "pagination": { "page": 1, "perPage": 10, "total": 42, "totalPages": 5 }
  }
}

Create a campaign

bashPOST /api/v1/campaigns

curl -X POST https://socialperks.io/api/v1/campaigns \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Instagram Story Shoutout",
    "platform": "instagram",
    "actionType": "story",
    "reward": { "type": "fixed", "value": 5.00 },
    "requirements": {
      "minFollowers": 500,
      "hashtags": ["#socialperks", "#ad"]
    }
  }'

Submit proof of action

bashPOST /api/v1/submissions

curl -X POST https://socialperks.io/api/v1/submissions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "camp_abc123",
    "proofUrl": "https://instagram.com/p/abc123",
    "proofType": "url",
    "notes": "Posted story with required hashtags"
  }'

Get AI recommendations

bashPOST /api/v1/ai/recommend

curl -X POST https://socialperks.io/api/v1/ai/recommend \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "biz_xyz789",
    "industry": "food_beverage",
    "goals": ["increase_reviews", "social_engagement"]
  }'

SDKs

Official client libraries with full type safety and built-in retry logic.

TypeScript SDK

Available now

typescriptInstall & usage

import { SocialPerksSDK } from "@socialperks/sdk";

const client = new SocialPerksSDK({
  baseUrl: "https://socialperks.io",
  apiKey: "sk_live_abc123...",
});

const campaigns = await client.listCampaigns({
  state: "active",
  page: 1,
});

Python SDK

Available now

pythonInstall & usage

from social_perks import SocialPerksClient

client = SocialPerksClient(
    base_url="https://socialperks.io",
    api_key="sk_live_abc123...",
)

campaigns = client.list_campaigns(state="active")
print(campaigns.data)

Download the generated SDK: /api/v1/sdk/python

Rate Limits

Rate limits are enforced per IP per endpoint. Every response includes rate limit headers so you can track your usage.

Tier	Limit	Applies To
Strict	5 req/min	Auth, password reset
Standard	30 req/min	Authenticated API calls
Relaxed	60 req/min	Read-only endpoints
Public	120 req/min	Public data (pricing, actions, benchmarks)

Rate limit headers: X-RateLimit-Limit (max requests), X-RateLimit-Remaining (requests left), X-RateLimit-Reset (epoch timestamp when the window resets). If you exceed the limit, you will receive a 429 Too Many Requests response.

Webhooks

Receive real-time notifications when events occur in your account. Configure webhook URLs in your dashboard.

Webhook Events

campaign.created

campaign.updated

campaign.ended

submission.created

submission.approved

submission.rejected

payout.completed

member.enrolled

Verifying Signatures

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body. Verify it using your webhook secret.

typescriptSignature verification

import { createHmac } from "crypto";

function verifyWebhook(
  body: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return signature === `sha256=${expected}`;
}

// In your handler:
const isValid = verifyWebhook(
  rawBody,
  req.headers["x-webhook-signature"],
  process.env.WEBHOOK_SECRET
);

Replay protection: Each webhook includes an X-Webhook-Timestamp header. Reject requests older than 5 minutes to prevent replay attacks.

Agent & LLM Support

Social Perks is designed to be consumed by AI agents and LLMs. We provide machine-readable definitions for major protocols.

MCP Server

Model Context Protocol definition with typed tools, input schemas, and resource definitions.

/api/v1/mcp

OpenAPI Spec

Full OpenAPI 3.1 specification. Import into any API tool, agent framework, or code generator.

/api/v1/docs

AI Plugin Manifest

OpenAI-compatible plugin manifest for agent discovery and automatic capability registration.

/.well-known/ai-plugin.json

Support & Resources

Useful Links

OpenAPI 3.1 Specification -- interactive API docs
Health Check -- server status and uptime
MCP Server Definition -- for LLM agents
Download Python SDK -- generated client library
AI Agent Guide -- connect your agents to businesses

Response Envelope

Every API response follows this structure, making it predictable to parse for both humans and agents.

jsonSuccess

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

jsonError

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests"
  }
}

Get your API key

Make your first request

Handle the response

Bearer Token (JWT)

API Key

Authentication

Campaigns

Submissions

AI (Backend-Only)

Perk Programs

Exchange

Billing

Reference Data

Infrastructure

List active campaigns

Create a campaign

Submit proof of action

Get AI recommendations

TypeScript SDK

Python SDK

Webhook Events

Verifying Signatures

MCP Server

OpenAPI Spec

AI Plugin Manifest

Useful Links

Response Envelope

Explore Social Perks

Industries

Cities

Tools

Guides

Compare

Resources