SocialINTEL

Fetching datasets…

Social Intel API reference. RESTful endpoints, no SDK required.
Base URL: https://api.socialintel.io

Endpoints:
1. GET /api/datasets/catalog — Returns the full catalog of available datasets as JSON.
2. GET /api/datasets/info/{slug} — Metadata about a dataset by slug: record_count, update_frequency, platform, sample fields.
3. GET /api/datasets/sample/{slug} — Downloads a sample of a dataset as CSV, JSON, JSONL, or Parquet.
4. GET /api/datasets/download/{slug} — Downloads the full dataset in CSV, JSON, JSONL, or Parquet formats. Requires an API key (X-API-Key header) for full downloads.

Examples:
Python example demonstrating catalog listing and dataset download using the requests library are shown on the page.

API Reference

Social Intel API

Download datasets, access samples, and integrate social data into your pipeline. RESTful, no SDK required. The five platform tools — Trend Radar, Coordinated Behavior, Vertical Intelligence, NL Insights, and the Dataset Cleaner — live in the app's Tools menu.

Base URL

api.socialintel.io

Protocol

HTTPS

Auth

X-API-Key

Formats

CSV/JSON/JSONL/Parquet

Quickstart

Get a free sample

100 rows, no auth required. Try before you download.

bash

curl "https://api.socialintel.io/api/datasets/sample/ageing-population-and-eldercare-discourse?format=csv" \
  -o sample.csv

Download full dataset

Add your API key for full access.

bash

curl "https://api.socialintel.io/api/datasets/download/ai-model-release-sentiment?format=json" \
  -H "X-API-Key: sk_live_..." \
  -o data.json

Rate Limits

Global

100/min

Per IP, edge-protected

Free Plan

500/day

~15K/month average

Individual Plan

1,000/day

Per-dataset purchases

Pro Plan

Up to 15K/day

Customizable via Pro Builder

Python

Requires the requests library (pip install requests).

python

import requests

API_KEY = "sk_live_..."
HEADERS = {"X-API-Key": API_KEY}

# Get catalog
catalog = requests.get(f"https://api.socialintel.io/api/datasets/catalog").json()

# Download a dataset
r = requests.get(
    f"https://api.socialintel.io/api/datasets/download/ai-model-release-sentiment",
    params={"format": "json"},
    headers=HEADERS
)
with open("ai-model-release-sentiment.json", "w") as f:
    f.write(r.text)

Endpoints

Pro plan — 7-day free trial — also includes webhook subscriptions (POST /api/webhooks), scheduled exports (POST /api/exports/schedules), and custom dataset requests (POST /api/custom-dataset-requests). See the Dashboard for your API key and full endpoint reference.

GET/api/datasets/catalogPublic

Returns all active datasets with live metadata including record counts, prices, and available formats.

Request

bash

curl "https://api.socialintel.io/api/datasets/catalog"

Response

json

[
  {
    "slug": "ageing-population-and-eldercare-discourse",
    "name": "Ageing Population & Eldercare Discourse",
    "platform": "Reddit",
    "record_count": 5200,
    "formats": ["csv","json","jsonl","parquet"],
    "status": "active"
  }
]

GET/api/datasets/sample/{slug}Public

Download a 100-row preview of any dataset. No authentication required. Great for testing.

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug (see catalog below)
`format` query	`string`	csv \| json \| jsonl \| parquet (default: csv)
`limit` query	`integer`	1–1000 rows to return (JSON only; default: full 100-row sample)

Request

bash

curl "https://api.socialintel.io/api/datasets/sample/ageing-population-and-eldercare-discourse?format=csv" \
  -o sample.csv

Response

json

# Returns file download — 100 rows always

GET/api/datasets/download/{slug} Auth

Download the full dataset. Free for datasets under 10K rows. Larger datasets require an Individual purchase or Pro plan (7-day free trial). Requires X-API-Key or Bearer token.

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug
`format` query	`string`	csv \| json \| jsonl \| parquet (default: csv)
`limit` query	`integer`	Max rows to return (1–100000, JSON pagination)
`starting_after` query	`string`	Cursor — last post_id from the previous page

Request

bash

curl "https://api.socialintel.io/api/datasets/download/ageing-population-and-eldercare-discourse?format=json" \
  -H "X-API-Key: sk_live_..." \
  -o data.json

Response

json

# 200 — file download
# 401 — missing/invalid API key
# 403 — not authorized or plan too low
# 404 — dataset not found

GET/api/datasets/info/{slug}Public

Get detailed metadata for a single dataset including sample rows and enrichment fields.

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug

Request

bash

curl "https://api.socialintel.io/api/datasets/info/ageing-population-and-eldercare-discourse"

Response

json

{
  "id": 151,
  "slug": "ageing-population-and-eldercare-discourse",
  "name": "Ageing Population & Eldercare Discourse",
  "platform": "Reddit",
  "platforms": ["reddit"],
  "platform_count": 1,
  "description": "Monitoring eldercare technology innovation discussions, ageing-in-place solution reviews, senior healthcare access debates, and demographic shift community impact assessment signals",
  "record_count": 5200,
  "price": 0,
  "status": "active",
  "update_frequency": "weekly",
  "formats": ["csv","json","jsonl","parquet"],
  "fields": ["id","content","sentiment_score",...],
  "license": "social-intel-commercial",
  "sample_url": "/api/datasets/sample/ageing-population-and-eldercare-discourse",
  "download_url": "/api/datasets/download/ageing-population-and-eldercare-discourse"
}

GET/api/datasets/model-card/{slug}Public

Returns pre-computed model-card data for a dataset: topic distribution, field coverage, and platform breakdown. Public for catalog datasets.

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug

Request

bash

curl "https://api.socialintel.io/api/datasets/model-card/ageing-population-and-eldercare-discourse"

Response

json

{
  "dataset": "ageing-population-and-eldercare-discourse",
  "topics": [ { "topic": "Eldercare technology", "count": 1240 } ],
  "field_coverage": { "id": 1.0, "content": 1.0, "sentiment_score": 0.92 },
  "platform_breakdown": [ { "platform": "reddit", "count": 5200 } ]
}

GET/api/datasets/catalog/eventsPublic

Server-Sent Events stream. Emits a 'catalog_updated' event whenever the catalog changes (new dataset uploaded or cache invalidated), so clients can refetch /api/datasets/catalog.

Request

bash

curl -N "https://api.socialintel.io/api/datasets/catalog/events"

Response

json

# text/event-stream
data: {"type": "catalog_updated", "at": "2026-08-11T10:00:00Z"}

# Keep-alive comments are sent periodically to hold the connection open

GET/api/datasets/statusPublic

