Services

A service is platform/service: linkedin/profile.info, reddit/subreddit.posts, googlemaps/place.search. It is the unit of the API, with one endpoint, one input contract, one output shape.

POST /v1/{platform}/{service}

POST /v1/reddit/subreddit.posts
POST /v1/linkedin/profile.posts
POST /v1/googlemaps/place.search

The service name is both the public name and the machine id, so there is no separate label or slug to translate between.

Naming

Service names follow entity.verb, lowercase, and are idiomatic to their platform: Reddit has subreddit.posts, Facebook has group.posts, YouTube has channel.videos, Instagram has reel.info. Where a name means the same thing everywhere it stays the same (profile.info on nine platforms). Where a platform has a real idiom, the name follows the platform, not an artificial cross-platform vocabulary. Published names are frozen, so a service is never silently repurposed.

Input kind

Each service declares what it consumes:

Kind	Body field	Example
`url`	`urls` (array) or `url` (string)	`linkedin/profile.info`
`query`	`queries` (array) or `query` (string)	`googlemaps/place.search`, `linkedin/post.search`

There is no extract/search split any more: the input kind is a property of the service, published in the catalogue as input_kind / input_field. Sending queries to a URL service returns a 400 that names the field it actually wants.

Input formats

Each service declares the exact shape(s) it accepts, with a concrete example:

"accepts": [
  {
    "format": "https://www.reddit.com/r/<subreddit>",
    "example": "https://www.reddit.com/r/programming",
    "pattern": "reddit\\.com\\/r\\/[^\\/?#]+",
    "note": "A sort suffix (/hot, /new, /top, /rising) is accepted too."
  }
]

An input is valid if it matches any of the declared shapes. Validation happens at the edge, before routing and before billing: a company URL sent to profile.info returns 400 invalid_input_format and is never charged.

Typed options

Services declare their own parameters, with types and allowed values:

{
  "url": "https://www.reddit.com/r/programming",
  "options": { "sort": "top", "time": "week" }
}

Options are validated at the edge. An unknown key, a wrong type or an out-of-enum value returns a corrective 400 naming the valid options, and they are never silently dropped. The declared option surface is the same across a service’s offers, so a request stays valid when the router falls over. An offer that doesn’t implement an option ignores it.

Discovery

GET /v1/services: every callable service, with offers, prices, caps, accepted inputs and options.
GET /v1/services/{platform}: one platform.
GET /v1/services/{platform}/{service}: one service.
GET /v1/openapi.json: OpenAPI 3.1, one path per service.
socialrouter.io/services: the browsable catalogue.
Services by platform: the same catalogue written out as reference pages, one per platform.
The MCP server exposes the same catalogue as a list_services tool.

All of it is derived from the live registry. Nothing is hand-maintained, so a newly implemented service appears everywhere at once.

Errors are written to be fixed

Every 4xx names the field, the expected shape, and the valid alternatives:

{
  "error": {
    "code": "unknown_service",
    "message": "Unknown service \"group.posts\" on reddit. Did you mean \"reddit/subreddit.posts\"? Services on reddit: subreddit.posts, post.info, post.comments.",
    "type": "not_found",
    "did_you_mean": "reddit/subreddit.posts"
  }
}

That matters most for LLM agents, which self-correct in one round trip instead of guessing.

Offers & routing

Who implements a service, and how the router picks.

Run a service

The endpoint reference.

Getting started

Concepts

Best practices

Naming

Input kind

Input formats

Typed options

Discovery

Errors are written to be fixed

Offers & routing

Run a service

​Naming

​Input kind

​Input formats

​Typed options

​Discovery

​Errors are written to be fixed

Offers & routing

Run a service

Naming

Input kind

Input formats

Typed options

Discovery

Errors are written to be fixed