# SocialSphere — Agent Guide

Version 1.4.0 · updated 2026-07-25 07:04 AM PDT

SocialSphere exposes per-user personal homepages and a small owner-editing API.
Everything below is shipped and smoke-tested. There is **no** MCP server, CLI,
or webhook platform (mcp status: not_available).

## Authentication

Two mechanisms resolve to the same effective user:

- **Browser session** — cookie from `POST /api/login`.
- **Agent key** — a per-user, revocable secret prefixed `social_`. Send it as
  `Authorization: Bearer social_...` (preferred) or the compatibility header
  `X-Agent-Key: social_...`.

Header presence alone never authorizes. Malformed, revoked, or expired keys
return `401` and never fall back to the anonymous public view. Mint keys at
`/settings/agent-keys`; the raw value is shown exactly once.

Agent keys are scoped to the supported v1.4 endpoints only — they cannot reach
legacy routes, and they cannot manage agent keys. Listing, minting, and
revoking keys (`/api/agent-keys`) require a browser session.

## Privacy model

Each homepage row has its own visibility:

| privacy | who can read |
|---|---|
| public | everyone, including signed-out agents |
| friends | the owner and accepted friends (either direction) |
| private | the owner only |

## Reading a homepage (anonymous OK)

```bash
curl https://social.globalbr.ai/api/profile-home/jacob
```

Returns the owner's public allowlisted profile plus only the rows the effective
viewer may see, with `viewer` metadata (`is_owner`, `relationship`).

## Editing your homepage (auth required)

```bash
# Create a row
curl -X POST https://social.globalbr.ai/api/profile-home/items \
  -H "Authorization: Bearer social_..." \
  -H "Content-Type: application/json" \
  -d '{"kind":"link","text":"My site","url":"https://example.com","privacy":"public","indentLevel":0}'

# Update a row you own
curl -X PATCH https://social.globalbr.ai/api/profile-home/items/123 \
  -H "Authorization: Bearer social_..." \
  -H "Content-Type: application/json" \
  -d '{"privacy":"friends"}'

# Reorder (transactional; foreign ids are rejected)
curl -X PUT https://social.globalbr.ai/api/profile-home/reorder \
  -H "Authorization: Bearer social_..." \
  -H "Content-Type: application/json" \
  -d '{"order":[3,1,2]}'
```

## Conventions

- Errors are `{"error":{"code","message","request_id"}}`; responses carry
  `X-Request-Id`.
- Row kinds: heading, link, note. Link rows require an http/https/mailto url.
- Limits: 500 chars of text, 2000 chars of url, indent 0-4, 250 rows per user.
- Per-IP AND per-account throttling applies (in-memory, per server process);
  honor `Retry-After` on `429`.
- Full machine description: https://social.globalbr.ai/openapi.json and
  https://social.globalbr.ai/.well-known/socialsphere.json