Returns the last catalog collection timestamp. Use it to decide whether to refetch the catalog.

Response

json

{
  "last_updated": "2026-08-11T09:00:00Z",
  "last_updated_ts": 1760000000.0
}

GET/api/datasets/download-limit Auth

Returns the current free-download usage for the authenticated user. Free users may download up to 10 full datasets per day.

Response

json

{
  "downloads_today": 3,
  "daily_limit": 10,
  "is_free_user": true
}

GET/api/datasets/payment-productsPublic

Slug → {name, price} mapping for frontend checkout. Use /api/datasets/catalog for full metadata.

Response

json

{
  "products": { "ai-model-release-sentiment": { "name": "AI Model Release Sentiment", "price": 28.0 } },
  "count": 1
}

GET/api/datasets/configsPublic

All active dataset configs for the catalog frontend. Private datasets are excluded.

Response

json

[
  { "slug": "ageing-population-and-eldercare-discourse", "name": "Ageing Population & Eldercare Discourse", "category": "Social", "status": "active" }
]

GET/api/datasets/categoriesPublic

Returns all unique dataset categories, used to populate catalog filters.

Response

json

{
  "categories": ["AI & Technology", "Finance", "Social", "Health"]
}

Reviews

GET/api/datasets/{slug}/reviewsPublic

Get all reviews for a dataset with reviewer info.

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug

Request

bash

curl "https://api.socialintel.io/api/datasets/ageing-population-and-eldercare-discourse/reviews"

Response

json

{
  "success": true,
  "reviews": [
    {
      "id": "rev_...",
      "dataset_slug": "ageing-population-and-eldercare-discourse",
      "rating": 5,
      "body": "Great coverage of eldercare discourse.",
      "created_at": "2026-08-01T10:00:00Z",
      "updated_at": null,
      "user": { "name": "Jane Doe", "plan": "pro", "plan_display": "Pro" }
    }
  ]
}

GET/api/datasets/{slug}/reviews/mine Auth

Get the current user's review for a dataset, if any.

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug

Response

json

{
  "success": true,
  "review": {
    "id": "rev_...",
    "rating": 5,
    "body": "Great coverage of eldercare discourse.",
    "user": { "name": "Jane Doe", "plan": "pro", "plan_display": "Pro" }
  }
}

POST/api/datasets/{slug}/reviews Auth

Create or update a review. You must have full download access to the dataset (Pro, or purchased). Requires a Cloudflare Turnstile token.

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug
`rating` body · required	`integer`	1–5 stars
`body` body · required	`string`	Review text
`cf_turnstile_response` body · required	`string`	Cloudflare Turnstile token

Request

bash

curl -X POST "https://api.socialintel.io/api/datasets/ageing-population-and-eldercare-discourse/reviews" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"rating": 5, "body": "Great dataset.", "cf_turnstile_response": "0.aAAAA..."}'

Response

json

{
  "success": true,
  "review": { "id": "rev_...", "rating": 5, "body": "Great dataset." }
}

DELETE/api/datasets/{slug}/reviews/{review_id} Auth

Delete a review. Only the review author can delete their own review.

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug
`review_id` path · required	`string`	Review ID

Response

json

{
  "success": true
}

GET/api/datasets/{slug}/reviews/ratingPublic

Get the average rating for a dataset.

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug

Response

json

{
  "success": true,
  "average_rating": 4.6
}

GET/api/reviews/featuredPublic

Return top-rated reviews for use as testimonials. No authentication required.

Response

json

{
  "success": true,
  "reviews": [
    { "id": "rev_...", "dataset_slug": "ai-model-release-sentiment", "rating": 5, "body": "...", "user": { "name": "Jane Doe", "plan": "pro" } }
  ]
}

GET/api/auth/oauth/googlePublic

Start Google OAuth sign-in/sign-up. 302-redirects the browser to Google, then back to /auth/callback#token=... No passwords or usernames are used. On turnstile failure it redirects to /login?error=turnstile_failed.

Query Parameters

Name	Type	Description
`redirect` query	`string`	Relative frontend path to return to after sign-in (default /)
`turnstile` query · required	`string`	Cloudflare Turnstile token (required, else 302 → /login?error=turnstile_failed)

Request

bash

curl -i "https://api.socialintel.io/api/auth/oauth/google?redirect=%2Fdashboard&turnstile=0.aAAAA..."

Response

json

# 302 — Redirect to Google (authorization_code flow)
# Location: https://accounts.google.com/o/oauth2/v2/auth?client_id=...&state=...
# On failure: 302 → {frontend_url}/login?error=turnstile_failed

GET/api/user/favorites Auth

Return list of dataset slugs the current user has favorited.

Request

bash

curl "https://api.socialintel.io/api/user/favorites" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "favorites": ["ageing-population-and-eldercare-discourse", "ai-model-release-sentiment"]
}

POST/api/user/favorites Auth

Add a dataset to user's favorites.

Query Parameters

Name	Type	Description
`slug` body · required	`string`	Dataset slug to favorite

Request

bash

curl -X POST "https://api.socialintel.io/api/user/favorites" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"slug": "ageing-population-and-eldercare-discourse"}'

Response

json

{
  "success": true,
  "favorited": true
}

DELETE/api/user/favorites/{slug} Auth

Remove a dataset from user's favorites.

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug to unfavorite

Request

bash

curl -X DELETE "https://api.socialintel.io/api/user/favorites/ageing-population-and-eldercare-discourse" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "removed": true
}

Authentication

GET/api/auth/me Auth

Returns the authenticated user's basic information including ID, email, and plan tier.

Request

bash

curl "https://api.socialintel.io/api/auth/me" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "user": {
    "id": "usr_...",
    "email": "user@example.com",
    "plan": "free",
    "email_verified": true
  }
}

POST/api/auth/logout Auth

Invalidate the current session / access token. Requires the JWT Bearer token (API keys are not accepted by this endpoint).

Request

bash

curl -X POST "https://api.socialintel.io/api/auth/logout" \
  -H "Authorization: Bearer eyJhbGciOi..."

Response

json

{
  "success": true,
  "message": "Logged out."
}

POST/api/auth/refresh Auth

Refresh the access token before it expires. Requires the JWT Bearer token or the httpOnly access_token cookie (API keys are not accepted by this endpoint).

Request

bash

curl -X POST "https://api.socialintel.io/api/auth/refresh" \
  -H "Authorization: Bearer eyJhbGciOi..."

Response

json

{
  "success": true,
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer"
}

POST/api/auth/verify-emailPublic

Verify your email address using the token sent by email (used for pending email changes).

Query Parameters

Name	Type	Description
`token` body · required	`string`	Verification token from email

