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

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