For AI agents

The Pereval documentation is designed so that an AI agent (Claude Code, Cursor, Copilot, Codex and others) can write the integration. Give it context and a clear task — it will find the rest on its own.

Context files

Every documentation page has a “Copy for AI agent” button — it copies the page’s source text.

MCP

Point the agent at https://api.pereval.dating/mcp with Authorization: Bearer <key>. After initialize (protocol 2024-11-05) it can tools/list / tools/call. Same limits and errors as REST; tool failures come back with isError: true and a text code (invalid, not_found, …).

To send a super like from an enrolled spending account, call like with super: true and action_ref. Use the same reference and arguments when retrying. Place the order for the super like entitlement through REST. How orders and retries work.

Ready-made task prompt

Copy it and add a description of your project:

Task: connect our dating app to the Pereval network (pereval.dating) as a platform.

Context: read https://pereval.dating/llms-full.txt and the specification https://pereval.dating/openapi.yaml.
Our stack: <language, framework, database>. Users are stored in <table/model>.

Do the following:
1. Settings: two consent toggles — "Show me in the Pereval network" (off by default, with a link to pereval.dating)
   and "Open to chatting in other languages" — with the texts from the "Profiles and consents" section.
   Store the consent time and version.
2. Profile sync: PUT /v1/members/{our id} when participation is turned on and on any profile change;
   turned off — the same PUT with consent.network: false (hidden, chats go on); data erased from the network
   or account deleted — DELETE (or deactivate/restore if we give 30 days to restore). First upload in batches via PUT /v1/members.
   Save the network_id. On 409 location_change_limited, show the user a clear message.
3. Take the feed from the start that matches the product, not from this list:
   swipe app — /en/docs/guide-app/ (a skip is a dislike),
   search site — /en/docs/guide-site/ (pages use cursor, a dislike is only an explicit rejection),
   bot — /en/docs/guide-bot/ (events via GET /v1/events).
   Mark the profile as coming from the Pereval network. If the bio was translated, add an "AI-translated" label. The limit is remaining_today, 200 distinct people a day.
4. Likes: POST /v1/likes for network profiles; incoming likes from the like.received event,
   reconciliation via GET /v1/members/{id}/likes.
5. Conversations: on match.created, create a conversation (idempotently by match_id); messages via POST /v1/matches/{id}/messages
   and the message.created event, with a warning based on flags when suspicious is true; read receipts via
   POST /v1/matches/{id}/read and the message.read event; a clear message on 429 first_messages_limit;
   closing via match.closed (the chat is closed, history stays; with peer_deleted — without the name and photos);
   match.erased — delete the chat; match.frozen / match.unfrozen — freeze and unfreeze the chat.
6. Activity: POST /v1/activity in batches every few minutes for users who opened the app.
7. Receiving events: a webhook that verifies the X-Network-Signature signature (HMAC-SHA256 of the raw body),
   protects against duplicates by id and responds with 2xx; 503 if a message arrives before an unknown match; acknowledge known erasures as no-ops and never recreate erased chat.
   Without a webhook URL, pull GET /v1/events?after=<next_after> on a schedule and store next_after.
8. Blocking and reporting for network profiles: POST /v1/blocks, POST /v1/reports. On member.suspended — hide the person
   in our app until the reports are reviewed; if all is well — POST /v1/members/{id}/reinstate; on member.rejected — ask
   the user to fix the profile. Super likes (super, message) and the Worldwide feed (scope=world, consent.world) are optional.
9. Tests for event handling (signature, duplicates, event order).

Do not: store the API key in client-side code.
Keys: PEREVAL_API_KEY and PEREVAL_WEBHOOK_SECRET — from environment variables (issued in the platform dashboard).

Tips

• Ask the agent to read Events and webhooks and Errors and limits first: the most common mistakes are in signature verification (HMAC over parsed JSON instead of the raw body) and in retries.
• For a typed client, have the agent generate it from openapi.yaml rather than write it by hand.
• Check the result in the test environment with the sandbox — step by step, as described in Testing.

Optional commercial integration

Do not enable it without the platform choosing it. Read network services, check capabilities and implement REST orders/entitlements before explicit spending-account enrollment. Keep X-Commerce-Key on the backend, never in a browser or a general AI agent configuration. Zero pricing still requires authorization and durable external_order_ref/X-Action-Ref. TEST does not convert to RUB.