social2llm

API Reference

Base URL: https://api.social2llm.com

Authentication

Monitor endpoints (/v2/monitors) use the X-API-Key header with a key from your dashboard. Account endpoints (/me, /me/keys) use a Bearer JWT from Kinde — these are intended for the dashboard, not for API clients.

POST /v2/monitors

Start monitoring a Facebook page. Returns immediately; watching starts in the background.

Body

  • platform (string, required) — currently only "facebook".
  • page_url (string, required) — the public Facebook page URL to watch.
  • callback_url (string, optional) — webhook target; each new post is POSTed here as it's found. Validated against SSRF; an unsafe URL is rejected with 400.

Response (201)

{"id":"mon_abc123","platform":"facebook","page_url":"https://www.facebook.com/<page>","status":"active","callback_url":null,"created_at":"..."}

GET /v2/monitors/{id}

Fetch a monitor owned by the calling API key. Other tenants' ids return 404 (so existence isn't leaked).

{"id":"mon_abc123","platform":"facebook","page_url":"https://www.facebook.com/<page>","status":"active","callback_url":"https://your-app.example/webhook","created_at":"..."}

POST /v2/monitors/{id}/reactivate

Resume a stopped monitor. It picks back up watching the page for new posts.

{"id":"mon_abc123","status":"active"}

DELETE /v2/monitors/{id}

Stop monitoring (soft-delete). Posts already delivered are unaffected.

Webhook payload

When a monitor has a callback_url, each new post is POSTed to it as it's found:

{"monitor_id":"mon_abc123","post_id":"...","post_url":"https://www.facebook.com/...",
 "text":"...","posted_at":"...",
 "engagement":{"reactions":128,"comments":34,"shares":12},
 "first_comment_url":"https://www.facebook.com/.../?comment_id=..."}

GET /me

(Bearer JWT) Current user + list of active (non-revoked) API keys.

POST /me/keys

(Bearer JWT) Create a new API key. The raw key is shown once.

# Request
{"label":"Production"}

# Response (201) — raw key shown ONCE
{"id":"...","label":"Production","key_prefix":"soc_a1b2c3d4","key":"soc_...","created_at":"..."}

DELETE /me/keys/{id}

(Bearer JWT) Soft-delete a key. Subsequent requests with that key return 401.

Errors

  • 400 — unsupported platform, or unsafe callback URL.
  • 401 — missing/invalid/revoked key, or bad JWT.
  • 403 — account pending approval (key creation blocked).
  • 404 — unknown monitor, or one owned by another key.
  • 422 — malformed request body.