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 social media page or account. Returns immediately; watching starts in the background.

Body

• platform (string, required) — one of "facebook" or "x".
• page_url (string, required) — the public page or account URL to watch. For Facebook use https://www.facebook.com/<page>; for X (Twitter) use https://x.com/<handle>.
• 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) — example for Facebook

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

Response (201) — example for X

{"id":"mon_xyz789","platform":"x","page_url":"https://x.com/<handle>","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).

Response (200) — example for Facebook

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

Response (200) — example for X

{"id":"mon_xyz789","platform":"x","page_url":"https://x.com/<handle>","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. The payload includes the event type, monitor ID, platform, and full post metadata for LLM processing.

Example: post.created event (Facebook)

{
  "event": "post.created",
  "monitor_id": "mon_abc123",
  "platform": "facebook",
  "post": {
    "platform_post_id": "123456_789",
    "permalink": "https://www.facebook.com/...",
    "page": {
      "page_id": "100064682681350",
      "page_name": "RMF24.pl",
      "page_url": "https://www.facebook.com/rmf24"
    },
    "text": "Post text content here...",
    "media_type": "photo",
    "thumbnail_url": "https://...",
    "media": {
      "image_url": "https://...",
      "video_url": null,
      "video_duration_seconds": null
    },
    "published_at": "2026-08-25T14:30:00Z",
    "metrics": {
      "reactions": 128,
      "comments": 34,
      "shares": 12,
      "metrics_at": "2026-08-25T14:35:00Z"
    },
    "reaction_breakdown": {"like": 100, "love": 28},
    "resolved_link": {
      "url": "https://example.com/article",
      "og_title": "Article title",
      "og_description": "Article description",
      "og_image": "https://example.com/image.jpg"
    }
  }
}

Example: post.created event (X)

{
  "event": "post.created",
  "monitor_id": "mon_xyz789",
  "platform": "x",
  "post": {
    "platform_post_id": "1234567890",
    "permalink": "https://x.com/tvn24/status/1234567890",
    "page": {
      "page_id": "tvn24",
      "page_name": "TVN24",
      "page_url": "https://x.com/tvn24"
    },
    "text": "Tweet text content here...",
    "media_type": "photo",
    "thumbnail_url": "https://...",
    "media": {
      "image_url": "https://...",
      "video_url": null,
      "video_duration_seconds": null
    },
    "published_at": "2026-08-25T14:30:00Z",
    "metrics": {
      "reactions": 256,
      "comments": 45,
      "shares": 89,
      "metrics_at": "2026-08-25T14:35:00Z"
    },
    "reaction_breakdown": {"like": 256, "quote": 12, "view": 15300},
    "resolved_link": {
      "url": "https://example.com/article",
      "og_title": "Article title",
      "og_description": "Article description",
      "og_image": "https://example.com/image.jpg"
    }
  }
}

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.