Request

bash

curl -X POST "https://api.socialintel.io/api/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{"token": "base64email.verificationtoken"}'

Response

json

{
  "success": true,
  "message": "Email verified. You are now signed in.",
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "user": { "id": "usr_...", "email": "user@example.com", "email_verified": true }
}

GET/api/auth/oauth/google/callbackPublic

Google redirects the browser here after sign-in. On success the user is signed in and redirected to /auth/callback#token=... with an httpOnly session cookie set. On failure it redirects to /login?error=...&redirect=...

Query Parameters

Name	Type	Description
`code` query · required	`string`	Authorization code from Google
`state` query · required	`string`	State token issued by /api/auth/oauth/google
`error` query	`string`	Present when the user denies consent

Response

json

# 302 — Redirect to {frontend_url}/auth/callback#token=... (success)
# 302 — Redirect to {frontend_url}/login?error=provider_error&redirect=/

POST/api/auth/resend-verificationPublic

Re-send the email verification link for an unverified account. Response is always the same regardless of whether the email exists (prevents account enumeration). Rate limited per email.

Query Parameters

Name	Type	Description
`email` body · required	`string`	Email address to resend verification for
`cf_turnstile_response` body	`string`	Cloudflare Turnstile token

Request

bash

curl -X POST "https://api.socialintel.io/api/auth/resend-verification" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "cf_turnstile_response": "0.aAAAA..."}'

Response

json

{
  "success": true,
  "message": "If the email exists, a link has been sent."
}

User Profile

GET/api/user/me Auth

Full user profile including API call usage, plan details, and account info.

Request

bash

curl "https://api.socialintel.io/api/user/me" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "user": {
    "id": "usr_...",
    "email": "user@example.com",
    "name": "Jane Doe",
    "plan": "pro",
    "email_verified": true,
    "subscription_status": "active",
    "is_subscription_active": true,
    "created_at": "2026-01-01T00:00:00Z",
    "trial": null,
    "purchased_dataset_slugs": ["ai-model-release-sentiment"],
    "favorite_slugs": ["ageing-population-and-eldercare-discourse"]
  },
  "usage": {
    "plan": "pro",
    "api_calls_today": 420,
    "daily_limit": 15000,
    "remaining_today": 14580,
    "burst_limit": 100,
    "total_api_calls": 12000,
    "is_premium": true,
    "subscription_active": true,
    "days_until_expiry": 21
  }
}

PUT/api/user/profile Auth

Update display name, email, or profile picture.

Query Parameters

Name	Type	Description
`name` body	`string`	Display name
`profilePic` body	`string`	Avatar image URL or base64 data URI (max 10MB, JPEG/PNG/GIF/WebP)
`email` body	`string`	New email — requires verification; applied only after the emailed token is confirmed

Request

bash

curl -X PUT "https://api.socialintel.io/api/user/profile" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "profilePic": "https://example.com/avatar.jpg"}'

Response

json

{
  "success": true,
  "message": "Profile updated"
}

POST/api/user/regenerate-key Auth

Revoke the current API key and issue a new one. Confirmed by a 6-digit code emailed to you.

Query Parameters

Name	Type	Description
`verification_code` body · required	`string`	6-digit code emailed via /api/user/regenerate-key/send-code

Request

bash

curl -X POST "https://api.socialintel.io/api/user/regenerate-key" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"verification_code": "483920"}'

Response

json

{
  "success": true,
  "apiKey": "sk_live_..."
}

GET/api/user/downloads Auth

List all dataset downloads made by the authenticated user. Returns an array (not wrapped in an object).

Request

bash

curl "https://api.socialintel.io/api/user/downloads" \
  -H "X-API-Key: sk_live_..."

Response

json

[
  { "slug": "ageing-population-and-eldercare-discourse", "name": "Ageing Population & Eldercare Discourse", "format": "csv", "type": "sample", "ts": 1760000000000 }
]

POST/api/user/regenerate-key/send-code Auth

Email a one-time 6-digit code used to confirm regenerating the primary API key. Rate limited.

Response

json

{
  "success": true,
  "message": "Verification code sent to your email."
}

GET/api/user/preferences Auth

Return the current user's saved preferences object.

Response

json

{
  "success": true,
  "preferences": { "email_notifications": true, "default_format": "csv" }
}

PUT/api/user/preferences Auth

Save user preferences. Replaces the entire preferences object with the one provided.

Query Parameters

Name	Type	Description
`preferences` body · required	`object`	Full preferences object to store

Request

bash

curl -X PUT "https://api.socialintel.io/api/user/preferences" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"preferences": {"email_notifications": true}}'

Response

json

{
  "success": true,
  "message": "Preferences saved"
}

GET/api/user/usage-stats Auth

Daily usage stats for the last 30 days: API calls, records downloaded, and datasets downloaded.

Response

json

{
  "success": true,
  "stats": [
    { "date": "2026-08-11", "api_calls": 420, "records_downloaded": 0, "datasets_downloaded": 1 }
  ]
}

GET/api/user/export Auth

Export all of the user's data (profile, purchases, and API keys) as a JSON attachment for GDPR data portability.

Response

json

# 200 — JSON file download
# Content-Disposition: attachment; filename=social-intel-export-2026-08-11.json
{
  "exported_at": "2026-08-11T10:00:00Z",
  "user": { "email": "user@example.com", "plan": "pro" },
  "purchases": [],
  "api_keys": []
}

GET/api/trial/status Auth

Return the Pro trial status for the current user.

Response

json

{
  "success": true,
  "trial": {
    "active": true,
    "started": "2026-08-04T10:00:00Z",
    "expires": "2026-08-11T10:00:00Z",
    "plan": "pro_monthly",
    "days_remaining": 3
  }
}

Two-Factor Authentication

POST/api/user/2fa/setup Auth

Generate a TOTP secret and 8 backup codes. 2FA is not enabled until verified via /api/user/2fa/verify. Requires a verified email.

Response

json

{
  "success": true,
  "secret": "JBSWY3DPEHPK3PXP",
  "backupCodes": ["1A2B3C4D5E6F7G8H", "…8 codes total…"]
}

POST/api/user/2fa/verify Auth

Confirm setup with a TOTP code from your authenticator app (or a backup code) to enable 2FA.

Query Parameters

Name	Type	Description
`code` body · required	`string`	6-digit TOTP code from your authenticator app

Request

bash

curl -X POST "https://api.socialintel.io/api/user/2fa/verify" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Response

json

{
  "success": true,
  "message": "2FA enabled successfully"
}

POST/api/user/2fa/disable Auth

Disable two-factor authentication for the account.

Response

json

