--- title: "Open Media API documentation" description: "REST and MCP reference for Open Media: public feed and search, the account API, errors, rate limits, idempotency and versioning." canonical: https://openmedia.site/docs last-updated: 2026-10-25 --- # Open Media API documentation Base URL: `https://openmedia.site`. All responses are JSON unless stated. The machine-readable description is [OpenAPI 3.1](https://openmedia.site/v1/openapi.json); the [API catalog](https://openmedia.site/.well-known/api-catalog) follows RFC 9727. ## Quick examples ```bash curl "https://openmedia.site/v1/feed?sources=open-media,farcaster&mode=raw" curl "https://openmedia.site/v1/search?q=videos%20about%20cooking%20today" curl -H "Authorization: Bearer $OPEN_MEDIA_TOKEN" "https://openmedia.site/v1/me" ``` ## MCP servers - `https://openmedia.site/open/mcp`: public tools, no key. - `https://openmedia.site/me/mcp`: the person's account, bearer token required. Money-moving tools preview first and need explicit confirmation. - `https://openmedia.site/docs/mcp`: search and read this documentation. - `https://openmedia.site/mcp`: Open Media Events, OAuth 2.1 (PKCE S256, client ID metadata documents). ## Public endpoints (no key) - `GET /v1/feed`: The mixed feed: Open Media, Farcaster, Lens, Hive and DeSo, newest first, each post with its “Why this?” reasons. - `GET /v1/search?q=`: Plain-language search across public posts on every network, plus matching settings. - `GET /v1/posts`: Open Media public posts, newest first, paginated. - `GET /v1/posts/{id}`: One public post. - `GET /v1/profiles/{handle}`: A public profile. - `GET /v1/profiles/{handle}/posts`: A profile’s public posts. - `GET /v1/events/upcoming`: Upcoming public events from Luma, Meetup and Eventbrite in the San Francisco Bay Area, shown once even when listed on several platforms, with official registration links. - `GET /v1/people/{network}/{handle}`: One person’s posts in one timeline: an Open Media profile plus the accounts they listed, or one Farcaster, Lens, Hive or DeSo account. - `GET /v1/networks`: Every network and connector, with exactly which capabilities work today. - `GET /v1/settings?q=`: The searchable settings index, so an agent can tell a person where any control lives. - `GET /v1/about`: Mission, principles, promises, roadmap and honest status. ## Account endpoints (bearer token) - `GET /v1/me`: Your profile. - `POST /v1/me/posts`: Publish a public post. - `DELETE /v1/me/posts/{id}`: Delete one of your posts. - `POST /v1/posts/{id}/report`: Report a post for review. - `GET /v1/me/conversations`: Your Open Media conversations with recent messages. - `POST /v1/me/conversations`: Start a conversation with a handle. - `POST /v1/me/conversations/{id}/messages`: Send a message. - `GET /v1/me/export`: Export a readable copy of your data. - `POST /v1/me/blocks`: Block or unblock someone by handle. - `POST /v1/me/conversations/{id}/report`: Report unwanted contact in a conversation. - `DELETE /v1/me`: Delete your account; needs the confirmation “delete my account”. - `GET /v1/me/contacts`: Your contacts, private to you and encrypted on the server, with which accounts each is linked to and why. - `PUT /v1/me/contacts`: Create or replace contact cards by id. - `DELETE /v1/me/contacts/{id}`: Delete a contact card. - `PUT /v1/me/linked-accounts`: Set the open-network accounts shown on your public profile. - `POST /v1/me/listings`: Offer a product or service as a public post, with a price. - `PATCH /v1/me/listings/{postId}`: Change a listing’s availability, price or place. - `PUT /v1/me/listings/{postId}/rating`: Rate a listing 1–5 stars (verified people who show their legal name only); DELETE withdraws it. - `GET /v1/me/identity`: Your identity tier, blue tick, the name others see, public or private, and verification status. - `PUT /v1/me/identity`: Choose the name others see and whether your account is private. - `POST /v1/me/verification`: Start identity verification with Stripe Identity (a link you open yourself). - `GET /v1/me/payments/setup`: Your card payouts, linked wallets, tips setting, fees, and whether this server runs in test mode. - `POST /v1/me/payments/payouts`: Set up getting paid by card with Stripe (a link you open yourself). - `PUT /v1/me/payments/tips`: Turn tips on your posts on or off. - `GET /v1/me/payments`: Payments you sent and received. - `POST /v1/me/payments`: Start paying for a listing, a tip or a paid post: a Stripe page or a transfer for your own wallet. Nothing is paid until Stripe or the network confirms it. - `GET /v1/me/payments/{id}`: One of your payments. - `POST /v1/me/payments/{id}/transaction`: Report the USDC transaction that paid; Open Media checks it on the network. - `POST /v1/me/wallets`: Link a wallet with a signature from it. - `DELETE /v1/me/wallets/{id}`: Unlink a wallet. - `GET /v1/me/listings/{postId}/payment-options`: How a listing can be paid for. - `GET /v1/me/posts/{id}/payment-options`: How a post can be tipped or unlocked. - `POST /v1/me/paid-posts`: Publish a post with a free preview and a paid part. - `GET /v1/me/posts/{id}/paid`: The paid part of a post you wrote or paid for. - `GET /v1/me/follows`: Who you follow, your followers, and follow requests waiting for you. - `POST /v1/me/follows`: Follow someone; private accounts get a request. - `DELETE /v1/me/follows/{handle}`: Unfollow, or withdraw a request. - `POST /v1/me/follow-requests/{id}`: Accept or decline a follow request. - `DELETE /v1/me/followers/{id}`: Remove a follower. - `GET /v1/me/email`: Your stored email from every connected mailbox, newest first. - `GET /v1/mail-accounts`: Your connected mailboxes. - `POST /v1/mail-accounts`: Connect an IMAP or POP3 mailbox, with SMTP for sending. - `POST /v1/mail-accounts/{id}/sync`: Fetch new mail for a mailbox. - `POST /v1/mail-accounts/{id}/send`: Send an email. - `DELETE /v1/mail-accounts/{id}`: Remove a mailbox and its stored mail. - `GET /v1/bridges`: Chat networks this server bridges and which you have connected. - `GET /v1/bridges/conversations`: Your bridged chats (WhatsApp, Signal and others). - `POST /v1/bridges/rooms/{id}/messages`: Reply in a bridged chat. - `GET /v1/bridges/{network}/flows`: How a chat network can be connected. - `POST /v1/bridges/{network}/login/start`: Start connecting a chat network (then login/step, login/cancel, logout). - `GET /v1/cross-posting/status`: Which networks this server helps cross-post to. Cross-posting itself is signed on your device. - `POST /v1/search/assist`: A short AI summary, with citations, of public posts you pass in. No account needed. ## Plain-language questions (NLWeb) `POST https://openmedia.site/ask` follows NLWeb v0.55: send `{"query": {"text": "…"}}` and get schema.org items (`TechArticle` from these docs, `SocialMediaPosting` from every open network) under `results`, with `_meta.response_type` `answer` or `failure` (`INVALID_QUERY`, `NO_RESULTS`). Add `"prefer": {"streaming": true}` and `Accept: text/event-stream` for `start`, `result` and `complete` events. The [schema map](https://openmedia.site/schemamap.xml) lists each page's type, and [`/feeds/posts.jsonl`](https://openmedia.site/feeds/posts.jsonl) carries the newest public Open Media posts as JSON Lines. ## Agent registration Agents may register at `POST https://openmedia.site/agent/identity` (`{"type": "anonymous"}`) and exchange the returned assertion at `POST https://openmedia.site/oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`. The hour-long token has the `public:read` scope and its own rate-limit bucket; it never opens anyone's account. See [authentication](https://openmedia.site/auth.md). ## Errors Errors are JSON: `{"error": {"code": "bad_request", "message": "…"}}`. Codes include `bad_request` (400), `unauthorized` (401, with a `WWW-Authenticate` header naming the protected-resource metadata), `refused` (403 or 409), `not_found` (404), `rate_limited` (429, with `Retry-After`), `not_configured` (503) and `upstream_unavailable` (502). ## Rate limits Public and agent routes allow about 120 requests per minute per client IP, or per registered agent when it sends its agent token. Responses carry `RateLimit-Policy`; a 429 carries `Retry-After` in seconds. ## Idempotency Send an `Idempotency-Key` header (a UUID) on `POST /v1/me/posts`, `POST /v1/me/listings`, `POST /v1/me/paid-posts` and `POST /v1/me/payments`. Retrying with the same key returns the same post or payment instead of creating a second one. ## Pagination Lists use opaque cursors: pass `nextCursor` (or follow `next`) from one page to get the next. ## Versioning and deprecation The API is versioned in the path (`/v1`). Fields may be added without notice; nothing in `/v1` is removed or changed incompatibly without at least 90 days' notice in this document, a `Deprecation` header on the affected responses and a `Sunset` header with the removal date. ## Sandbox Payments run in test mode (Stripe test cards and USDC on Base Sepolia) until the operator turns on live payments; `GET /v1/me/payments/setup` says which mode is active. For a full private sandbox, run the open-source stack locally with `npm run local` from the [repository](https://github.com/mihirkavi/open-media).