{
  "openapi": "3.1.0",
  "info": {
    "title": "Givemora Events API v2",
    "version": "2.0.0",
    "description": "Asynchronous, payload-free submission and batch-receipt contract. HTTP 202 means durable acceptance or receipt processing, not successful delivery to destinations. V2 uses separate idempotency namespaces from v1."
  },
  "servers": [
    {
      "url": "https://givemora.com"
    }
  ],
  "security": [
    {
      "ProjectCredential": []
    }
  ],
  "paths": {
    "/v2/events": {
      "post": {
        "operationId": "submit",
        "summary": "Durably accept one event for asynchronous routing",
        "description": "Requires a current project environment credential with events:write. Idempotency-Key is required and must contain 1–128 visible ASCII characters. For regular event JSON, a non-null Event.id must equal that header; null behaves as absent. For CloudEvents, the adapter derives the canonical Event.id as ce_ followed by the lowercase SHA-256 hex digest of \"givemora.com/cloudevents/v1\\0\" + source + \"\\0\" + the original CloudEvent id. Set Idempotency-Key to that derived canonical Event.id, not the original CloudEvent id. The same key and canonical event body replay the original accepted result while its receipt is retained; a changed event conflicts with 409. Single-event fingerprinting follows the current event canonicalization behavior. Default receipt retention is 30 days and can differ by deployment. After expiry, an ambiguous outcome requires manual reconciliation: do not silently generate a new key or replay. A 202 confirms durable acceptance only: its initial routing_status and routing are both pending. Later polling reports the lifecycle and routing decision independently.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/CeSpecversion"
          },
          {
            "$ref": "#/components/parameters/CeId"
          },
          {
            "$ref": "#/components/parameters/CeSource"
          },
          {
            "$ref": "#/components/parameters/CeType"
          },
          {
            "$ref": "#/components/parameters/CeTime"
          },
          {
            "$ref": "#/components/parameters/CeSubject"
          },
          {
            "$ref": "#/components/parameters/CeDataschema"
          },
          {
            "$ref": "#/components/parameters/CeCorrelationid"
          },
          {
            "$ref": "#/components/parameters/CeSeverity"
          },
          {
            "$ref": "#/components/parameters/CeTraceparent"
          },
          {
            "$ref": "#/components/parameters/CeTracestate"
          },
          {
            "$ref": "#/components/parameters/GivemoraTimestamp"
          },
          {
            "$ref": "#/components/parameters/GivemoraNonce"
          },
          {
            "$ref": "#/components/parameters/GivemoraSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            },
            "application/cloudevents+json": {
              "schema": {
                "$ref": "#/components/schemas/CloudEvent"
              }
            },
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              },
              "description": "CloudEvents HTTP binary mode. Supply the required ce-specversion, ce-id, ce-source and ce-type headers; supported ce-* extensions are documented in the header parameters. Body size defaults to 256 KiB and is configurable."
            }
          }
        },
        "responses": {
          "202": {
            "description": "Durably accepted only. The initial response has routing_status=pending and routing=pending; these initial values are not a promise that future polled lifecycle and decision values will match.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              },
              "Pragma": {
                "$ref": "#/components/headers/PragmaNoCache"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AcceptedSubmission"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "403": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "409": {
            "description": "Idempotency key conflicts with an existing body.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              },
              "Pragma": {
                "$ref": "#/components/headers/PragmaNoCache"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "conflict": {
                    "value": {
                      "error": {
                        "code": "idempotency_conflict",
                        "message": "The request is invalid.",
                        "request_id": "01J00000000000000000000001",
                        "details": []
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "429": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "503": {
            "description": "Temporarily unavailable; retry the exact original request with the same key after Retry-After.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              },
              "Pragma": {
                "$ref": "#/components/headers/PragmaNoCache"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/MalformedJsonNoStore"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLargeNoStore"
          }
        },
        "x-sdk-method-names": {
          "php": "submit",
          "typescript": "submit",
          "python": "submit",
          "go": "SubmitEvent",
          "go_context": "SubmitEventContext"
        }
      }
    },
    "/v2/events/batch": {
      "post": {
        "operationId": "submitBatch",
        "summary": "Process an ordered event batch into a durable receipt",
        "description": "Requires a current project environment credential with events:write. Idempotency-Key is required and must contain 1–128 visible ASCII characters. Batch keys have a namespace separate from single-event and v1 keys. Repeating the same key and byte-for-byte identical serialized JSON body resumes or replays its receipt; any byte change, including JSON whitespace or object-property order, conflicts with 409. Batch item order is significant. The default receipt horizon is 30 days and may vary by deployment. A 202 means the receipt is complete, not that events have routed. A 503 can follow a committed accepted prefix; preserve its receipt and retry the byte-for-byte identical serialized body and key.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/GivemoraTimestamp"
          },
          {
            "$ref": "#/components/parameters/GivemoraNonce"
          },
          {
            "$ref": "#/components/parameters/GivemoraSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventBatch"
              }
            },
            "application/cloudevents-batch+json": {
              "schema": {
                "type": "array",
                "minItems": 1,
                "maxItems": 100,
                "items": {
                  "$ref": "#/components/schemas/CloudEvent"
                },
                "description": "CloudEvents structured batch; each entry follows the supported CloudEvents adapter and the same event validation limits."
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Every item has a durable accepted or rejected result in the receipt.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              },
              "Pragma": {
                "$ref": "#/components/headers/PragmaNoCache"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompletedBatch"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "403": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "409": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "422": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "429": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "503": {
            "description": "The receipt remains incomplete and may contain an already committed accepted prefix. Keep the returned receipt_id and retry the identical body with the same key; never assume rollback.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              },
              "Pragma": {
                "$ref": "#/components/headers/PragmaNoCache"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IncompleteBatch"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/MalformedJsonNoStore"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLargeNoStore"
          }
        },
        "x-sdk-method-names": {
          "php": "submitBatch",
          "typescript": "submitBatch",
          "python": "submit_batch",
          "go": "SubmitBatchEvents",
          "go_context": "SubmitBatchEventsContext"
        }
      }
    },
    "/v2/event-submissions/{submission}": {
      "get": {
        "operationId": "getSubmission",
        "summary": "Read current payload-free routing state for one accepted submission",
        "description": "Requires the same current project environment credential with events:write that owns the submission. A foreign or unavailable submission is 404; an expired retained submission is 410; after purge it is 404. The response contains metadata only and never returns the submitted payload. routing_status is the durable submission lifecycle; routing is a separate nullable routing decision, so the two values may differ.",
        "parameters": [
          {
            "$ref": "#/components/parameters/SubmissionId"
          }
        ],
        "responses": {
          "200": {
            "description": "Current payload-free lifecycle status and routing decision. routing_status and routing are independent; for example a routed submission may have a filtered decision because no destination matched.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              },
              "Pragma": {
                "$ref": "#/components/headers/PragmaNoCache"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmissionStatus"
                },
                "examples": {
                  "routedButFiltered": {
                    "summary": "Routing completed with a filtered decision",
                    "value": {
                      "submission_id": "01JBF000000000000000000012",
                      "event_id": "01JBF000000000000000000022",
                      "received_at": "2026-11-03T10:17:00Z",
                      "routing_status": "routed",
                      "routing": "filtered",
                      "routing_reason": "destination_missing",
                      "routing_explain": {
                        "state": "routed"
                      },
                      "request_id": "01JBF000000000000000000004"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "403": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "404": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "410": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "422": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "429": {
            "$ref": "#/components/responses/ErrorNoStore"
          }
        },
        "x-sdk-method-names": {
          "php": "getSubmission",
          "typescript": "getSubmission",
          "python": "get_submission",
          "go": "GetSubmission",
          "go_context": "GetSubmissionContext"
        }
      }
    },
    "/v2/event-submission-batches/{receipt}": {
      "get": {
        "operationId": "getSubmissionBatch",
        "summary": "Read a page of payload-free batch receipt items",
        "description": "Requires the same current project environment credential with events:write that owns the receipt. Batch pages are immutable processing results and may show accepted items as routing pending even after they route; use GET /v2/event-submissions/{submission} for current routing. Foreign or unavailable receipts return 404; expired retained receipts return 410; purged receipts return 404. The decimal cursor is an offset into the receipt snapshot. The server clamps numeric limits to 1..100; the default is 100.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReceiptId"
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Decimal offset cursor returned as next_cursor; omit on the first page.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,8}$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size; defaults to 100 and is clamped by the server to 1..100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A payload-free page from the receipt snapshot.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/NoStore"
              },
              "Pragma": {
                "$ref": "#/components/headers/PragmaNoCache"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchReceiptPage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "403": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "404": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "410": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "422": {
            "$ref": "#/components/responses/ErrorNoStore"
          },
          "429": {
            "$ref": "#/components/responses/ErrorNoStore"
          }
        },
        "x-sdk-method-names": {
          "php": "getSubmissionBatch",
          "typescript": "getSubmissionBatch",
          "python": "get_submission_batch",
          "go": "GetSubmissionBatch",
          "go_context": "GetSubmissionBatchContext"
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ProjectCredential": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "project environment credential",
        "description": "Current project credential with events:write scope. This scope is required for polling as well as submission."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "1–128 visible ASCII characters. Reuse the exact key for retries within the finite server retention horizon.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[!-~]+$"
        }
      },
      "SubmissionId": {
        "name": "submission",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/Ulid"
        }
      },
      "ReceiptId": {
        "name": "receipt",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/Ulid"
        }
      },
      "CeSpecversion": {
        "name": "ce-specversion",
        "in": "header",
        "required": false,
        "description": "Required for CloudEvents HTTP binary mode; must be 1.0. Binary mode is selected by ce-* headers with a non-CloudEvents media type. Do not mix with application/cloudevents media types. Binary mode does not support ce-actor or ce-tags.",
        "schema": {
          "type": "string",
          "const": "1.0"
        }
      },
      "CeId": {
        "name": "ce-id",
        "in": "header",
        "required": false,
        "description": "Required for CloudEvents HTTP binary mode.",
        "schema": {
          "type": "string",
          "maxLength": 256
        }
      },
      "CeSource": {
        "name": "ce-source",
        "in": "header",
        "required": false,
        "description": "Required for CloudEvents HTTP binary mode; URI reference without user information.",
        "schema": {
          "type": "string",
          "maxLength": 2048,
          "format": "uri-reference"
        }
      },
      "CeType": {
        "name": "ce-type",
        "in": "header",
        "required": false,
        "description": "Required for CloudEvents HTTP binary mode.",
        "schema": {
          "type": "string",
          "maxLength": 100,
          "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"
        }
      },
      "CeTime": {
        "name": "ce-time",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "format": "date-time"
        }
      },
      "CeSubject": {
        "name": "ce-subject",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 512
        }
      },
      "CeDataschema": {
        "name": "ce-dataschema",
        "in": "header",
        "required": false,
        "description": "Must be in the configured URI allowlist when configured.",
        "schema": {
          "type": "string",
          "format": "uri",
          "maxLength": 2048
        }
      },
      "CeCorrelationid": {
        "name": "ce-correlationid",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 128
        }
      },
      "CeSeverity": {
        "name": "ce-severity",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "info",
            "success",
            "warning",
            "critical"
          ]
        }
      },
      "CeTraceparent": {
        "name": "ce-traceparent",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 512
        }
      },
      "CeTracestate": {
        "name": "ce-tracestate",
        "in": "header",
        "required": false,
        "description": "Valid only when ce-traceparent is present.",
        "schema": {
          "type": "string"
        }
      },
      "GivemoraTimestamp": {
        "name": "X-Givemora-Timestamp",
        "in": "header",
        "required": false,
        "description": "Optional signed-ingestion header. If any X-Givemora signing header is sent, send all three. Unix timestamp seconds; server tolerance is configurable (300 seconds by default).",
        "schema": {
          "type": "string",
          "pattern": "^-?\\d+$"
        }
      },
      "GivemoraNonce": {
        "name": "X-Givemora-Nonce",
        "in": "header",
        "required": false,
        "description": "Optional signed-ingestion nonce; when signing is used, 1–128 visible ASCII characters and not previously used for this credential within the replay window.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[!-~]+$"
        }
      },
      "GivemoraSignature": {
        "name": "X-Givemora-Signature",
        "in": "header",
        "required": false,
        "description": "Optional signed-ingestion signature. If any signing header is sent, send all three. Format sha256=<64 lowercase hexadecimal characters>; HMAC-SHA256 key is the bearer credential. Binary CloudEvents uses its separate canonical signing input.",
        "schema": {
          "type": "string",
          "pattern": "^sha256=[a-f0-9]{64}$"
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "Matches request_id in the JSON body.",
        "schema": {
          "$ref": "#/components/schemas/Ulid"
        }
      },
      "NoStore": {
        "description": "Responses are not cacheable.",
        "schema": {
          "type": "string",
          "const": "private, no-store, max-age=0"
        }
      },
      "PragmaNoCache": {
        "schema": {
          "type": "string",
          "const": "no-cache"
        }
      },
      "RetryAfter": {
        "description": "Delta-seconds before retrying.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "responses": {
      "ErrorNoStore": {
        "description": "Error response. Message text may be localized; use the stable error code.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/NoStore"
          },
          "Pragma": {
            "$ref": "#/components/headers/PragmaNoCache"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "MalformedJsonNoStore": {
        "description": "Malformed JSON request body.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/NoStore"
          },
          "Pragma": {
            "$ref": "#/components/headers/PragmaNoCache"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "malformed_json": {
                "value": {
                  "error": {
                    "code": "malformed_json",
                    "message": "Something went wrong. Please try again.",
                    "request_id": "01JBF000000000000000000101",
                    "details": []
                  }
                }
              }
            }
          }
        }
      },
      "PayloadTooLargeNoStore": {
        "description": "Request body exceeds the configured endpoint size limit.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/NoStore"
          },
          "Pragma": {
            "$ref": "#/components/headers/PragmaNoCache"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "payload_too_large": {
                "value": {
                  "error": {
                    "code": "payload_too_large",
                    "message": "The event payload exceeds the configured size limit.",
                    "request_id": "01JBF000000000000000000102",
                    "details": []
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Ulid": {
        "type": "string",
        "pattern": "^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$"
      },
      "Event": {
        "type": "object",
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "description": "Current v1 envelope validation is retained. data/context/actor/subject, when non-null, must be JSON objects; unknown top-level keys are rejected. Sensitive values are redacted server-side.",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128,
            "description": "Optional producer-assigned event ID. On POST /v2/events, a non-null ID must equal Idempotency-Key; null behaves as absent and the required header supplies the single-event key. In a batch, a non-null item ID is its per-event deduplication key, distinct from the batch Idempotency-Key; null is treated as absent."
          },
          "type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"
          },
          "occurred_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "RFC3339 timestamp including a timezone."
          },
          "severity": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "info",
              "success",
              "warning",
              "critical",
              null
            ]
          },
          "data": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "properties": {
              "summary": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 500
              },
              "summary_translations": {
                "type": "object",
                "maxProperties": 8,
                "additionalProperties": false,
                "properties": {
                  "en": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "fa": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "ar": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "es": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "fr": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "de": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "pt-BR": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "zh-CN": {
                    "type": "string",
                    "maxLength": 500
                  }
                }
              }
            }
          },
          "context": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "actor": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "subject": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              }
            }
          },
          "tags": {
            "type": [
              "array",
              "null"
            ],
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 50
            }
          },
          "correlation_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "CloudEvent": {
        "type": "object",
        "required": [
          "specversion",
          "id",
          "source",
          "type"
        ],
        "properties": {
          "specversion": {
            "type": "string",
            "const": "1.0"
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Original CloudEvents ID. The adapter maps it to a canonical Givemora Event.id: ce_ plus lowercase SHA-256 of the UTF-8 bytes of \"givemora.com/cloudevents/v1\\0\" + source + \"\\0\" + this id. Use that derived canonical Event.id for Idempotency-Key."
          },
          "source": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "format": "uri-reference",
            "description": "URI reference without user information (userinfo); the adapter rejects userinfo.",
            "allOf": [
              {
                "not": {
                  "pattern": "^[A-Za-z][A-Za-z0-9+.-]*://[^/?#]*@"
                }
              },
              {
                "not": {
                  "pattern": "^//[^/?#]*@"
                }
              }
            ]
          },
          "type": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"
          },
          "time": {
            "type": "string",
            "format": "date-time"
          },
          "subject": {
            "type": "string",
            "maxLength": 512
          },
          "datacontenttype": {
            "type": "string"
          },
          "dataschema": {
            "type": "string",
            "format": "uri"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          },
          "data_base64": {
            "type": "string",
            "contentEncoding": "base64"
          },
          "actor": {
            "type": "object",
            "additionalProperties": true
          },
          "correlationid": {
            "type": "string",
            "maxLength": 128
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "success",
              "warning",
              "critical"
            ]
          },
          "tags": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 50
            }
          },
          "traceparent": {
            "type": "string"
          },
          "tracestate": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "not": {
          "required": [
            "data",
            "data_base64"
          ]
        }
      },
      "EventBatch": {
        "type": "array",
        "minItems": 1,
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/Event"
        },
        "description": "Ordered body. Default maximum is 100 items and 5 MiB; deployment configuration may tighten limits."
      },
      "AcceptedSubmission": {
        "type": "object",
        "required": [
          "accepted",
          "submission_id",
          "event_id",
          "duplicate",
          "received_at",
          "routing_status",
          "routing",
          "routing_reason",
          "schema_id",
          "schema_version",
          "schema_warnings",
          "request_id"
        ],
        "properties": {
          "accepted": {
            "const": true
          },
          "submission_id": {
            "$ref": "#/components/schemas/Ulid"
          },
          "event_id": {
            "$ref": "#/components/schemas/Ulid"
          },
          "duplicate": {
            "type": "boolean"
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "routing_status": {
            "const": "pending"
          },
          "routing": {
            "const": "pending"
          },
          "routing_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "schema_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "schema_version": {
            "type": [
              "integer",
              "null"
            ]
          },
          "schema_warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "request_id": {
            "$ref": "#/components/schemas/Ulid"
          }
        },
        "additionalProperties": false
      },
      "BatchAcceptedItem": {
        "type": "object",
        "required": [
          "index",
          "status",
          "accepted",
          "retryable",
          "submission_id",
          "event_id",
          "duplicate",
          "routing_status",
          "schema_id",
          "schema_version",
          "schema_warnings"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "status": {
            "const": "accepted"
          },
          "accepted": {
            "const": true
          },
          "retryable": {
            "const": false
          },
          "submission_id": {
            "$ref": "#/components/schemas/Ulid"
          },
          "event_id": {
            "$ref": "#/components/schemas/Ulid"
          },
          "duplicate": {
            "type": "boolean"
          },
          "routing_status": {
            "const": "pending"
          },
          "schema_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "schema_version": {
            "type": [
              "integer",
              "null"
            ]
          },
          "schema_warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false
      },
      "BatchRejectedItem": {
        "type": "object",
        "required": [
          "index",
          "status",
          "accepted",
          "retryable",
          "submission_id",
          "event_id",
          "duplicate",
          "routing_status",
          "schema_id",
          "schema_version",
          "schema_warnings",
          "error"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "status": {
            "const": "rejected"
          },
          "accepted": {
            "const": false
          },
          "retryable": {
            "type": "boolean"
          },
          "error": {
            "$ref": "#/components/schemas/BatchItemError"
          },
          "submission_id": {
            "type": "null"
          },
          "event_id": {
            "type": "null"
          },
          "duplicate": {
            "const": false
          },
          "routing_status": {
            "type": "null"
          },
          "schema_id": {
            "type": "null"
          },
          "schema_version": {
            "type": "null"
          },
          "schema_warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 0
          }
        },
        "additionalProperties": false
      },
      "BatchItemError": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "additionalProperties": false
      },
      "BatchItem": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/BatchAcceptedItem"
          },
          {
            "$ref": "#/components/schemas/BatchRejectedItem"
          }
        ]
      },
      "CompletedBatch": {
        "type": "object",
        "required": [
          "accepted",
          "receipt_id",
          "status",
          "items",
          "request_id"
        ],
        "properties": {
          "accepted": {
            "const": true
          },
          "receipt_id": {
            "$ref": "#/components/schemas/Ulid"
          },
          "status": {
            "const": "completed"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchItem"
            }
          },
          "request_id": {
            "$ref": "#/components/schemas/Ulid"
          }
        },
        "additionalProperties": false
      },
      "IncompleteBatch": {
        "type": "object",
        "required": [
          "error",
          "receipt_id",
          "status"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "request_id",
              "details"
            ],
            "properties": {
              "code": {
                "const": "ingestion_temporarily_unavailable"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "$ref": "#/components/schemas/Ulid"
              },
              "details": {
                "type": "object",
                "required": [
                  "reason",
                  "receipt_id"
                ],
                "properties": {
                  "reason": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "receipt_id": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 1,
                    "items": {
                      "$ref": "#/components/schemas/Ulid"
                    }
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          },
          "receipt_id": {
            "$ref": "#/components/schemas/Ulid"
          },
          "status": {
            "const": "incomplete"
          }
        },
        "additionalProperties": true
      },
      "SubmissionStatus": {
        "type": "object",
        "description": "A payload-free poll result. routing_status is the durable lifecycle enum; routing is an independent nullable string decision and is not constrained to the lifecycle values.",
        "required": [
          "submission_id",
          "event_id",
          "received_at",
          "routing_status",
          "routing",
          "routing_reason",
          "routing_explain",
          "request_id"
        ],
        "properties": {
          "submission_id": {
            "$ref": "#/components/schemas/Ulid"
          },
          "event_id": {
            "$ref": "#/components/schemas/Ulid"
          },
          "received_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "routing_status": {
            "type": "string",
            "enum": [
              "pending",
              "routed",
              "blocked",
              "failed"
            ],
            "description": "Durable submission lifecycle state. This is not the routing decision in routing."
          },
          "routing": {
            "type": [
              "string",
              "null"
            ],
            "description": "Current routing decision, independently reported as any string or null; it may differ from routing_status."
          },
          "routing_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "routing_explain": {
            "type": [
              "object",
              "array",
              "null"
            ],
            "description": "Sanitized explanation; never includes the submitted payload.",
            "items": {}
          },
          "request_id": {
            "$ref": "#/components/schemas/Ulid"
          }
        },
        "additionalProperties": false
      },
      "BatchReceiptPage": {
        "type": "object",
        "required": [
          "receipt_id",
          "status",
          "items",
          "next_cursor",
          "request_id"
        ],
        "properties": {
          "receipt_id": {
            "$ref": "#/components/schemas/Ulid"
          },
          "status": {
            "type": "string",
            "enum": [
              "incomplete",
              "completed"
            ]
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchReceiptItem"
            },
            "maxItems": 100
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{1,8}$"
          },
          "request_id": {
            "$ref": "#/components/schemas/Ulid"
          }
        },
        "additionalProperties": false
      },
      "BatchReceiptItem": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/BatchAcceptedItem"
          },
          {
            "$ref": "#/components/schemas/BatchReceiptRejectedItem"
          }
        ]
      },
      "BatchReceiptRejectedItem": {
        "type": "object",
        "required": [
          "index",
          "status",
          "accepted",
          "retryable",
          "submission_id",
          "event_id",
          "duplicate",
          "routing_status",
          "schema_id",
          "schema_version",
          "schema_warnings",
          "error"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "status": {
            "const": "rejected"
          },
          "accepted": {
            "const": false
          },
          "retryable": {
            "type": "boolean"
          },
          "error": {
            "type": "object",
            "required": [
              "code"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            },
            "additionalProperties": false
          },
          "submission_id": {
            "type": "null"
          },
          "event_id": {
            "type": "null"
          },
          "duplicate": {
            "const": false
          },
          "routing_status": {
            "type": "null"
          },
          "schema_id": {
            "type": "null"
          },
          "schema_version": {
            "type": "null"
          },
          "schema_warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 0
          }
        },
        "additionalProperties": false
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "$ref": "#/components/schemas/Ulid"
              },
              "details": {}
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      }
    }
  },
  "x-idempotency": {
    "default_retention_days": 30,
    "configurable": true,
    "expiry_behavior": "If acceptance is ambiguous beyond the server retention horizon, manually reconcile before taking action. Do not silently create a new idempotency key or replay an expired request.",
    "namespaces": [
      "v2 single-event",
      "v2 batch",
      "v1"
    ]
  }
}