{
  "success": true,
  "message": "2FA disabled"
}

API Keys

GET/api/keys Auth

List all API keys for the authenticated user.

Request

bash

curl "https://api.socialintel.io/api/keys" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "keys": [
    {
      "id": "key_...",
      "name": "My Key",
      "key_prefix": "sk_live_....",
      "scopes": ["datasets:read", "datasets:download"],
      "dataset_slugs": null,
      "last_used_at": "2026-01-15T10:00:00Z",
      "expires_at": null,
      "is_active": true,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "scopes_available": ["datasets:read", "datasets:download", "datasets:write", "exports:read", "exports:write", "webhooks:read", "webhooks:write", "stream:connect"]
}

POST/api/keys Auth

Create a new API key. Premium plan required. The raw key is returned once — save it, it will not be shown again.

Query Parameters

Name	Type	Description
`name` body · required	`string`	Friendly label for the key
`scopes` body	`array<string>`	Scopes (default: ["datasets:read","datasets:download"])
`dataset_slugs` body	`array<string>`	Restrict the key to specific dataset slugs

Request

bash

curl -X POST "https://api.socialintel.io/api/keys" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Production key", "scopes": ["datasets:read", "datasets:download"]}'

Response

json

{
  "success": true,
  "key": { "id": "key_...", "name": "My Key", "key": "sk_live_...", "created_at": "..." },
  "message": "Save this key — it will not be shown again."
}

GET/api/keys/{key_id} Auth

Get details for a specific API key.

Query Parameters

Name	Type	Description
`key_id` path · required	`string`	ID of the key

Request

bash

curl "https://api.socialintel.io/api/keys/key_..." \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "key": { "id": "key_...", "name": "My Key", "key_prefix": "sk_live_....", "scopes": ["datasets:read"], "is_active": true }
}

PATCH/api/keys/{key_id} Auth

Update an API key: rename it, change scopes, restrict dataset slugs, or deactivate it.

Query Parameters

Name	Type	Description
`key_id` path · required	`string`	ID of the key
`name` body	`string`	New label
`scopes` body	`array<string>`	Replace the key scopes
`dataset_slugs` body	`array<string>`	Restrict the key to specific dataset slugs
`is_active` body	`boolean`	Deactivate or reactivate the key

Request

bash

curl -X PATCH "https://api.socialintel.io/api/keys/key_..." \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Production key (updated)", "is_active": true}'

Response

json

{
  "success": true,
  "message": "API key updated"
}

DELETE/api/keys/{key_id} Auth

Revoke an API key immediately. The key will no longer work.

Query Parameters

Name	Type	Description
`key_id` path · required	`string`	ID of the key to revoke

Request

bash

curl -X DELETE "https://api.socialintel.io/api/keys/key_..." \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "message": "API key revoked"
}

Webhooks

GET/api/webhooks Auth

List all registered webhooks for your account.

Request

bash

curl "https://api.socialintel.io/api/webhooks" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "webhooks": [
    {
      "id": "wh_...",
      "name": "My webhook",
      "url": "https://example.com/hook",
      "events": ["dataset.updated", "dataset.new_rows"],
      "dataset_slugs": null,
      "filters": null,
      "is_active": true,
      "last_triggered_at": null,
      "failure_count": 0,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "events_available": ["dataset.updated", "dataset.new_rows", "custom_dataset.ready", "export.complete"]
}

POST/api/webhooks Auth

Register a new webhook endpoint to receive event notifications. Pro plan required. Returns a secret preview — save it, it will not be shown again.

Query Parameters

Name	Type	Description
`name` body · required	`string`	Friendly name for the webhook
`url` body · required	`string`	HTTPS endpoint URL
`events` body · required	`array<string>`	Event types to subscribe to (at least one). Available: dataset.updated, dataset.new_rows, custom_dataset.ready, export.complete
`dataset_slugs` body	`array<string>`	Only fire events for these dataset slugs
`filters` body	`object`	Optional event filters

Request

bash

curl -X POST "https://api.socialintel.io/api/webhooks" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My webhook", "url": "https://example.com/hook", "events": ["dataset.updated", "dataset.new_rows"], "dataset_slugs": ["ai-model-release-sentiment"]}'

Response

json

{
  "success": true,
  "webhook": { "id": "wh_...", "name": "...", "url": "https://example.com/hook", "active": true, "secret_preview": "abc12345..." },
  "message": "Save the secret — it will not be shown again."
}

GET/api/webhooks/{webhook_id} Auth

Get details for a specific webhook registration.

Query Parameters

Name	Type	Description
`webhook_id` path · required	`string`	ID of the webhook

Request

bash

curl "https://api.socialintel.io/api/webhooks/wh_..." \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "webhook": {
    "id": "wh_...",
    "name": "My webhook",
    "url": "https://example.com/hook",
    "events": ["dataset.updated"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

PATCH/api/webhooks/{webhook_id} Auth

Update a webhook: rename, change URL, events, dataset filters, or pause delivery.

Query Parameters

Name	Type	Description
`webhook_id` path · required	`string`	ID of the webhook
`name` body	`string`	New friendly name
`url` body	`string`	New HTTPS endpoint URL
`events` body	`array<string>`	Replace subscribed events
`dataset_slugs` body	`array<string>`	Replace the dataset slug restriction
`is_active` body	`boolean`	Pause or resume the webhook

Request

bash

curl -X PATCH "https://api.socialintel.io/api/webhooks/wh_..." \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"events": ["dataset.updated", "export.complete"], "is_active": true}'

Response

json

{
  "success": true,
  "message": "Webhook updated"
}

GET/api/webhooks/{webhook_id}/deliveries Auth

List delivery attempts (successes and failures) for a webhook, newest first.

Query Parameters

Name	Type	Description
`webhook_id` path · required	`string`	ID of the webhook
`limit` query	`integer`	Max deliveries (1–200, default 50)
`offset` query	`integer`	Pagination offset (default 0)

Request

bash

curl "https://api.socialintel.io/api/webhooks/wh_.../deliveries?limit=10" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "deliveries": [
    { "id": "del_...", "event": "dataset.updated", "status": "delivered", "attempts": 1, "delivered_at": "2026-08-11T10:00:00Z" }
  ],
  "total": 1
}

DELETE/api/webhooks/{webhook_id} Auth

Delete a webhook and stop receiving notifications.

Query Parameters

Name	Type	Description
`webhook_id` path · required	`string`	ID of the webhook

Request

bash

curl -X DELETE "https://api.socialintel.io/api/webhooks/wh_..." \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "message": "Webhook deleted"
}

POST/api/webhooks/{webhook_id}/test Auth

Send a test payload to a registered webhook URL.

