Docs / YouSpot HTTP API

YouSpot HTTP API

The endpoints YouSpot answers over plain HTTP: public profile data with no auth, and the MCP tool surface with a bearer token.

Most programmatic work here goes through the MCP server, because that is where the tools live. These endpoints answer over plain HTTP for the cases where running an MCP client is not worth it.

Public, no auth

Endpoint	Returns
`GET /api/human/<username>`	A public member profile as JSON.
`GET /api/human/<username>.json`	The same profile, explicit extension.
`GET /api/human/<username>.md`	The same profile as markdown.
`GET /api/network/members`	A page of the public member directory.

curl https://youspot.com/api/human/dharmesh.json

Batch

POST /api/batch runs up to 20 GET requests against the read endpoints in one round trip. Each item comes back with its own status and body (or text for markdown), in the order sent, so one failing item never hides the others: the batch itself is 200 once the envelope is valid. Anything that is not a batchable read is refused per item with the allowlist attached. Each item still counts against its endpoint's own rate limit; the batch saves round trips, not budget.

curl -X POST https://youspot.com/api/batch \
  -H "Content-Type: application/json" \
  -d '{"requests":[
    {"id":"dir","path":"/api/network/members","query":{"q":"consulting","per_page":5}},
    {"id":"me","path":"/api/human/dharmesh"}
  ]}'
# 200 { "object": "batch", "count": 2, "responses": [ { "id": "dir", "status": 200, "body": {...} }, { "id": "me", "status": 200, "body": {...} } ] }

Sandbox

Every anonymous path here also answers under /sandbox, where /mcp/v1 becomes the demo-account MCP server: tools/call needs no credential and every tool that writes is refused. GET /sandbox describes the mount and says whether the demo account is seeded. The OAuth server and the endpoints that need a member are not mounted there.

Authenticated

The tool surface is reached by posting JSON-RPC to /mcp with a bearer token. tools/list enumerates it and tools/call runs one.

curl -X POST https://youspot.com/mcp \
  -H "Authorization: Bearer $YOUSPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_connections","arguments":{"query":"acme"}}}'

Errors

A missing or expired bearer gets 401 with a WWW-Authenticate: Bearer header naming the protected-resource metadata URL. A tool that fails returns a JSON-RPC result with isError set rather than an HTTP error, so a client can read what went wrong.

Rate limits

Tool calls are metered against the member's monthly credits. A member out of credits gets a clear error naming the limit rather than a silent failure.