Code examples

Every example below runs against the public API in cURL, TypeScript, and Python. They expect a read, write, or admin key matching the request, and values you adapt to your own integration.

Reconify has no sandbox or test mode. A write example creates immutable evidence in your real organization, and the public API deletes nothing.

export RECONIFY_API_KEY="rk_your_key_here"

import { ReconifyClient } from "@reconifyhq/sdk";

const client = new ReconifyClient({ apiKey: process.env.RECONIFY_API_KEY });

from reconify import Reconify

client = Reconify()  # reads RECONIFY_API_KEY

Send events

Ingestion covers four shapes: a single event, a mixed batch, a safe replay, and an event that carries provider lookup data.

Submit one event

One event in the events array is the smallest valid ingestion request.

curl -sS -X POST "https://api.reconifyhq.com/v2/events" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9","flow":"payment_to_wallet","type":"payment.succeeded","occurred_at":"2026-01-01T12:00:00Z","amount":"150.00","currency":"USD","reference":"order-123","entity_id":"wallet_123"}'

const result = await client.ingestion.ingestMonitoringEvents({
  body: {
    events: [
      {
        id: "evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9",
        flow: "payment_to_wallet",
        type: "payment.succeeded",
        occurred_at: "2026-01-01T12:00:00Z",
        amount: "150.00",
        currency: "USD",
        reference: "order-123",
        entity_id: "wallet_123",
      },
    ],
  },
});

from reconify.models import MonitoringBatchRequest, MonitoringEvent

result = client.ingestion.ingest_monitoring_events(
    MonitoringBatchRequest(
        events=[
            MonitoringEvent(
                id="evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9",
                flow="payment_to_wallet",
                type="payment.succeeded",
                occurred_at="2026-01-01T12:00:00Z",
                amount="150.00",
                currency="USD",
                reference="order-123",
                entity_id="wallet_123",
            )
        ]
    )
)

Submit a mixed batch

The second event below carries an invalid amount, so the batch returns one accepted result and one rejected result. The response order matches the request order.

curl -sS -X POST "https://api.reconifyhq.com/v2/events" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"id":"evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9","flow":"payment_to_wallet","type":"payment.succeeded","amount":"150.00","currency":"USD","reference":"order-123","entity_id":"wallet_123"},
    {"flow":"payment_to_wallet","type":"payment.succeeded","amount":"bad","currency":"USD","reference":"order-124","entity_id":"wallet_124"}
  ]'

const mixed = await client.ingestion.ingestMonitoringEvents({
  body: {
    events: [
      {
        id: "evt_01J3Y0M8VJQ5W1R3E4J4K7N8Q1",
        flow: "payment_to_wallet",
        type: "payment.succeeded",
        amount: "150.00",
        currency: "USD",
        reference: "order-123",
        entity_id: "wallet_123",
      },
      {
        flow: "payment_to_wallet",
        type: "payment.succeeded",
        amount: "bad",
        currency: "USD",
        reference: "order-124",
        entity_id: "wallet_124",
      },
    ],
  },
});

for (const item of mixed.results) {
  console.log(item.index, item.status, item.code);
}

mixed = client.ingestion.ingest_monitoring_events(
    MonitoringBatchRequest(
        events=[
            MonitoringEvent(
                id="evt_01J3Y0M8VJQ5W1R3E4J4K7N8Q1",
                flow="payment_to_wallet",
                type="payment.succeeded",
                amount="150.00",
                currency="USD",
                reference="order-123",
                entity_id="wallet_123",
            ),
            MonitoringEvent(
                flow="payment_to_wallet",
                type="payment.succeeded",
                amount="bad",
                currency="USD",
                reference="order-124",
                entity_id="wallet_124",
            ),
        ]
    )
)

for item in mixed.results:
    print(item.index, item.status, item.code)

Inspect every result before retrying. Retry only rejected items that are safe to resend.

The Python SDK rejects a numeric amount during Pydantic model validation, but it cannot tell whether a string contains a valid monetary value. An amount such as "bad" reaches the API and returns a rejected result.

Replay an event safely