Query Parameters

Name	Type	Description
`webhook_id` path · required	`string`	ID of the webhook

Request

bash

curl -X POST "https://api.socialintel.io/api/webhooks/wh_.../test" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "message": "Test event sent to endpoint"
}

Scheduled Exports

Pro plan feature. Automatically export a dataset on a schedule and deliver it by email, S3, or webhook. The first schedule runs immediately; schedules are limited per tier (default 5).

GET/api/exports/schedules Auth

List all scheduled exports for the account.

Response

json

{
  "success": true,
  "schedules": [
    {
      "id": "sched_...",
      "name": "Weekly AI sentiment",
      "dataset_slug": "ai-model-release-sentiment",
      "format": "csv",
      "schedule_config": { "frequency": "weekly", "time": "02:00", "day_of_week": 1 },
      "delivery_method": "email",
      "delivery_config": { "method": "email", "email": "user@example.com" },
      "is_active": true,
      "next_run_at": "2026-08-18T02:00:00Z"
    }
  ],
  "total": 1
}

POST/api/exports/schedules Auth

Create a new scheduled export. Requires a verified email and the Pro plan.

Query Parameters

Name	Type	Description
`name` body · required	`string`	Schedule name
`dataset_slug` body · required	`string`	Dataset to export
`format` body	`string`	csv \| json \| jsonl \| parquet (default: csv)
`schedule.frequency` body · required	`string`	daily \| weekly \| monthly
`schedule.time` body	`string`	HH:MM run time (default 02:00)
`schedule.day_of_week` body	`integer`	0–6 (weekly only)
`schedule.day_of_month` body	`integer`	1–31 (monthly only)
`delivery.method` body · required	`string`	email \| s3 \| webhook
`delivery.email` body	`string`	Required for email delivery
`delivery.s3_path` body	`string`	Required for s3 delivery
`delivery.webhook_url` body	`string`	Required for webhook delivery (HTTPS, public IP)
`filters` body	`object`	Row filters
`field_selection` body	`array<string>`	Fields to include

Request

bash

curl -X POST "https://api.socialintel.io/api/exports/schedules" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekly AI sentiment", "dataset_slug": "ai-model-release-sentiment", "format": "csv", "schedule": {"frequency": "weekly", "time": "02:00", "day_of_week": 1}, "delivery": {"method": "email", "email": "user@example.com"}}'

Response

json

{
  "success": true,
  "schedule": { "id": "sched_...", "name": "Weekly AI sentiment", "dataset_slug": "ai-model-release-sentiment", "next_run_at": "2026-08-18T02:00:00Z" }
}

GET/api/exports/schedules/{schedule_id} Auth

Get details for a specific export schedule.

Query Parameters

Name	Type	Description
`schedule_id` path · required	`string`	Schedule ID

Response

json

{
  "success": true,
  "schedule": { "id": "sched_...", "name": "Weekly AI sentiment", "dataset_slug": "ai-model-release-sentiment", "is_active": true }
}

PATCH/api/exports/schedules/{schedule_id} Auth

Update an export schedule (name, format, schedule, delivery, filters, is_active).

Query Parameters

Name	Type	Description
`schedule_id` path · required	`string`	Schedule ID
`name` body	`string`	New name
`format` body	`string`	csv \| json \| jsonl \| parquet
`schedule` body	`object`	New schedule config (frequency, time, day_of_week/day_of_month)
`delivery` body	`object`	New delivery config (method, email/s3_path/webhook_url)
`is_active` body	`boolean`	Pause or resume

Request

bash

curl -X PATCH "https://api.socialintel.io/api/exports/schedules/sched_..." \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Response

json

{
  "success": true,
  "message": "Export schedule updated"
}

DELETE/api/exports/schedules/{schedule_id} Auth

Delete an export schedule.

Query Parameters

Name	Type	Description
`schedule_id` path · required	`string`	Schedule ID

Request

bash

curl -X DELETE "https://api.socialintel.io/api/exports/schedules/sched_..." \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "message": "Export schedule deleted"
}

POST/api/exports/schedules/{schedule_id}/run-now Auth

Trigger an export immediately for a schedule.

Query Parameters

Name	Type	Description
`schedule_id` path · required	`string`	Schedule ID

Request

bash

curl -X POST "https://api.socialintel.io/api/exports/schedules/sched_.../run-now" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "message": "Export started"
}

Custom Datasets

POST/api/custom-dataset-requests Auth

Submit a custom dataset request. Enrichment runs in the background. Priced per row tier ($18–$68, +$11.98 privacy fee for private requests). Pro plan gets up to 50/month.

Query Parameters

Name	Type	Description
`platforms` body	`array<string>`	Array of platform names (e.g. ["reddit","youtube"]). Auto-selected if empty
`queries_raw` body	`string`	Seed queries to guide enrichment
`max_rows` body · required	`integer`	Maximum rows to collect — must form a valid tier with min_rows
`min_rows` body	`integer`	Minimum rows (tier lower bound, default 10000)
`name` body	`string`	Dataset name (auto-generated from description if empty)
`is_private` body	`boolean`	Private dataset (adds $11.98 privacy fee for non-Pro)

Request

bash

curl -X POST "https://api.socialintel.io/api/custom-dataset-requests" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "AI & ML trends 2026", "platforms": ["reddit", "youtube"], "queries_raw": "large language models, agentic AI", "min_rows": 10000, "max_rows": 25000, "is_private": false}'

Response

json

{
  "reference_id": "CDR-...",
  "status": "pending",
  "message": "Request submitted. AI enrichment in progress.",
  "poll_url": "/custom-dataset-requests/CDR-.../status",
  "min_rows": 10000,
  "max_rows": 25000,
  "price": 18.0,
  "requires_payment": true
}

GET/api/custom-dataset-requests/{reference_id}/status Auth

Check the processing status and result metadata of a custom dataset request.

Query Parameters

Name	Type	Description
`reference_id` path · required	`string`	Reference ID returned from request creation

Request

bash

curl "https://api.socialintel.io/api/custom-dataset-requests/CDR-.../status" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "reference_id": "CDR-...",
  "status": "processing",
  "name": "My Custom Dataset",
  "platforms": ["reddit"],
  "min_rows": 10000,
  "max_rows": 25000,
  "record_count": 0,
  "price": 18.0,
  "requires_payment": true,
  "error": null
}

GET/api/custom-dataset-requests Auth

List the current user's custom dataset requests with status, price, and files-ready flags.

Query Parameters

Name	Type	Description
`status` query	`string`	Filter by status (pending \| processing \| done \| failed \| cancelled)
`limit` query	`integer`	Max results (1–200, default 50)

Request

bash

