---
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://convo-mail-sync.convo-mail-sync.workers.dev/docs
last-updated: 2026-10-27
---

# Open Media API documentation

Base URL: `https://convo-mail-sync.convo-mail-sync.workers.dev`. All responses are JSON unless stated. The machine-readable description is [OpenAPI 3.1](https://convo-mail-sync.convo-mail-sync.workers.dev/v1/openapi.json); the [API catalog](https://convo-mail-sync.convo-mail-sync.workers.dev/.well-known/api-catalog) follows RFC 9727.

## Quick examples

```bash
curl "https://convo-mail-sync.convo-mail-sync.workers.dev/v1/feed?sources=open-media,farcaster&mode=raw"
curl "https://convo-mail-sync.convo-mail-sync.workers.dev/v1/search?q=videos%20about%20cooking%20today"
curl -H "Authorization: Bearer $OPEN_MEDIA_TOKEN" "https://convo-mail-sync.convo-mail-sync.workers.dev/v1/me"
```

## MCP servers

- `https://convo-mail-sync.convo-mail-sync.workers.dev/open/mcp`: public tools, no key.
- `https://convo-mail-sync.convo-mail-sync.workers.dev/account/mcp`: the person's account over OAuth 2.1 (the host signs them in with their email code once; scope `account`). The same tools as /me/mcp.
- `https://convo-mail-sync.convo-mail-sync.workers.dev/me/mcp`: the person's account, bearer token required. Money-moving tools preview first and need explicit confirmation.
- `https://convo-mail-sync.convo-mail-sync.workers.dev/docs/mcp`: search and read this documentation.
- `https://convo-mail-sync.convo-mail-sync.workers.dev/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 through a feed lens (raw, relevant, work or a shared one), each post with its “Why this?” reasons.
- `GET /v1/lenses`: Feed lenses: the built-in Raw, Relevant and Work and lenses people shared, each with its rules in plain words and what it may read.
- `GET /v1/lenses/{id}`: One feed lens and its manifest.
- `POST /v1/lenses/draft`: Write a feed lens from plain words, with what was and was not understood.
- `POST /v1/lenses/preview`: The public feed through a lens (an id, a manifest or plain words); nothing is saved.
- `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/profiles/{handle}/resume`: A person’s public professional profile as a resume page (JSON Resume “even” theme); add .json for JSON Resume or .yaml for RenderCV.
- `GET /v1/jobs?q=`: Open job posts on Open Media with pay, place and the employer’s apply link. Open Media never applies for anyone.
- `GET /v1/profile-preview?url=`: What a public https website says about its owner (name, work, skills, projects, links), with sources. Read-only; obeys robots.txt.
- `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.
- `GET /v1/listings/{postId}/checks`: What was checked on a listing: claims, outcomes, how many verified people agreed and the pages they cited.
- `GET /v1/transparency`: Monthly counts of listing checks, reports and decisions, with no personal data.

## 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/conversations/{id}/messages`: Messages in one conversation, newest last (limit, before).
- `POST /v1/me/media/videos`: Upload a video (raw MP4, MOV or WebM, at most 100 MB) to attach to a post.
- `POST /v1/me/realtime-token`: Your own short-lived session for live message updates through Supabase Realtime.
- `GET /v1/connected/me`: Every /v1/me route again, for apps that signed you in with “Sign in with Open Media” (OAuth); see ADR 0041.
- `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, service, event or job as a public post. It goes live at once and is checked in the background.
- `GET /v1/me/profile-fields`: Your profile fields (contact details, accounts on other networks), each with who may see it.
- `PUT /v1/me/profile-fields`: Replace your profile fields and who may see each one: everyone, connections or only me.
- `GET /v1/me/professional`: Your professional profile, and the same data as a JSON Resume document.
- `PUT /v1/me/professional`: Replace your professional profile: headline, experience, education, skills, links, open to work or hiring. It is public.
- `POST /v1/me/professional/import`: Fill your profile from LinkedIn’s profile PDF, its data-export files or a JSON Resume: proposals with sources, saved only the ones you choose.
- `POST /v1/me/professional/portfolio`: Fill your profile from your own website (consent: true): proposals from JSON Resume, JSON-LD, h-card and Open Graph, saved only the ones you choose.
- `POST /v1/me/career/tailor`: Draft your profile and a cover note for one job from your own profile only, with anything unsupported removed and listed.
- `POST /v1/me/career/application`: Draft the message to apply for a job with. Nothing is sent.
- `GET /v1/verification-tasks/next`: For human-verified people: a listing claim to check; answer with POST /v1/verification-tasks/{taskId} and cited quotes.
- `GET /v1/operator/review-queue`: For Open Media operators: held listings, hidden posts and appeals.
- `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.
- `GET /v1/me/lenses`: Your feed lenses.
- `POST /v1/me/lenses`: Save a feed lens, or share it publicly.
- `POST /v1/me/lenses/install`: Install a shared feed lens (a copy that is yours).
- `DELETE /v1/me/lenses/{key}`: Remove one of your feed lenses.
- `GET /v1/me/feed`: Your feed through a lens, using who you follow when the lens asks for it.
- `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; signed in, your own AI key from Settings → Open Media AI writes it.
- `POST /v1/translate`: Translate up to 20 texts into English (or another language), detecting each one’s language. Public text is cached by its hash; with private: true and your token, messages and email are translated without being stored.

## Plain-language questions (NLWeb)

`POST https://convo-mail-sync.convo-mail-sync.workers.dev/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://convo-mail-sync.convo-mail-sync.workers.dev/schemamap.xml) lists each page's type, and [`/feeds/posts.jsonl`](https://convo-mail-sync.convo-mail-sync.workers.dev/feeds/posts.jsonl) carries the newest public Open Media posts as JSON Lines.

## Agent registration

Agents may register at `POST https://convo-mail-sync.convo-mail-sync.workers.dev/agent/identity` (`{"type": "anonymous"}`) and exchange the returned assertion at `POST https://convo-mail-sync.convo-mail-sync.workers.dev/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://convo-mail-sync.convo-mail-sync.workers.dev/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).