Send the same id and payload. A stored item returns duplicate. Reusing the same id with different content returns a rejected item with idempotency_conflict, which needs investigation rather than another retry.

# Exact replay: expect status "duplicate".
curl -sS -X POST "https://api.reconifyhq.com/v2/events" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9","flow":"payment_to_wallet","type":"payment.succeeded","occurred_at":"2026-01-01T12:00:00Z","amount":"150.00","currency":"USD","reference":"order-123","entity_id":"wallet_123"}'

# Conflicting replay: expect code "idempotency_conflict".
curl -sS -X POST "https://api.reconifyhq.com/v2/events" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9","flow":"payment_to_wallet","type":"payment.succeeded","occurred_at":"2026-01-01T12:00:00Z","amount":"151.00","currency":"USD","reference":"order-123","entity_id":"wallet_123"}'

const replayEvent = {
  id: "evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9",
  flow: "payment_to_wallet" as const,
  type: "payment.succeeded" as const,
  occurred_at: "2026-01-01T12:00:00Z",
  amount: "150.00",
  currency: "USD",
  reference: "order-123",
  entity_id: "wallet_123",
};

const duplicate = await client.ingestion.ingestMonitoringEvents({
  body: { events: [replayEvent] },
});

const conflict = await client.ingestion.ingestMonitoringEvents({
  body: { events: [{ ...replayEvent, amount: "151.00" }] },
});

replay_event = MonitoringEvent(
    id="evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9",
    flow="payment_to_wallet",
    type="payment.succeeded",
    occurred_at="2026-01-01T12:00:00Z",
    amount="150.00",
    currency="USD",
    reference="order-123",
    entity_id="wallet_123",
)

duplicate = client.ingestion.ingest_monitoring_events(
    MonitoringBatchRequest(events=[replay_event])
)

conflict = client.ingestion.ingest_monitoring_events(
    MonitoringBatchRequest(
        events=[replay_event.model_copy(update={"amount": "151.00"})]
    )
)

An event without id receives a generated ID and can be stored again on retry.

Submit provider-enriched evidence

data.integration_ref selects a configured provider connection. Put the provider lookup value in data, because provider alone is descriptive and does not trigger a lookup.

curl -sS -X POST "https://api.reconifyhq.com/v2/events" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_01J3Y0M8VJQ5W1R3E4J4K7N8R2","flow":"payment_to_wallet","type":"payment.initiated","occurred_at":"2026-01-01T12:00:00Z","amount":"150.00","currency":"USD","reference":"order-125","entity_id":"wallet_125","data":{"integration_ref":"int_01J9XSTRIPE01","provider":"stripe","provider_transaction_id":"pi_3P8x2K"}}'

const enriched = await client.ingestion.ingestMonitoringEvents({
  body: {
    events: [
      {
        id: "evt_01J3Y0M8VJQ5W1R3E4J4K7N8R2",
        flow: "payment_to_wallet",
        type: "payment.initiated",
        occurred_at: "2026-01-01T12:00:00Z",
        amount: "150.00",
        currency: "USD",
        reference: "order-125",
        entity_id: "wallet_125",
        data: {
          integration_ref: "int_01J9XSTRIPE01",
          provider: "stripe",
          provider_transaction_id: "pi_3P8x2K",
        },
      },
    ],
  },
});

from reconify.models import MonitoringEventData

enriched = client.ingestion.ingest_monitoring_events(
    MonitoringBatchRequest(
        events=[
            MonitoringEvent(
                id="evt_01J3Y0M8VJQ5W1R3E4J4K7N8R2",
                flow="payment_to_wallet",
                type="payment.initiated",
                occurred_at="2026-01-01T12:00:00Z",
                amount="150.00",
                currency="USD",
                reference="order-125",
                entity_id="wallet_125",
                data=MonitoringEventData(
                    integration_ref="int_01J9XSTRIPE01",
                    provider="stripe",
                    provider_transaction_id="pi_3P8x2K",
                ),
            )
        ]
    )
)

The immediate response confirms ingestion, not the provider result. See Enrich events with provider data for tracking states and failure behavior.

