API for developers

Read the directory from your own app or website. Every answer is JSON.

Getting a key

API keys are issued by the site team. Contact us and tell us what you are building.

Making a request

Send the key in the X-Api-Key header (or as Authorization: Bearer …). The base address is:

https://socialgroups.demo.pepploweb.com/api/v1

curl -H "X-Api-Key: YOUR_KEY" "https://socialgroups.demo.pepploweb.com/api/v1/links?platform=facebook&per_page=10"

Each key may make 60 requests per minute. Past that the answer is 429 with a Retry-After header.

Answers

{ "success": true, "data": [ … ], "meta": { "page": 1, "per_page": 20, "total": 134, "last_page": 7 } }
{ "success": false, "error": { "code": "invalid_key", "message": "This API key is not valid." } }

Endpoints

Request	What it returns
`GET /`	Name of the site and what your key may do.
`GET /platforms`	The social networks of this directory (Facebook, Instagram, X …), each with its colour, icon name, link types and number of links.
`GET /types`	The link types this directory accepts, each with its platform, label, colour, icon name, button text and count label.
`GET /categories`	All categories with their number of links.
`GET /links`	A page of links. See the filters below.
`GET /links/{slug}`	One link.
`POST /links`	Submit a link (keys with the “submit” permission).

Filters for `GET /links`

Parameter	Meaning
`q`	Search in names, descriptions and tags.
`platform`	One of: facebook, instagram, x, youtube, linkedin, reddit, discord, tiktok, pinterest, threads, snapchat, twitch, bluesky, other.
`type`	One of: facebook-group, facebook-page, facebook-link, instagram-profile, instagram-channel, instagram-link, x-profile, x-community, x-link, youtube-channel, youtube-link, linkedin-group, linkedin-page, linkedin-profile, reddit-community, discord-server, tiktok-profile, tiktok-link, pinterest-profile, threads-profile, snapchat-profile, twitch-channel, bluesky-profile, other-link.
`category`	Category slug or id. Sub-categories are included.
`country`	Two-letter country code, e.g. `IN`.
`language`	Language code, e.g. `en`.
`featured`	`1` to return featured links only.
`sort`	`newest` (default), `trending`, `popular`, `views` or `rating`.
`page`, `per_page`	Paging. `per_page` can be up to 50.

A link

{
  "slug": "daily-cricket-talk",
  "type": "facebook-group",
  "type_label": "Facebook group",
  "platform": "facebook",
  "title": "Daily Cricket Talk",
  "handle": null,
  "description": "Match previews, live score chat …",
  "image": null,
  "category": { "name": "Cricket", "slug": "cricket" },
  "tags": ["cricket", "ipl"],
  "country": "IN",
  "language": "en",
  "members": 8420,
  "views": 3063,
  "clicks": 1094,
  "featured": true,
  "verified": true,
  "page": "https://socialgroups.demo.pepploweb.com/link/daily-cricket-talk",
  "join": "https://socialgroups.demo.pepploweb.com/go/daily-cricket-talk",
  "added_at": "2026-10-06T09:12:00+00:00"
}

Send your visitors to join to open the link, or to page for the full details. handle is the public username (@name, r/name, in/name), or null for groups, posts, invites and other links without one. platform is the social network (facebook, instagram, x …). members is the number of members, followers or subscribers, depending on the type.

Submitting a link

curl -X POST "https://socialgroups.demo.pepploweb.com/api/v1/links" \
  -H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://www.facebook.com/groups/yourgroup", "category": "sports", "title": "My group", "tags": ["cricket"], "country": "IN", "language": "en"}'

Only url and category are needed when the name can be read from the link. The answer has the link's status: approved or pending (waiting for a moderator). A link that is already listed, not recognised or refused answers 422 with the reason.

Error codes

missing_key and invalid_key (401) · forbidden (403) · not_found (404) · invalid (422) · rate_limited (429).