API Reference
ClawSignal exposes a REST API via Vercel Serverless Functions. All endpoints are at https://clawsignal.co/api/{endpoint}.
Authentication
All API endpoints require authentication via the Authorization header:
Method 1: API Token (recommended for agents and scripts)
Authorization: Bearer your-clawsignal-api-token
Set CLAWSIGNAL_API_TOKEN in environment variables. This is a static token for server-to-server communication.
Method 2: Supabase JWT (used by the frontend)
Authorization: Bearer eyJhbGciOiJS...
The frontend automatically attaches the user's Supabase session JWT via the callAPI() helper.
Error Codes
| Status | Meaning |
|---|
| 200 | Success |
| 400 | Bad request — missing or invalid parameters |
| 401 | Unauthorized — invalid or missing auth token |
| 404 | Resource not found |
| 405 | Method not allowed |
| 500 | Server error |
Client Management
GET /api/clients — List all clients
curl -H "Authorization: Bearer $TOKEN" https://clawsignal.co/api/clients
Query params: ?active=true or ?active=false
POST /api/clients — Create a client
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"business_name":"Acme Plumbing","tier":"starter","contact_email":"owner@acme.com"}' \
https://clawsignal.co/api/clients
PUT /api/clients?id=uuid — Update a client
Keywords
GET /api/keywords?client_id=uuid — List keywords for a client
POST /api/keywords — Add a keyword
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"client_id":"uuid","keyword":"plumber san diego","current_rank":15}' \
https://clawsignal.co/api/keywords
PUT /api/keywords?id=uuid — Update keyword rank
DELETE /api/keywords?id=uuid — Remove a keyword
Deliverables
GET /api/deliverables?client_id=uuid&month=2026-03-01 — List deliverables
POST /api/deliverables — Add a deliverable
PUT /api/deliverables?id=uuid — Toggle/update a deliverable
Audits
GET /api/audits?client_id=uuid — List audits for a client
POST /api/audits — Run or store an audit
Reports
GET /api/reports?client_id=uuid — List reports
POST /api/reports — Generate a report
Alerts
POST /api/alerts-check — Check for alert conditions
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"ranking_drop"}' \
https://clawsignal.co/api/alerts-check
Alert types: ranking_drop, ranking_milestone, new_review, negative_review, audit_drop, deliverable_overdue, portal_inactive, gbp_post_needed, competitor_overtake
Email Reports
POST /api/email-report — Log/send an email report
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"clientId":"uuid","reportData":{"month":"March 2026"},"recipientEmail":"client@example.com"}' \
https://clawsignal.co/api/email-report
Retention Actions
POST /api/retention-action — Send retention outreach email
curl -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"clientId":"uuid","actionType":"case_study"}' \
https://clawsignal.co/api/retention-action
Action types: case_study, testimonial, schedule_call, upsell, winback
Newsletter
POST /api/newsletter-send — Send weekly digest to all subscribers
POST /api/newsletter-subscribe — Subscribe an email
GET /api/newsletter-unsubscribe?email=xxx — Unsubscribe
GSC Integration
POST /api/gsc-auth — Exchange OAuth code for tokens
POST /api/gsc-auth?action=refresh — Refresh access token
POST /api/gsc-auth?action=disconnect — Disconnect GSC
POST /api/gsc-sync — Sync keyword data from GSC
GBP Integration
POST /api/gbp-auth — Exchange OAuth code for GBP tokens
POST /api/gbp-publish — Publish a post to Google
POST /api/gbp-reviews?action=sync — Sync reviews from Google
GET /api/gbp-reviews?clientId=uuid — Get synced reviews
POST /api/gbp-insights?action=sync — Sync performance insights
GET /api/gbp-insights?clientId=uuid — Get synced insights
Other Endpoints
GET /api/rss — RSS 2.0 feed of published blog posts
GET /api/stats — Dashboard statistics
POST /api/stripe-checkout — Create Stripe checkout session
POST /api/stripe-webhook — Handle Stripe payment events
GET /api/docs.json — Machine-readable API documentation (JSON)
Code Examples
JavaScript (fetch)
const res = await fetch('https://clawsignal.co/api/clients', {
headers: { Authorization: 'Bearer ' + API_TOKEN },
});
const clients = await res.json();
Python (requests)
import requests
headers = {"Authorization": f"Bearer {API_TOKEN}"}
res = requests.get("https://clawsignal.co/api/clients", headers=headers)
clients = res.json()
cURL
curl -H "Authorization: Bearer $CLAWSIGNAL_API_TOKEN" \
https://clawsignal.co/api/clients
Rate Limits
Vercel Serverless Functions have default rate limits based on your plan. For most operations, there is no explicit rate limit beyond Vercel's infrastructure limits. However, avoid sending more than 60 requests per minute to prevent throttling.
Registering as an Agent
AI agents (like OpenClaw agents) can interact with ClawSignal by:
- Obtaining a
CLAWSIGNAL_API_TOKEN from the Settings page - Using the API endpoints documented above
- Reading the machine-readable docs at
/api/docs.json - Following the authentication pattern (Bearer token in headers)
Bulk Operations
For bulk keyword imports, use the Bulk Import page in the dashboard or send multiple POST requests to /api/keywords. There is no dedicated bulk endpoint — process items sequentially or in small batches.