Read data back

Read routes confirm what Reconify holds, page through results, and return organization context.

Read events

A list read confirms what Reconify stored, most recent first.

curl -sS "https://api.reconifyhq.com/v2/events?limit=20" \
  -H "Authorization: Bearer $RECONIFY_API_KEY"

curl -sS "https://api.reconifyhq.com/v2/events/evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9" \
  -H "Authorization: Bearer $RECONIFY_API_KEY"

const page = await client.events.listEvents({ query: { limit: 20 } });

const event = await client.events.getEvent({
  path: { event_id: "evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9" },
});

page = client.events.list_events(limit=20)

event = client.events.get_event("evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9")

Follow the cursor

Read page.next_cursor from each response and pass it as after. Stop when the cursor is absent.

curl -sS "https://api.reconifyhq.com/v2/events?limit=100" \
  -H "Authorization: Bearer $RECONIFY_API_KEY"

curl -sS "https://api.reconifyhq.com/v2/events?limit=100&after=$NEXT_CURSOR" \
  -H "Authorization: Bearer $RECONIFY_API_KEY"

for await (const event of client.events.iterateEvents({
  query: { limit: 100 },
})) {
  console.log(event.id, event.processing_status);
}

for event in client.iter_events(limit=100):
    print(event.id, event.processing_status)

Read organization data

Organization routes return the organization record and its members, without email addresses.

curl -sS "https://api.reconifyhq.com/v2/organization" \
  -H "Authorization: Bearer $RECONIFY_API_KEY"

curl -sS "https://api.reconifyhq.com/v2/organization/members" \
  -H "Authorization: Bearer $RECONIFY_API_KEY"

const organization = await client.organization.getOrganization();
const members = await client.organization.listOrganizationMembers();

organization = client.organization.get_organization()
members = client.organization.list_organization_members()

Member responses contain IDs and roles. They do not contain email addresses.

Work with issues

Issue routes cover reads, assignment, status changes, and append-only notes.

Read and update issues

Issue reads accept a status filter, and a PATCH updates assignment or status.

curl -sS "https://api.reconifyhq.com/v2/issues?status=open" \
  -H "Authorization: Bearer $RECONIFY_API_KEY"

curl -sS "https://api.reconifyhq.com/v2/issues/$ISSUE_ID" \
  -H "Authorization: Bearer $RECONIFY_API_KEY"

curl -sS "https://api.reconifyhq.com/v2/issues/$ISSUE_ID/events" \
  -H "Authorization: Bearer $RECONIFY_API_KEY"

curl -sS -X PATCH "https://api.reconifyhq.com/v2/issues/$ISSUE_ID" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assigned_to":"00000000-0000-7000-8000-000000000002"}'

const issues = await client.issues.listIssues({ query: { status: "open" } });

const issue = await client.issues.getIssue({ path: { issue_id: issueId } });

const evidence = await client.events.listIssueEvents({
  path: { issue_id: issueId },
});

const updated = await client.issues.updateIssue({
  path: { issue_id: issueId },
  body: { assigned_to: "00000000-0000-7000-8000-000000000002" },
});

from reconify.models import PatchIssueRequest

issues = client.issues.list_issues(status="open")

issue = client.issues.get_issue(issue_id)

evidence = client.events.list_issue_events(issue_id)

updated = client.issues.update_issue(
    issue_id,
    PatchIssueRequest(assigned_to="00000000-0000-7000-8000-000000000002"),
)

The PATCH request changes assignment only. It does not change finding status.

Add a note safely

Notes are append-only, and an Idempotency-Key header makes a retry safe.

curl -sS -X POST "https://api.reconifyhq.com/v2/issues/$ISSUE_ID/notes" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Idempotency-Key: note-order-123-provider-late" \
  -H "Content-Type: application/json" \
  -d '{"body":"Confirmed that the provider callback arrived late."}'

const note = await client.issues.addIssueNote({
  path: { issue_id: issueId },
  headers: { "Idempotency-Key": "note-order-123-provider-late" },
  body: { body: "Confirmed that the provider callback arrived late." },
});

