Integrate with an AI agent

A coding agent such as Claude Code, Cursor, GitHub Copilot, or Codex can add Reconify event tracking to your codebase, provided it works from the published API instead of invented endpoints and field names. The prompt below keeps it there. One thing stays with you: the credential. The write key comes from Dashboard → Settings → API Keys and goes into your secret manager as RECONIFY_API_KEY, because an agent has no business creating credentials or deciding where secrets live.

An API key never belongs in a prompt, a rules file, or a chat window. The prompt below has the agent read the key from the environment.

Which flow to use is not a decision you make up front. The prompt has the agent work that out from your code and confirm it with you.

Copy this prompt

The prompt runs in four phases and stops for your approval twice, because an agent that starts writing a sender before it understands how your money moves maps the wrong identifiers, and the mapping is the expensive part to fix later. It carries no project-specific detail on purpose, since discovering that is the agent’s first job.

I want to add Reconify monitoring to this project. Reconify receives
money-movement events and raises findings when expected evidence is missing,
late, or mismatched.

Work in four phases. Stop and wait for my approval where I say so. Do not
change any file before phase 4.

PHASE 1 — Understand how money moves in this project.
Read the codebase and answer:
- Where does money actually move? Find the payment, wallet, ledger, payout, and
  order-fulfillment paths.
- What does each of those paths record when it completes or fails? Name the
  functions, domain events, webhook handlers, queue messages, or table writes.
- What identifier ties a payment to its downstream effect? For example, what
  value connects "customer paid" to "wallet was credited"?
- What identifies the account or object being credited or debited?
- How are monetary amounts stored: integer minor units, decimal, or float? What
  currencies exist?
- Where is the natural place to emit an outbound call after each of these
  completes?
Report what you found. Do not read the Reconify docs yet.

PHASE 2 — Learn the Reconify model.
Now read, in this order:
1. https://docs.reconifyhq.com/concepts/overview
2. https://docs.reconifyhq.com/concepts/operations
3. https://docs.reconifyhq.com/reference/api/welcome
Summarize back to me, in your own words: what a flow is, what an operation is,
the difference between `reference` and `entity_id`, and which of the four flows
exist along with the evidence and deadline each one expects.

PHASE 3 — Propose a mapping. STOP after this and wait for my approval.
Produce a table with one row per money-movement path you found in phase 1:
| My code path | Reconify flow | Reconify event type | My value for reference | My value for entity_id | My value for amount and currency | Where it will be emitted |
Then tell me:
- Which flows I can monitor today, and which ones my code cannot yet support
  because it does not record the required evidence.
- Any place where my identifiers do not cleanly map, and what you recommend.
- Whether amounts need converting to a decimal string.
- Which integration path you recommend: @reconifyhq/sdk for TypeScript,
  reconify-python for Python, or a direct REST call in another language.
Do not write code yet. Wait for me to confirm or correct the mapping.

PHASE 4 — Plan, then implement.
After I approve the mapping, write an implementation plan covering the sender,
where it is called, configuration, error handling, and tests. Wait for my
approval of the plan, then implement it.

Rules that apply throughout:
- Do not change my database schema or my existing domain events. Add a
  translation layer over what I already emit.
- Read the key from the RECONIFY_API_KEY environment variable. Never hardcode
  it, log it, or expose it to a client.
- `amount` is a decimal string such as "150.00", never a number or a float.
- Set a stable event `id` derived from my source system's identifier so retries
  are safe.
- Read every item in the `results` array of an ingestion response. `index` maps
  back to the event sent. Log rejected items with their code, field, and
  message. Treat `duplicate` as delivered. Alert on `idempotency_conflict`.
- Do not invent endpoints. The public API is only what is listed at
  https://docs.reconifyhq.com/reference/api/welcome. There are no webhooks.
- Tests must use a fake HTTP client. Never call the live API from a test.

An agent with subagents or a plan mode does best when it uses them for phase 1. Finding every money-movement path in a large codebase is a search problem, and the quality of the mapping depends entirely on that search being complete.

Check what it produced

The mapping the agent proposes is the deliverable worth scrutinizing. A correct one names your own identifiers rather than repeating the documentation:

My code path	Flow	Event type	`reference`	`entity_id`	Amount
`PaymentService.capture()` success	`payment_to_wallet`	`payment.succeeded`	`payment.order_id`	`payment.wallet_id`	`Decimal(cents)/100` as string
`WalletService.credit()` commit	`payment_to_wallet`	`wallet.credited`	`credit.order_id`	`credit.wallet_id`	same

Each value has to serve its own role: reference correlates an operation, and entity_id identifies its wallet or order. The contract allows the same source identifier in both roles where that is genuinely correct. Six mistakes account for most of what agents get wrong against this API:

amount sent as a number

"amount": 150.00 is rejected. It must be "amount": "150.00". Watch for a float in Python or a bare number in JavaScript.

reference and entity_id swapped

reference correlates the operation, and entity_id names the wallet or order. Swapping them produces events that never correlate, so every operation looks incomplete.

Random event IDs

A uuid4() generated at send time defeats retry safety. The ID must be derived from the source system so the same event produces the same ID twice.

Results ignored

A 202 response does not mean every event was stored. If the code does not loop over results, rejections are silent.

An invented webhook handler

There is no outbound webhook. If the agent added a /webhooks/reconify route, delete it and poll GET /v2/issues?status=open instead.

Tests that call the live API

There is no sandbox. Tests must use a fake HTTP client. Both SDKs support this: pass fetch in TypeScript, or http_client in Python.

Keep the rules in your repo

Agents forget prompts between sessions, and a rules file does not. The text below belongs in AGENTS.md at your repository root, on its own or appended to an existing file. Claude Code, Cursor, Codex, and several other tools read it automatically.

AGENTS.md rules for Reconify

## Reconify monitoring

Reconify receives money-movement events from this codebase and raises findings
when expected evidence is missing, late, or mismatched.

Reference: https://docs.reconifyhq.com

### Contract rules

- The only public API is `/v2` at `https://api.reconifyhq.com`. Never call
  `/business/v1`, which is internal and not part of the public contract.
- There are no outbound webhooks. To learn about new findings, poll
  `GET /v2/issues?status=open`.
- There is no sandbox or test mode. Every request reaches the real
  organization. Never call the live API from an automated test.
- Authentication is `Authorization: Bearer rk_...` read from
  `RECONIFY_API_KEY`. `read` keys authorize GET, `write` keys authorize POST
  and PATCH.

### Event fields

Required on every event: `flow`, `type`, `reference`, `entity_id`.
Also required unless the type is `payment.failed` or `payout.failed`:
`amount`, `currency`.

- `amount` is a decimal **string** such as `"150.00"`. Never a number.
- `currency` is a three-letter uppercase ISO code.
- `occurred_at` is RFC 3339 UTC.
- `reference` identifies the operation. `entity_id` identifies the wallet or
  order. Map each field by its role, and never swap them.
- `id` is optional but should always be set, as `evt_` plus 26 uppercase
  alphanumeric characters, so retries are safe.
- Unknown fields are rejected. Put extra context in `metadata` (flat, at most
  20 keys) or in `data` for provider details.

Valid `flow` values: `payment_to_wallet`, `payment_to_order`,
`wallet_to_wallet`, `wallet_to_payout`.

Valid `type` values: `payment.initiated`, `payment.succeeded`,
`payment.failed`, `order.fulfilled`, `wallet.credited`, `wallet.debited`,
`wallet.refunded`, `payout.initiated`, `payout.succeeded`, `payout.failed`.

Note the asymmetry: requests send `type`, event reads return `event_type`.

### Ingestion behavior

`POST /v2/events` accepts 1 to 500 events, up to 5 MiB per request and 256 KiB
per event. It returns `202` when at least one event is accepted, and `422` when
all are rejected.

Always read `results`. Each item has `index` matching the submitted position,
and `status` of `accepted`, `duplicate`, or `rejected`. Rejection codes are
`invalid_event`, `unknown_field`, `idempotency_conflict`, `duplicate`, and
`malformed_request`.

`accepted` means the event was stored, not that the operation succeeded.

### Retries

Retry with the same `id` and the same payload, since stored events return
`duplicate`. Reusing an `id` with different content returns
`idempotency_conflict` and must be investigated, not retried. Events without an
`id` are unsafe to retry.

`Idempotency-Key` applies only to `POST /v2/issues/{issue_id}/notes`. Never send
it on event ingestion.

### Security

Never hardcode, log, or commit an API key. Never log full event payloads, note
bodies, amounts, or customer identifiers. Log `X-Request-ID` from the response
instead.

### SDKs

- TypeScript: `@reconifyhq/sdk`, `new ReconifyClient({ apiKey })`,
  `client.ingestion.ingestMonitoringEvents({ body })`.
- Python: `reconify-python`, `Reconify()` or `AsyncReconify()`,
  `client.ingestion.ingest_monitoring_events(batch)`.

Both retry reads automatically and do not retry ingestion unless you opt in.

Next: Send events covers the batch handling and retry rules the agent’s sender has to get right.

Getting started

Start monitoring

Understand monitoring

Troubleshoot and support

Agent tooling

Examples

Copy this prompt

Check what it produced

Keep the rules in your repo

​Copy this prompt

​Check what it produced

​Keep the rules in your repo

Copy this prompt

Check what it produced

Keep the rules in your repo