curl "https://api.socialintel.io/api/custom-dataset-requests?status=done" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "requests": [
    { "reference_id": "CDR-...", "name": "AI & ML trends 2026", "platforms": ["reddit", "youtube"], "status": "done", "slug": "ai-ml-trends-2026", "record_count": 18400, "price": 18.0, "requires_payment": false, "files_ready": true }
  ],
  "total": 1,
  "plan": "pro",
  "monthly_limit": "50"
}

GET/api/custom-dataset-requests/check-slug Auth

Check whether a dataset slug is available for a custom dataset (not used by a catalog dataset, an existing custom dataset, or a pending request).

Query Parameters

Name	Type	Description
`slug` query · required	`string`	Slug to check

Request

bash

curl "https://api.socialintel.io/api/custom-dataset-requests/check-slug?slug=ai-ml-trends-2026" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "available": true,
  "message": "Slug 'ai-ml-trends-2026' is available."
}

PUT/api/custom-dataset-requests/{reference_id}/edit Auth

Update AI-generated enrichment fields (slug, category, description, search_queries, platforms, is_private) after review. Query count may be trimmed by up to 5%, platforms by up to 20%.

Query Parameters

Name	Type	Description
`reference_id` path · required	`string`	Reference ID
`slug` body	`string`	New dataset slug
`slug_aliases` body	`array<string>`	Alias slugs
`category` body	`string`	One of the valid dataset categories
`description` body	`string`	Dataset description
`search_queries` body	`array<string>`	Enrichment search queries
`platforms` body	`array<string>`	Platforms to include
`is_private` body	`boolean`	Make the dataset private

Request

bash

curl -X PUT "https://api.socialintel.io/api/custom-dataset-requests/CDR-.../edit" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"category": "AI & Technology", "search_queries": ["agentic AI", "LLM agents"]}'

Response

json

{
  "reference_id": "CDR-...",
  "status": "processing",
  "slug": "ai-ml-trends-2026",
  "category": "AI & Technology",
  "search_queries": ["agentic AI", "LLM agents"],
  "query_count": 2,
  "record_count": 0,
  "price": 18.0,
  "requires_payment": true
}

POST/api/custom-dataset-requests/{reference_id}/cancel Auth

Cancel a pending or processing enrichment request.

Query Parameters

Name	Type	Description
`reference_id` path · required	`string`	Reference ID

Request

bash

curl -X POST "https://api.socialintel.io/api/custom-dataset-requests/CDR-.../cancel" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "reference_id": "CDR-...",
  "status": "cancelled",
  "price": 0,
  "requires_payment": false
}

GET/api/custom-dataset-requests/{reference_id}/download Auth

Download a finished custom dataset file. Free for sample (100 rows) and for Pro users; otherwise requires the dataset to be purchased (402 otherwise).

Query Parameters

Name	Type	Description
`reference_id` path · required	`string`	Reference ID
`fmt` query	`string`	csv \| json \| jsonl \| parquet (default: csv)
`sample` query	`boolean`	true returns a 100-row sample

Request

bash

curl "https://api.socialintel.io/api/custom-dataset-requests/CDR-.../download?fmt=csv" \
  -H "X-API-Key: sk_live_..." \
  -o dataset.csv

Response

json

# 200 — file download
# 402 — payment required (non-Pro, dataset not purchased)
# 425 — dataset still being processed

GET/api/custom-dataset-requests/{reference_id}/model-card Auth

Return pre-computed model-card data (topic distribution + field coverage) for a custom dataset.

Query Parameters

Name	Type	Description
`reference_id` path · required	`string`	Reference ID

Request

bash

curl "https://api.socialintel.io/api/custom-dataset-requests/CDR-.../model-card" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "topics": [ { "topic": "AI agents", "count": 5120 } ],
  "field_coverage": { "id": 1.0, "content": 1.0, "sentiment_score": 0.88 },
  "platform_breakdown": [ { "platform": "reddit", "count": 18400 } ]
}

Payments & Billing

GET/api/payments/plans Auth

Return available plans (free, individual, pro monthly/yearly) with pricing and features. Processed via PayPal.

Request

bash

curl "https://api.socialintel.io/api/payments/plans" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "currency": "USD",
  "processor": "paypal",
  "plans": {
    "free": { "name": "Free", "price": 0 },
    "individual": { "name": "Individual", "price": 18.0 },
    "pro_monthly": { "name": "Pro — Monthly", "price": 39.0, "recurrence": "month", "popular": true },
    "pro_yearly": { "name": "Pro — Yearly", "price": 390.0, "recurrence": "year" }
  }
}

GET/api/payments/config Auth

Return the PayPal client configuration for the frontend SDK.

Request

bash

curl "https://api.socialintel.io/api/payments/config" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "processor": "paypal",
  "client_id": "AYzS...",
  "mode": "live"
}

POST/api/payments/create-order Auth

Create a PayPal order for a dataset purchase, a plan purchase, or a custom dataset payment. Returns an approval URL for the PayPal flow.

Query Parameters

Name	Type	Description
`dataset_slug` body	`string`	Slug of the dataset to buy (one-time)
`plan_key` body	`string`	Plan to buy: pro_monthly \| pro_yearly
`custom_reference_id` body	`string`	Reference ID for a custom dataset payment
`amount` body	`number`	Explicit amount (custom datasets)
`plan_config` body	`object`	Custom Pro limits

Request

bash

curl -X POST "https://api.socialintel.io/api/payments/create-order" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"dataset_slug": "ai-model-release-sentiment"}'

Response

json

{
  "success": true,
  "approval_url": "https://www.paypal.com/checkoutnow?token=...",
  "order_id": "8A...",
  "reference_id": "order_usr_..._...",
  "amount_usd": 28.0,
  "description": "ai-model-release-sentiment",
  "is_onetime": true
}

POST/api/payments/capture-order Auth

Confirm a completed PayPal order and grant access. Call this after the buyer approves the PayPal checkout.

Query Parameters

Name	Type	Description
`paypal_order_id` body · required	`string`	PayPal order ID
`reference_id` body · required	`string`	Reference ID returned by create-order

Request

bash

curl -X POST "https://api.socialintel.io/api/payments/capture-order" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"paypal_order_id": "8A...", "reference_id": "order_usr_..._..."}'

Response

json

{
  "success": true,
  "status": "COMPLETED",
  "payment_id": "8A...",
  "paypal_order_id": "8A...",
  "order_id": "order_usr_..._...",
  "amount_usd": 28.0
}

POST/api/payments/start-trial Auth

Start a 7-day free Pro trial. No payment is collected. Requires a verified email; one trial per account.

Query Parameters

