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
Google approved Business Profile API access on 2026-07-27. Write, OAuth, and sync operations are available on a connected profile. If the availability gate is ever closed on our side, those operations return HTTP 503 with code: "gbp_api_approval_pending" (a legacy code string kept stable for API consumers) before any external Google call. Disconnect and reads of historical stored rows remain available.
POST /api/gbp-auth — Unavailable; OAuth exchange is blocked pending approval
POST /api/gbp-auth?action=disconnect — Remove an existing stored connection
POST /api/gbp-publish — Unavailable pending approval
POST /api/gbp-reviews?action=sync — Unavailable pending approval
GET /api/gbp-reviews?clientId=uuid — Get historical stored reviews
POST /api/gbp-insights?action=sync — Unavailable pending approval
GET /api/gbp-insights?clientId=uuid — Get historical stored 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.