> ## Documentation Index > Fetch the complete documentation index at: https://docs.reconifyhq.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Reconify's API reference is read-only for customer data. Do not invent endpoints or authentication behavior beyond the OpenAPI contract. > The public OpenAPI document contains only the documented external /v2 contract. # Submit monitoring events > Durably acknowledge one event or a batch of 1–500 flow-monitoring events. Each event is validated independently; accepted and rejected indexes are returned together. ## OpenAPI ````yaml /openapi/reconify.openapi.json post /v2/events openapi: 3.1.0 info: description: Public event ingestion and issue operations for Reconify. title: Reconify API version: 2.1.0 servers: - description: Reconify API root url: https://api.reconifyhq.com security: [] tags: - description: Submit events through the public v2 ingestion API. name: event-ingestion - description: Public API metadata and health checks. name: api-metadata - description: Read received events and evidence linked to issues. name: event-reads - description: Discover and coordinate evidence-backed monitoring issues. name: issue-operations - description: Read organization details and assignable member IDs. name: organization paths: /v2/events: post: tags: - event-ingestion summary: Submit monitoring events description: >- Durably acknowledge one event or a batch of 1–500 flow-monitoring events. Each event is validated independently; accepted and rejected indexes are returned together. operationId: events_ingest requestBody: content: application/json: examples: event_array: summary: Multiple monitoring events value: - amount: '150.00' currency: USD data: provider: stripe provider_reference: pi_123 entity_id: wallet_123 flow: payment_to_wallet id: evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9 occurred_at: '2026-01-01T00:00:00Z' reference: order-123 type: payment.succeeded - data: failure_code: card_declined failure_message: The card was declined. provider: stripe provider_reference: pi_124 retryable: false entity_id: wallet_123 flow: payment_to_wallet id: evt_01J3Y0M8VJQ5W1R3E4J4K7N8Q0 occurred_at: '2026-01-01T00:00:00Z' reference: order-124 type: payment.failed payment_failed: summary: A failed payment event carrying provider failure context value: data: failure_code: card_declined failure_message: The card was declined. provider: stripe provider_reference: pi_124 retryable: false entity_id: wallet_123 flow: payment_to_wallet id: evt_01J3Y0M8VJQ5W1R3E4J4K7N8Q0 occurred_at: '2026-01-01T00:00:00Z' reference: order-124 type: payment.failed single_event: summary: A single successful payment event value: amount: '150.00' currency: USD data: provider: stripe provider_reference: pi_123 entity_id: wallet_123 flow: payment_to_wallet id: evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9 occurred_at: '2026-01-01T00:00:00Z' reference: order-123 type: payment.succeeded wrapped_batch: summary: A backward-compatible wrapped batch value: events: - amount: '150.00' currency: USD data: provider: stripe provider_reference: pi_123 entity_id: wallet_123 flow: payment_to_wallet id: evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9 occurred_at: '2026-01-01T00:00:00Z' reference: order-123 type: payment.succeeded schema: $ref: '#/components/schemas/MonitoringIngestRequest' required: true responses: '202': content: application/json: examples: accepted: value: results: - event_id: evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9 index: 0 status: accepted schema: $ref: '#/components/schemas/MonitoringBatchResponse' description: Accepted '400': content: application/json: examples: bad_request: value: code: malformed_request message: request body must be a JSON object or array schema: $ref: '#/components/schemas/Error' description: Bad Request '401': content: application/json: examples: unauthorized: value: code: unauthorized message: authentication required schema: $ref: '#/components/schemas/Error' description: Unauthorized '403': content: application/json: examples: forbidden: value: code: forbidden message: wallet integrity monitoring is not enabled schema: $ref: '#/components/schemas/Error' description: Forbidden '413': content: application/json: examples: request_entity_too_large: value: code: request_too_large message: request exceeds the 5 MiB limit schema: $ref: '#/components/schemas/Error' description: Request Entity Too Large '422': content: application/json: examples: unprocessable_entity: value: results: - code: invalid_event field: amount index: 0 message: amount is required for this event type status: rejected schema: $ref: '#/components/schemas/MonitoringBatchResponse' description: Unprocessable Entity '503': content: application/json: examples: service_unavailable: value: code: database_unavailable message: monitoring ingestion is unavailable schema: $ref: '#/components/schemas/Error' description: Service Unavailable security: - organizationApiKey: [] components: schemas: MonitoringIngestRequest: description: >- Submit one event, a bare array of events, or the backward-compatible events wrapper. oneOf: - $ref: '#/components/schemas/MonitoringEvent' - description: One to 500 monitoring events. items: $ref: '#/components/schemas/MonitoringEvent' maxItems: 500 minItems: 1 type: array - $ref: '#/components/schemas/MonitoringBatchRequest' MonitoringBatchResponse: properties: results: description: Results in the same order as the submitted events. items: $ref: '#/components/schemas/MonitoringResult' type: array required: - results type: object Error: properties: code: description: Stable machine-readable error code. enum: - malformed_request - unauthorized - forbidden - request_too_large - invalid_input - not_found - idempotency_conflict - database_unavailable type: string detail: description: Human-readable details about the request failure. type: string message: description: Short human-readable explanation. type: string status: description: HTTP status code for the problem. type: integer title: description: General category of the problem. type: string required: - code - message type: object MonitoringEvent: additionalProperties: false description: >- A monitoring event. Batches are limited to 500 events, requests to 5242880 bytes, and individual events to 262144 bytes. Amount and currency are required for all event types except payment.failed and payout.failed. entity_id identifies the target derived from the selected flow. properties: amount: description: Decimal amount in the event currency. pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$ type: string causation_id: description: >- Optional opaque identifier for the single earlier event that caused this event. It is not resolved at ingest. maxLength: 200 minLength: 1 pattern: ^[\x21-\x7E]+$ type: string correlation_id: description: >- Optional producer-supplied opaque identifier propagated across services. Do not include secrets or personal data. maxLength: 200 minLength: 1 pattern: ^[\x21-\x7E]+$ type: string currency: description: Three-letter uppercase ISO currency code. pattern: ^[A-Z]{3}$ type: string data: $ref: '#/components/schemas/MonitoringEventData' description: Optional provider, failure, or retry context. entity_id: description: >- Target identifier. Its entity type is derived from the selected flow. minLength: 1 type: string flow: description: Monitoring flow that defines the expected evidence sequence. enum: - payment_to_wallet - payment_to_order - wallet_to_wallet - wallet_to_payout type: string id: description: Optional stable ULID used to identify the event across retries. pattern: ^evt_[0-9A-Z]{26}$ type: string metadata: additionalProperties: type: - string - number - boolean description: Optional flat key-value context retained with the event. maxProperties: 20 type: object occurred_at: description: Time when the event occurred in the source system. format: date-time type: string reference: description: Stable local business reference supplied by the producer. minLength: 1 type: string type: description: Lifecycle event type, such as payment.succeeded. enum: - order.fulfilled - payment.failed - payment.initiated - payment.succeeded - payout.failed - payout.initiated - payout.succeeded - wallet.credited - wallet.debited - wallet.refunded type: string required: - flow - type - reference - entity_id type: object MonitoringBatchRequest: additionalProperties: false properties: events: description: One to 500 events to validate and ingest. items: $ref: '#/components/schemas/MonitoringEvent' maxItems: 500 minItems: 1 type: array required: - events type: object MonitoringResult: properties: code: description: Stable machine-readable code for a rejected item. enum: - invalid_event - unknown_field - idempotency_conflict - duplicate - malformed_request type: string event_id: description: Reconify event identifier when the event was stored. type: string field: description: Request field associated with the rejection. type: string index: description: Zero-based position of the event in the request. minimum: 0 type: integer message: description: Short human-readable explanation. type: string status: description: Whether the event was accepted, duplicated, or rejected. enum: - accepted - duplicate - rejected type: string warnings: description: Non-fatal normalization or validation warnings. items: type: string type: array required: - index - status type: object MonitoringEventData: additionalProperties: false properties: failure_code: description: Stable provider or source code for a failed event. type: string failure_message: description: Human-readable failure context from the source system. type: string integration_ref: description: >- Opaque payment integration reference used for asynchronous provider tracking. type: string provider: description: Provider that originated or processed the event. type: string provider_reference: description: Provider-side identifier for the payment or payout. type: string provider_transaction_id: description: >- Provider transaction identifier. Numeric identifiers must be encoded as strings. type: string retryable: description: Whether the source considers the failed event retryable. type: boolean type: object securitySchemes: organizationApiKey: description: Organization API key. Use a write-scoped key for event ingestion. scheme: bearer type: http ````