---
title: "YouSpot HTTP API"
description: "The endpoints YouSpot answers over plain HTTP: public profile data with no auth, and the MCP tool surface with a bearer token."
canonical: https://youspot.com/docs/api
last-updated: 2026-09-04
---

# 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. |

```bash
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.

```bash
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` 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.

```bash
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.