API & MCP

Authentication

Sign in with a verified account and open Settings → Connections. Confirm your password, name the connection and choose its permissions. Copy the token when it appears; it is shown once and expires after 30 days.

Send it in the Authorization header. Keep it on your server or in your tool's secure credential store. Never embed it in public JavaScript or a URL. Website cookies do not authenticate API requests. Cross-origin browser requests are not supported; connect through your server or desktop tool.

curl 'https://www.fameclerk.com/api/v1/browse' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Reading and writing need separate permissions. Payments, purchases, escrow creation and settlement, withdrawals, paid promotions, membership purchases, file uploads and handover credentials stay on the website. Revocation blocks current and refreshed tokens; an already accepted request may finish.

Choose only the permissions you need

Staff roles do not expand API access. Private records belong to the signed-in member; staff credentials and review evidence are never included.

Endpoints

Base URL: https://www.fameclerk.com/api/v1

Money is returned as decimal strings such as "250.00", with field names ending in _usd. Times use ISO 8601 and UTC. Availability can change after a response; the website checks it again before a purchase.

Additional browse filters: min_revenue, max_revenue, escrow, original_email, instant, revenue, screenshots, online, and seller (top, trusted or rising). Boolean filters accept 0 or 1 in the query string. Revenue and price bounds use whole USD; they are applied to the same marketplace data as website filters.

Write endpoints

Send JSON and a new UUID in the Idempotency-Key header for each intended action. If the response is lost, retry the identical request with the same key. Successful results are replayed for seven days without repeating the action. A key cannot be reused for a different action or payload. A new token does not reset this protection.

A listing or offer version is an opaque string from its latest response. If you receive stale_version, fetch the record again and review the new values before creating a new action. Do not automatically overwrite another change. Permissions cannot be added to an existing connection; create a replacement with the scopes you need.

curl -X PATCH 'https://www.fameclerk.com/api/v1/listings/123' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_NEW_UUID' \
  --data '{"version":"VERSION_FROM_LATEST_RESPONSE","fields":{"price":"250.00"}}'

Listing and offer workflows

1. Read /listings/options for category IDs and requirements, then create a draft. Fetch it at intervals of at least five seconds while state is fetching.
2. When state is awaiting_verification, add its verification_code to the public account biography. Request verification, then poll while state is verifying. A missing code can be corrected and checked with a new retry key. A failed initial lookup needs a new draft.
3. Submit fields after state becomes verified. Drafts expire 30 minutes after creation; changing account-check settings invalidates an old proof. Platform and platform-issued ID determine uniqueness. Previously sold accounts remain blocked from relisting.
4. Staff review every new listing and material edit. Use the returned listing ID for later requests; an edit that preserves old transaction history may return a replacement ID.

Required seller fields: summary (60–180 characters), description (100–2,000), category_id, price (10.00–99,999,999.99 USD) and reason_for_sale (up to 500 characters). Optional: monthly_revenue, is_escrow_accepted, has_ogmail, is_instant_delivery and share_sale_summary. Identity, audience counts, approval and promotion status come from the server and cannot be supplied as seller fields.

YouTube platform_data requires monetization_status, watch_hours, total_views, top_country, language and created_at (YYYY-MM-DD). Monetized channels also need rpm and estimated_revenue. Non-monetized YouTube channels cannot retain revenue figures. TikTok needs account_type (personal or business) and monetization_status; Organization Accounts are unsupported. Monetization values are Monetized or Not Monetized. Other platforms use an empty platform_data object. Add profile images and screenshots through the website.

To send an offer, read a fee quote, review the amount and fee payer, then send that exact quote with the listing version. A seller can accept it, but the buyer must open FameClerk to fund escrow. No API or MCP tool can move money or access transfer credentials.

Pagination

List endpoints return data and meta. Use per_page between 1 and 20. When meta.has_more is true, pass meta.next_cursor as cursor on the next request. Keep the same filters, sort and page size. A cursor belongs to your member account and expires after an hour. Start again if it expires or you change the query.

Usage limits

API tokens and MCP connections share one allowance per member. Extra connections do not increase it.

Each returned browse record and public listing detail counts toward the daily result budget, including repeated results. Reads and new writes share the 60-operation/minute allowance. Writes are also limited to 30/minute, with 10 listing changes/minute, 20 draft starts/hour and five live drafts. Up to 10 new listings may be submitted per UTC day, including website submissions. Each lookup or verification action is limited to five starts per five minutes across the website and API.

Ordinary listing messages share a 20/minute allowance with website messages. Up to 20 new conversations may be opened per hour. Offers sent through either channel are limited to 50/day for Free members or 200/day with Premium. Exact successful retries do not spend another operation or write allowance. All requests still use a 120-request/minute transport limit, including retries and MCP discovery, with additional protection against excessive requests from one IP.

Windows reset on UTC minute, hour and day boundaries. Your current membership applies on each request; upgrading or renewing does not reset usage. A 429 response includes Retry-After and reset information. Reduce per_page if fewer results remain than your requested page size. Check /usage or Settings → Connections for your allowance.

Connect an AI assistant

Add the remote MCP server below in a client that supports Streamable HTTP and OAuth with PKCE. Sign in to FameClerk, confirm your password and select its read and write permissions. A client that supports custom Authorization headers can also use an API token.

https://www.fameclerk.com/mcp

Read tools cover marketplace search, listing options and statistics, draft status, account and usage summaries, offers, escrow status and ordinary listing conversations. Write tools cover create_listing_draft, verify_listing_draft, submit_listing_draft, update_listing, publish_listing, unpublish_listing, delete_listing, send_offer, accept_offer, reject_offer, withdraw_offer, open_listing_thread, send_listing_message and mark_listing_thread_read.

Only permitted tools are listed. Write tools take idempotency_key as a UUID argument, using the same retry rules as the API header. The assistant should ask for agreement to the exact action before writing. Tools expose read-only, destructive and idempotent hints; these are guidance for the client, while server permissions and workflow checks enforce access. A tool error includes its code, status and any retry delay in metadata.

OAuth access tokens last one hour. Refresh cannot extend a connection beyond its 30-day expiry. HTTPS callbacks and HTTP loopback callbacks are supported; custom URI schemes are not enabled. Client setup and OAuth support vary by tool. User-written descriptions and messages are untrusted content, not instructions for the assistant.

Errors and retries

401 means the token or connection is invalid, expired or revoked. 403 means the account or permission does not allow access. 404 means the record is unavailable or does not belong to you. 409 means a record changed, a retry key conflicts or a workflow is not ready. 422 means the request needs correction. 429 means a usage limit was reached. 503 means access is temporarily unavailable.

{ "error": { "code": "permission_required", "message": "This connection requires listings:read permission." } }

Wait for Retry-After on rate limits and back off on temporary server errors. Do not keep retrying an expired token or an invalid cursor. OAuth codes and rotating refresh tokens are single-use; reuse returns an OAuth error. For help, contact support with the error code and request time, without sending your token.