Name	Type	Description
`plan_key` body · required	`string`	pro_monthly \| pro_yearly

Request

bash

curl -X POST "https://api.socialintel.io/api/payments/start-trial" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"plan_key": "pro_monthly"}'

Response

json

{
  "success": true,
  "trial_end": "2026-08-18T10:00:00Z",
  "plan": "pro_monthly",
  "message": "Trial started. No payment collected."
}

POST/api/payments/change-plan Auth

Self-serve plan change. Only a pro → free downgrade is supported; upgrades require purchasing via /pricing.

Query Parameters

Name	Type	Description
`target_plan` body · required	`string`	free \| pro_monthly \| pro_yearly

Request

bash

curl -X POST "https://api.socialintel.io/api/payments/change-plan" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"target_plan": "free"}'

Response

json

{
  "success": true,
  "message": "Downgraded to Free plan."
}

GET/api/payments/purchases Auth

List the user's active purchases with dataset names, platforms, and amounts. Includes Pro-granted dataset slugs.

Request

bash

curl "https://api.socialintel.io/api/payments/purchases" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "purchases": [
    { "dataset_slug": "ai-model-release-sentiment", "name": "AI Model Release Sentiment", "platform": "Reddit", "payment_id": "...", "amount_usd": 28.0, "purchase_type": "onetime", "purchased_at": "2026-08-01T10:00:00Z" }
  ],
  "granted_dataset_slugs": []
}

GET/api/payments/subscription Auth

Return the current subscription details (plan, status, period end, price, manage URL) or null when on the free plan.

Request

bash

curl "https://api.socialintel.io/api/payments/subscription" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "subscription": {
    "plan": "pro",
    "plan_key": "pro_monthly",
    "status": "active",
    "current_period_end": "2026-09-01T10:00:00Z",
    "subscription_started": "2026-08-01T10:00:00Z",
    "manage_url": "https://www.socialintel.io/billing",
    "price": 39.0,
    "plan_config": {}
  }
}

GET/api/payments/access/{slug} Auth

Check whether the current user has download access to a dataset and why (pro_plan, trial, purchased, granted, or not_purchased).

Query Parameters

Name	Type	Description
`slug` path · required	`string`	Dataset slug

Request

bash

curl "https://api.socialintel.io/api/payments/access/ai-model-release-sentiment" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "has_access": false,
  "reason": "not_purchased",
  "upgrade_url": "/pricing"
}

GET/api/orders Auth

Return the user's order history (dataset purchases and subscription payments) as a bare array.

Request

bash

curl "https://api.socialintel.io/api/orders" \
  -H "X-API-Key: sk_live_..."

Response

json

[
  { "order_id": "ord_...", "item_name": "ai-model-release-sentiment", "amount": 28.0, "currency": "USD", "status": "completed", "purchase_type": "onetime", "created_at": "2026-08-01T10:00:00Z", "download_url": "/api/datasets/download/ai-model-release-sentiment" }
]

GET/api/orders/{order_id}/invoice Auth

Return an HTML receipt for a completed order (downloadable attachment).

Query Parameters

Name	Type	Description
`order_id` path · required	`string`	Order ID

Request

bash

curl "https://api.socialintel.io/api/orders/ord_.../invoice" \
  -H "X-API-Key: sk_live_..." -o receipt.html

Response

json

# 200 — HTML receipt
# Content-Disposition: attachment; filename=receipt-....html

GET/api/subscriptions Auth

Return the user's active subscriptions (dataset subscriptions and the Pro plan) as a bare array.

Request

bash

curl "https://api.socialintel.io/api/subscriptions" \
  -H "X-API-Key: sk_live_..."

Response

json

[
  { "id": "usr_...", "type": "pro_plan", "dataset_slug": null, "dataset_name": "Pro Plan — Monthly (All Datasets)", "status": "active", "amount": 39.0, "cancel_url": "/api/subscriptions/pro/cancel" }
]

POST/api/subscriptions/pro/cancel/send-otp Auth

Email a one-time verification code used to confirm cancelling the Pro plan.

Response

json

{
  "success": true,
  "message": "Verification code sent to your email."
}

POST/api/subscriptions/pro/cancel Auth

Cancel the Pro plan. Only available within the 7-day risk-free trial window; a 95% refund is issued automatically. Max 4 cancellations per calendar year. Confirmed by an emailed OTP.

Query Parameters

Name	Type	Description
`otp_code` body · required	`string`	6-digit code from /api/subscriptions/pro/cancel/send-otp

Request

bash

curl -X POST "https://api.socialintel.io/api/subscriptions/pro/cancel" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"otp_code": "483920"}'

Response

json

{
  "success": true,
  "message": "Pro plan canceled. You are within the 7-day risk-free trial period — $37.05 (95% of purchase price) has been refunded to your PayPal account."
}

POST/api/subscriptions/{subscription_id}/cancel Auth

Cancel a dataset subscription via PayPal. Confirmed by an emailed OTP.

Query Parameters

Name	Type	Description
`subscription_id` path · required	`string`	Subscription ID (from /api/subscriptions)
`otp_code` body · required	`string`	6-digit code from /api/subscriptions/pro/cancel/send-otp

Request

bash

curl -X POST "https://api.socialintel.io/api/subscriptions/sub_.../cancel" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"otp_code": "483920"}'

Response

json

{
  "success": true,
  "message": "Subscription cancelled"
}

Notifications

GET/api/notifications Auth

List in-app notifications for the current user, newest first.

Query Parameters

Name	Type	Description
`limit` query	`integer`	Max results (1–100, default 50)
`unread_only` query	`boolean`	Only unread notifications (default false)

Request

bash

curl "https://api.socialintel.io/api/notifications?limit=20" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "notifications": [
    { "id": "notif_...", "title": "Custom dataset ready", "body": "Your dataset is ready to download.", "is_read": false, "created_at": "2026-08-11T10:00:00Z" }
  ]
}

POST/api/notifications/{notification_id}/read Auth

Mark a single notification as read.

Query Parameters

Name	Type	Description
`notification_id` path · required	`string`	Notification ID

Response

json

{
  "success": true
}

POST/api/notifications/read-all Auth

Mark all notifications as read.

Response

json

{
  "success": true
}

GET/api/notifications/unread-count Auth

Return the number of unread notifications.

Response

json

{
  "success": true,
  "unread_count": 3
}

Contact & Feedback

POST/api/contactPublic

Send a message to the Social Intel support team. We respond within 24 hours. Requires a Cloudflare Turnstile token.

Query Parameters

Name	Type	Description
`name` body · required	`string`	Your name
`email` body · required	`string`	Your email address
`message` body · required	`string`	Message body
`subject` body	`string`	Message subject
`cf_turnstile_response` body · required	`string`	Cloudflare Turnstile token (400 without it)