from reconify.models import AddNoteRequest

note = client.issues.add_issue_note(
    issue_id,
    AddNoteRequest(body="Confirmed that the provider callback arrived late."),
    idempotency_key="note-order-123-provider-late",
)

Repeat the request with the same key and body to replay the original note. A different body returns 409 idempotency_conflict.

Health and errors

The last two examples cover the unauthenticated health check and the shape of error handling around every call above.

Check availability

GET /v2 and GET /v2/health need no credentials.

curl -sS "https://api.reconifyhq.com/v2/health"

const health = await client.metadata.getHealth();

health = client.metadata.get_health()

Handle errors

The SDKs retry safe reads after a degraded 503. Event ingestion is not retried by default because a batch without stable IDs can be recorded more than once. Enable unsafe-method retries only after every event has a stable id.

# This POST is retryable because every event in the body has a stable ID.
# curl respects Retry-After and otherwise uses an increasing delay.
curl --retry 2 --retry-all-errors --retry-max-time 15 \
  -sS -X POST "https://api.reconifyhq.com/v2/events" \
  -H "Authorization: Bearer $RECONIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_01J3Y0M8VJQ5W1R3E4J4K7N8S3","flow":"payment_to_wallet","type":"payment.succeeded","amount":"150.00","currency":"USD","reference":"order-126","entity_id":"wallet_126"}'

import { ReconifyApiError } from "@reconifyhq/sdk";

try {
  await client.ingestion.ingestMonitoringEvents({
    body: {
      events: [
        {
          id: "evt_01J3Y0M8VJQ5W1R3E4J4K7N8S3",
          flow: "payment_to_wallet",
          type: "payment.succeeded",
          amount: "150.00",
          currency: "USD",
          reference: "order-126",
          entity_id: "wallet_126",
        },
      ],
    },
    request: { retry: { retryNonIdempotent: true } },
  });
} catch (error) {
  if (error instanceof ReconifyApiError && error.status === 503) {
    console.error({
      code: error.code,
      requestId: error.response.headers.get("x-request-id"),
    });
  } else {
    throw error;
  }
}

from reconify import Reconify
from reconify.errors import ReconifyServiceUnavailableError
from reconify.transport import RetryConfig

retrying_client = Reconify(
    retry=RetryConfig(max_retries=2, retry_unsafe_methods=True)
)

try:
    retrying_client.ingestion.ingest_monitoring_events(
        MonitoringBatchRequest(
            events=[
                MonitoringEvent(
                    id="evt_01J3Y0M8VJQ5W1R3E4J4K7N8S3",
                    flow="payment_to_wallet",
                    type="payment.succeeded",
                    amount="150.00",
                    currency="USD",
                    reference="order-126",
                    entity_id="wallet_126",
                )
            ]
        )
    )
except ReconifyServiceUnavailableError as exc:
    print({"code": exc.code, "request_id": exc.request_id})

Do not retry an ingestion request unless every event has a stable ID. Do not log API keys or full financial payloads. A 401 means the key is missing or invalid. A 403 means the key lacks the required scope.

See Errors for the complete code and retry matrix, or the public API reference for request and response details.

Getting started

Start monitoring

Understand monitoring

Troubleshoot and support

Agent tooling

Examples

Send events

Submit one event

Submit a mixed batch

Replay an event safely

Submit provider-enriched evidence

Read data back

Read events

Follow the cursor

Read organization data

Work with issues

Read and update issues

Add a note safely

Health and errors

Check availability

Handle errors

​Send events

​Submit one event

​Submit a mixed batch

​Replay an event safely

​Submit provider-enriched evidence

​Read data back

​Read events

​Follow the cursor

​Read organization data

​Work with issues

​Read and update issues

​Add a note safely

​Health and errors

​Check availability

​Handle errors

Send events

Submit one event

Submit a mixed batch

Replay an event safely

Submit provider-enriched evidence

Read data back

Read events

Follow the cursor

Read organization data

Work with issues

Read and update issues

Add a note safely

Health and errors

Check availability

Handle errors