Request

bash

curl -X POST "https://api.socialintel.io/api/contact" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@example.com", "subject": "Billing question", "message": "I have a question about my invoice.", "cf_turnstile_response": "0.aAAAA..."}'

Response

json

{
  "success": true,
  "message": "Message received. We'll get back to you within 24 hours."
}

GET/api/feedback Auth

List the current user's own feedback submissions.

Query Parameters

Name	Type	Description
`status` query	`string`	open \| acknowledged \| implemented \| closed
`limit` query	`integer`	Max results (1–100, default 20)
`offset` query	`integer`	Pagination offset

Request

bash

curl "https://api.socialintel.io/api/feedback" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "feedback": [
    { "id": "fb_...", "category": "feature_request", "body": "Add more platforms.", "status": "open", "rating": 5, "is_public": false, "created_at": "2026-08-01T10:00:00Z" }
  ],
  "total": 1
}

POST/api/feedback Auth

Submit feedback. Requires a Cloudflare Turnstile token. Quality public feedback may earn gifts.

Query Parameters

Name	Type	Description
`category` body · required	`string`	general \| bug \| feature_request \| improvement \| testimonial \| other
`body` body · required	`string`	Feedback text (10–5000 chars)
`rating` body	`integer`	1–5 stars
`is_public` body	`boolean`	Allow it to be shown on the public wall
`cf_turnstile_response` body	`string`	Cloudflare Turnstile token

Request

bash

curl -X POST "https://api.socialintel.io/api/feedback" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"category": "feature_request", "body": "I would love a Parquet sample option.", "rating": 5, "is_public": true, "cf_turnstile_response": "0.aAAAA..."}'

Response

json

{
  "success": true,
  "feedback": { "id": "fb_...", "category": "feature_request", "status": "open" },
  "message": "Thank you for your feedback!"
}

GET/api/feedback/publicPublic

List public feedback submissions (no authentication required).

Response

json

{
  "success": true,
  "feedback": [ { "id": "fb_...", "category": "testimonial", "body": "Love this platform.", "status": "implemented" } ],
  "total": 1
}

GET/api/feedback/gifts Auth

List gifts awarded to the current user for quality feedback.

Response

json

{
  "success": true,
  "gifts": [ { "id": "gift_...", "kind": "api_calls", "amount": 500, "granted_at": "2026-08-01T10:00:00Z" } ],
  "total": 1
}

Referrals

GET/api/referrals Auth

Return the current user's referral code, referred-user count, and current/next reward tier.

Request

bash

curl "https://api.socialintel.io/api/referrals" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "referral_code": "ref_abc...",
  "referral_link": "https://www.socialintel.io/?ref=abc...",
  "total_referred": 12,
  "referred_count": 12,
  "current_tier": { "label": "Bronze", "min_referred": 10, "custom_datasets_limit": 1, "api_keys": 1, "api_calls_per_day": 2000 },
  "next_tier": { "label": "Silver", "min_referred": 50, "needed": 38 }
}

POST/api/referrals/generate-code Auth

Generate a one-time referral code for the current user.

Request

bash

curl -X POST "https://api.socialintel.io/api/referrals/generate-code" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "referral_code": "ref_abc..."
}

POST/api/referrals/claim-rewards Auth

Claim all pending referral rewards. Grants or upgrades Pro access with tiered limits based on how many users you referred.

Request

bash

curl -X POST "https://api.socialintel.io/api/referrals/claim-rewards" \
  -H "X-API-Key: sk_live_..."

Response

json

{
  "success": true,
  "claimed": 2,
  "tier": { "label": "Bronze", "min_referred": 10, "custom_datasets_limit": 1, "api_keys": 1, "api_calls_per_day": 2000 }
}

Chat Assistant

POST/api/chat Auth

Send a message to the Social Intel AI assistant and get a reply. Maintains conversation history for context.

Query Parameters

Name	Type	Description
`message` body · required	`string`	User message (max 2000 chars)
`history` body	`array<object>`	Prior messages [{role, content}], max 20
`stream` body	`boolean`	Reserved for future streaming (default false)

Request

bash

curl -X POST "https://api.socialintel.io/api/chat" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Which plan includes scheduled exports?", "history": []}'

Response

json

{
  "success": true,
  "message": "Scheduled exports are included in the Pro plan (from $39/month or $390/year).",
  "role": "assistant",
  "model": "openai/gpt-oss-120b",
  "usage": { "prompt_tokens": 120, "completion_tokens": 40, "total_tokens": 160 }
}

Error Codes

Status

Meaning

200

OK — request succeeded

400

Bad Request — invalid parameters

401

Unauthorized — missing or invalid API key

403

Forbidden — not authorized or plan too low

404

Not Found — dataset slug does not exist

422

Unprocessable — validation error

429

Rate Limited — slow down requests

500

Server Error — contact support

Dataset Catalog

Browse all

Slug

Platform

Records

Price

5g-and-connectivity-infrastructure-discussion

Arxiv, GitHub, GitLab +27 more

—

Free

academic-research-integrity-discourse

Arxiv, GitHub, GitLab +13 more

—

Free

addiction-and-recovery-community-signals

Reddit, YouTube, Mastodon +12 more

—

Free

advertising-and-media-buying-community

Product Hunt, Indie Hackers, G2 +22 more

—

Free

ageing-population-and-eldercare-discourse

Reddit, YouTube, Mastodon +18 more

—

Free

ai-developer-tools-adoption

Arxiv, GitHub, GitLab +27 more

—

Free

ai-ethics-and-safety-debate

Arxiv, GitHub, GitLab +27 more

—

Free

ai-in-education-community-debate

Arxiv, GitHub, GitLab +13 more

—

Free

ai-in-healthcare-professional-discourse

Arxiv, GitHub, GitLab +27 more

—

Free

ai-job-market-and-skills-demand

Arxiv, GitHub, GitLab +27 more

—

Free

ai-model-release-sentiment

Arxiv, GitHub, GitLab +27 more

—

Free

ai-startup-funding-and-news

Arxiv, GitHub, GitLab +27 more

—

Free

alt-platform-echo-chambers-and-radicalisation

Mastodon, Bluesky, Misskey +8 more

—

Free

augmented-and-virtual-reality-discourse

Arxiv, GitHub, GitLab +27 more

—

Free

b2b-saas-and-enterprise-software-discourse

Product Hunt, Indie Hackers, G2 +22 more

—

Free

+ 110 more datasets — see catalog endpoint

Stuck on something?

Questions about the API? We respond within 24 hours.

Contact Support Browse Datasets