{
  "openapi": "3.1.0",
  "info": {
    "title": "Givemora Events API",
    "version": "0.1.0",
    "description": "OpenAPI contract for the public event catalog, first project credential request/claim/acknowledgement lifecycle, project-credential event ingestion, batch ingestion, and generic signed webhook ingestion. The four SDKs remain 0.1.0 previews; this artifact does not claim package publication."
  },
  "servers": [
    {
      "url": "https://givemora.com"
    }
  ],
  "paths": {
    "/v1/event-catalog": {
      "get": {
        "operationId": "api_get_v1_event_catalog",
        "summary": "Get the public event catalog and safe standard templates.",
        "x-authentication": {
          "scheme": null
        },
        "x-success-status": 200,
        "parameters": [
          {
            "name": "Accept-Language",
            "in": "header",
            "required": false,
            "description": "Optional, ordered language preferences. The first supported locale is used for data.locale; unsupported values are skipped. Defaults to en when no supported preference is provided.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Get the public event catalog and safe standard templates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/P9StableRateLimited"
          }
        },
        "x-contract-status": "live",
        "x-route-source": "App\\Http\\Controllers\\Api\\V1\\EventCatalogController",
        "security": [],
        "x-error-contract": {
          "rate_limit_exceeded": {
            "status": 429,
            "retryable": true,
            "retry_after": "delta-seconds",
            "example": {
              "error": {
                "code": "rate_limit_exceeded",
                "message": "The request limit has been reached.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          }
        },
        "x-error-contract-note": "Only stable machine codes are listed. Human messages may be localized; retryable and Retry-After behavior are operation metadata.",
        "x-public-access": {
          "reason": "The catalog exposes only public event types and safe standard templates."
        },
        "x-request-body": "none"
      }
    },
    "/v1/events": {
      "post": {
        "operationId": "api_post_v1_events",
        "summary": "Ingest one event",
        "description": "Accept one event using a project environment credential with the events:write scope. The endpoint validates the event envelope and configured payload and schema limits; it also accepts CloudEvents structured JSON or HTTP binary mode. A valid request returns HTTP 202 with the durable acceptance and routing result. Idempotency-Key is optional: while a producer-key receipt is retained, repeating the same key and canonical body returns the stored result with duplicate status; reusing that key with a different body returns HTTP 409. Event-payload retention follows project policy independently of the deduplication receipt.",
        "security": [
          {
            "ProjectCredential": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "ce-specversion",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "const": "1.0"
            },
            "description": "Required only when sending CloudEvents HTTP binary mode; structured and legacy JSON requests omit this header."
          },
          {
            "name": "ce-id",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required only when sending CloudEvents HTTP binary mode; structured and legacy JSON requests omit this header."
          },
          {
            "name": "ce-source",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required only when sending CloudEvents HTTP binary mode; structured and legacy JSON requests omit this header."
          },
          {
            "name": "ce-type",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Required only when sending CloudEvents HTTP binary mode; structured and legacy JSON requests omit this header."
          },
          {
            "name": "ce-time",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Optional CloudEvents occurrence time."
          },
          {
            "name": "ce-subject",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional CloudEvents subject."
          },
          {
            "name": "ce-dataschema",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Optional allowlisted schema URI."
          },
          {
            "name": "ce-correlationid",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional Givemora correlation ID."
          },
          {
            "name": "ce-severity",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "info",
                "success",
                "warning",
                "critical"
              ]
            },
            "description": "Optional Givemora severity."
          },
          {
            "name": "ce-traceparent",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional W3C traceparent; an ordinary traceparent HTTP header takes precedence."
          },
          {
            "name": "ce-tracestate",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional W3C tracestate, valid only with ce-traceparent."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event",
                "description": "Maximum event request size is 256 KiB by default; server configuration may tighten limits."
              },
              "example": {
                "id": "order-event-123",
                "type": "invoice.paid",
                "occurred_at": "2026-10-14T11:30:00Z",
                "data": {
                  "invoice_id": "inv_123",
                  "amount_minor": 1299,
                  "currency": "USD"
                }
              }
            },
            "application/cloudevents+json": {
              "schema": {
                "type": "object",
                "required": [
                  "specversion",
                  "id",
                  "source",
                  "type"
                ],
                "properties": {
                  "specversion": {
                    "const": "1.0"
                  },
                  "id": {
                    "type": "string",
                    "maxLength": 256
                  },
                  "source": {
                    "type": "string",
                    "maxLength": 2048,
                    "format": "uri-reference"
                  },
                  "type": {
                    "type": "string",
                    "maxLength": 100,
                    "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"
                  },
                  "time": {
                    "type": "string",
                    "maxLength": 64,
                    "format": "date-time"
                  },
                  "subject": {
                    "type": "string",
                    "maxLength": 512
                  },
                  "datacontenttype": {
                    "type": "string",
                    "maxLength": 128,
                    "description": "For object data, use application/json or an application/*+json media type. For data_base64, the server validates the media type."
                  },
                  "dataschema": {
                    "type": "string",
                    "maxLength": 2048,
                    "format": "uri",
                    "description": "Must match a server-configured URI allowlist. The server never fetches this URI."
                  },
                  "data": {
                    "type": "object"
                  },
                  "data_base64": {
                    "type": "string",
                    "contentEncoding": "base64",
                    "description": "Strict canonical RFC 4648 base64; decoded bytes must not exceed the configured event payload limit."
                  },
                  "traceparent": {
                    "type": "string",
                    "maxLength": 512,
                    "description": "Optional W3C traceparent."
                  },
                  "tracestate": {
                    "type": "string",
                    "maxLength": 512,
                    "description": "Optional W3C tracestate; valid only when traceparent is present."
                  },
                  "actor": {
                    "type": "object",
                    "description": "Optional structured actor metadata."
                  },
                  "correlationid": {
                    "type": "string",
                    "maxLength": 128
                  },
                  "severity": {
                    "type": "string",
                    "enum": [
                      "info",
                      "success",
                      "warning",
                      "critical"
                    ]
                  },
                  "tags": {
                    "type": "array",
                    "maxItems": 20,
                    "uniqueItems": true,
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 50,
                      "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
                    }
                  }
                },
                "oneOf": [
                  {
                    "required": [
                      "data"
                    ]
                  },
                  {
                    "required": [
                      "data_base64"
                    ]
                  }
                ],
                "dependentRequired": {
                  "tracestate": [
                    "traceparent"
                  ]
                },
                "additionalProperties": false,
                "description": "CloudEvents 1.0 structured JSON. Supply exactly one of data or data_base64. For data_base64, the adapter stores opaque bytes as canonical data {\"_givemora_binary\":{\"encoding\":\"base64\",\"value\":\"<canonical-base64>\"}} and preserves datacontenttype in context.cloud_event; bytes that resemble JSON are not parsed. The request body and decoded bytes are subject to configured limits. The adapter maps id/source/type/time and supported context attributes into the canonical event envelope; unknown extensions are rejected. dataschema is checked against the server allowlist and is never fetched. See the operation's x-cloudevents-http-binary contract for raw-body binary mode."
              },
              "example": {
                "specversion": "1.0",
                "id": "evt-123",
                "source": "urn:example:billing",
                "type": "invoice.paid",
                "time": "2026-10-14T11:30:00Z",
                "data": {
                  "invoice_id": "inv_123",
                  "amount_minor": 1299,
                  "currency": "USD"
                }
              }
            },
            "*/*": {
              "schema": {
                "type": "string",
                "format": "binary",
                "description": "CloudEvents HTTP binary mode: raw body bytes become opaque event data; Content-Type maps to datacontenttype. Required and supported attributes are sent in ce-* headers."
              },
              "example": "{\"status\":\"ready\"}"
            }
          }
        },
        "x-cloudevents-http-binary": {
          "enabled": true,
          "content_mode": "binary",
          "data": "raw-body-bytes",
          "required_headers": [
            "ce-specversion",
            "ce-id",
            "ce-source",
            "ce-type"
          ],
          "attribute_headers": "ce-*",
          "header_value_decoding": "unescape HTTP quoted strings, then percent-decode once",
          "content_type_maps_to": "datacontenttype (exact header value)",
          "ce_datacontenttype_header_allowed": false,
          "structured_only_attributes": [
            "actor",
            "tags"
          ],
          "decoded_bytes_limit": "personal.limits.event_payload_bytes",
          "signature": {
            "required": false,
            "headers": [
              "X-Givemora-Timestamp",
              "X-Givemora-Nonce",
              "X-Givemora-Signature"
            ],
            "algorithm": "HMAC-SHA256",
            "key": "project bearer credential",
            "signature_header_format": "sha256=<lowercase-hex>",
            "signing_input": "givemora-cloudevents-http-binary-v1\\n{timestamp}\\n{nonce}\\n{canonical-json}\\n{sha256-hex(raw-body)}",
            "canonical_json": "normalized lowercase attribute map, exact Content-Type as datacontenttype when present, keys sorted lexicographically recursively, JSON_UNESCAPED_UNICODE and JSON_UNESCAPED_SLASHES",
            "partial_signature_headers": "rejected",
            "body_only_signature": "rejected"
          }
        },
        "responses": {
          "202": {
            "description": "The event was durably accepted or matched as a duplicate.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/IngestionRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AcceptedEvent"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/EventIngestionCorrelatedError"
          },
          "409": {
            "$ref": "#/components/responses/EventIngestionCorrelatedError"
          },
          "413": {
            "$ref": "#/components/responses/EventIngestionCorrelatedError"
          },
          "422": {
            "$ref": "#/components/responses/EventIngestionCorrelatedError"
          },
          "429": {
            "$ref": "#/components/responses/EventIngestionRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/EventIngestionCorrelatedError"
          },
          "401": {
            "$ref": "#/components/responses/EventIngestionError"
          },
          "403": {
            "$ref": "#/components/responses/EventIngestionError"
          }
        },
        "x-idempotency": "Event-key deduplication is scoped to workspace, project, environment, and producer key (the key may come from event.id; if both are supplied they must match). Its fixed per-deployment horizon is configured by personal.ingestion.idempotency_retention_days (default 30 days). While the receipt is unexpired, the same key and canonical body replays the stored result, and the same key with a different body returns 409 idempotency_conflict. After expiry, the producer key may be accepted as a new event and cause new side effects. Event-payload retention is governed independently by project policy; the receipt snapshot does not contain payload. Network exactly-once delivery or side effects are not guaranteed.",
        "x-ordering": "No server-side event ordering guarantee. SDK outboxes preserve FIFO only within the caller-selected partition.",
        "x-success-status": 202,
        "x-contract-status": "live",
        "x-route-source": "App\\Http\\Controllers\\Api\\V1\\EventController@store",
        "x-authentication": {
          "scheme": "ProjectCredential",
          "scope": "events:write"
        },
        "x-rate-limit-policy": {
          "window_seconds_default": 60,
          "window_seconds_configuration": "personal.limits.rate.decay_seconds",
          "enforcement": "All buckets are independently enforced. An accepted request consumes one attempt from each bucket; a request is rejected when any bucket is exhausted.",
          "retry_after": "positive delta-seconds for the longest remaining exhausted bucket window",
          "pre_authentication": {
            "applies_to": "All event, batch, and generic webhook requests before project credential lookup.",
            "scope": "resolved source IP; invalid or missing IP values share one bounded unknown bucket",
            "default_requests": 600,
            "window_seconds_default": 60,
            "limit_configuration": "personal.limits.rate.ingestion_pre_auth_per_ip_per_minute",
            "trusted_proxy_configuration": "personal.limits.rate.ingestion_trusted_proxies",
            "proxy_headers": "CF-Connecting-IP and X-Forwarded-For are honored only when REMOTE_ADDR matches a configured trusted proxy CIDR."
          },
          "buckets": [
            {
              "scope": "credential",
              "default_requests": 60,
              "limit_configuration": "personal.limits.rate.ingestion_key_per_minute"
            },
            {
              "scope": "project",
              "default_requests": 120,
              "limit_configuration": "personal.limits.rate.ingestion_project_per_minute"
            },
            {
              "scope": "workspace",
              "default_requests": 300,
              "limit_configuration": "personal.limits.rate.ingestion_workspace_per_minute"
            }
          ]
        },
        "x-error-contract": {
          "unauthenticated": {
            "status": 401,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "unauthenticated"
              }
            }
          },
          "insufficient_scope": {
            "status": 403,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "insufficient_scope"
              }
            }
          },
          "rate_limit_exceeded": {
            "status": 429,
            "retryable": true,
            "retry_after": "delta-seconds",
            "example": {
              "error": {
                "code": "rate_limit_exceeded",
                "message": "The request limit has been reached.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "payload_too_large": {
            "status": 413,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "payload_too_large",
                "message": "The event payload is too large.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "signature_headers_incomplete": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_headers_incomplete"
              }
            }
          },
          "signature_timestamp_invalid": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_timestamp_invalid"
              }
            }
          },
          "signature_timestamp_expired": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_timestamp_expired"
              }
            }
          },
          "signature_nonce_invalid": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_nonce_invalid"
              }
            }
          },
          "signature_invalid": {
            "status": 401,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_invalid"
              }
            }
          },
          "signature_replay": {
            "status": 409,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_replay"
              }
            }
          },
          "malformed_json": {
            "status": 400,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "malformed_json",
                "message": "The event body is not valid JSON.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "validation_failed": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "validation_failed",
                "message": "The event request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "idempotency_key_mismatch": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "idempotency_key_mismatch",
                "message": "The event request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "idempotency_conflict": {
            "status": 409,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "idempotency_conflict",
                "message": "The event request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "billing_quota_exceeded": {
            "status": 429,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "billing_quota_exceeded",
                "message": "The event request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "ingestion_temporarily_unavailable": {
            "status": 503,
            "retryable": true,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "ingestion_temporarily_unavailable",
                "message": "The request could not be processed at this time.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          }
        },
        "x-error-contract-note": "The response body has no top-level retryable field. retryable describes whether clients may automatically retry the same unchanged request; false means correct the request or re-check quota before resubmission. rate_limit_exceeded carries Retry-After as positive delta-seconds; all other listed codes omit it."
      }
    },
    "/v1/events/batch": {
      "post": {
        "operationId": "api_post_v1_events_batch",
        "summary": "Ingest a batch of events",
        "description": "Accept a bounded array of events using a project environment credential with the events:write scope. JSON and CloudEvents batch JSON are supported; the endpoint validates the batch and each event independently, then returns HTTP 202 with one outcome per item, including rejected items. Supplying Idempotency-Key creates a durable batch receipt: retrying the same key and identical request body resumes or returns the same receipt and item outcomes, while a changed body under that key returns HTTP 409. If capacity interrupts processing, HTTP 503 identifies the incomplete receipt, which can be resumed by retrying the same request. Batch-receipt retention and event-payload retention follow separate policies.",
        "security": [
          {
            "ProjectCredential": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "minItems": 1,
                "maxItems": 100,
                "items": {
                  "$ref": "#/components/schemas/Event"
                },
                "description": "Maximum batch body is 5 MiB by default; each event has the 256 KiB default limit. Server configuration may tighten limits."
              },
              "example": [
                {
                  "id": "order-event-123",
                  "type": "invoice.paid",
                  "occurred_at": "2026-10-14T11:30:00Z",
                  "data": {
                    "invoice_id": "inv_123",
                    "amount_minor": 1299,
                    "currency": "USD"
                  }
                }
              ]
            },
            "application/cloudevents-batch+json": {
              "schema": {
                "type": "array",
                "minItems": 1,
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "required": [
                    "specversion",
                    "id",
                    "source",
                    "type"
                  ],
                  "properties": {
                    "specversion": {
                      "const": "1.0"
                    },
                    "id": {
                      "type": "string",
                      "maxLength": 256
                    },
                    "source": {
                      "type": "string",
                      "maxLength": 2048,
                      "format": "uri-reference"
                    },
                    "type": {
                      "type": "string",
                      "maxLength": 100,
                      "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"
                    },
                    "time": {
                      "type": "string",
                      "maxLength": 64,
                      "format": "date-time"
                    },
                    "subject": {
                      "type": "string",
                      "maxLength": 512
                    },
                    "datacontenttype": {
                      "type": "string",
                      "maxLength": 128,
                      "description": "For object data, use application/json or an application/*+json media type. For data_base64, the server validates the media type."
                    },
                    "dataschema": {
                      "type": "string",
                      "maxLength": 2048,
                      "format": "uri",
                      "description": "Must match a server-configured URI allowlist. The server never fetches this URI."
                    },
                    "data": {
                      "type": "object"
                    },
                    "data_base64": {
                      "type": "string",
                      "contentEncoding": "base64",
                      "description": "Strict canonical RFC 4648 base64; decoded bytes must not exceed the configured event payload limit."
                    },
                    "traceparent": {
                      "type": "string",
                      "maxLength": 512,
                      "description": "Optional W3C traceparent."
                    },
                    "tracestate": {
                      "type": "string",
                      "maxLength": 512,
                      "description": "Optional W3C tracestate; valid only when traceparent is present."
                    },
                    "actor": {
                      "type": "object",
                      "description": "Optional structured actor metadata."
                    },
                    "correlationid": {
                      "type": "string",
                      "maxLength": 128
                    },
                    "severity": {
                      "type": "string",
                      "enum": [
                        "info",
                        "success",
                        "warning",
                        "critical"
                      ]
                    },
                    "tags": {
                      "type": "array",
                      "maxItems": 20,
                      "uniqueItems": true,
                      "items": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 50,
                        "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
                      }
                    }
                  },
                  "oneOf": [
                    {
                      "required": [
                        "data"
                      ]
                    },
                    {
                      "required": [
                        "data_base64"
                      ]
                    }
                  ],
                  "dependentRequired": {
                    "tracestate": [
                      "traceparent"
                    ]
                  },
                  "additionalProperties": false
                },
                "description": "A bounded array of CloudEvents 1.0 structured objects. Each item has an independent result. Supply exactly one of data or data_base64. data_base64 uses strict canonical RFC 4648 encoding and is stored opaquely as data {\"_givemora_binary\":{\"encoding\":\"base64\",\"value\":\"<canonical-base64>\"}}; datacontenttype remains in context.cloud_event. Unknown extensions are rejected. HTTP binary content mode is available only on POST /v1/events."
              },
              "example": [
                {
                  "specversion": "1.0",
                  "id": "evt-123",
                  "source": "urn:example:billing",
                  "type": "invoice.paid",
                  "time": "2026-10-14T11:30:00Z",
                  "data": {
                    "invoice_id": "inv_123",
                    "amount_minor": 1299,
                    "currency": "USD"
                  }
                }
              ]
            }
          },
          "description": "Maximum request size is 5 MiB by default; server configuration may tighten limits."
        },
        "responses": {
          "202": {
            "description": "Batch-level acceptance with per-item outcomes; individual items may be rejected.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/IngestionRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/EventIngestionCorrelatedError"
          },
          "413": {
            "$ref": "#/components/responses/EventIngestionCorrelatedError"
          },
          "422": {
            "$ref": "#/components/responses/EventIngestionCorrelatedError"
          },
          "429": {
            "$ref": "#/components/responses/EventBatchRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/EventBatchIncomplete"
          },
          "401": {
            "$ref": "#/components/responses/EventIngestionError"
          },
          "403": {
            "$ref": "#/components/responses/EventIngestionError"
          },
          "409": {
            "$ref": "#/components/responses/EventIngestionCorrelatedError"
          }
        },
        "x-success-status": 202,
        "x-contract-status": "live",
        "x-route-source": "App\\Http\\Controllers\\Api\\V1\\BatchEventController@store",
        "x-authentication": {
          "scheme": "ProjectCredential",
          "scope": "events:write"
        },
        "x-rate-limit-policy": {
          "window_seconds_default": 60,
          "window_seconds_configuration": "personal.limits.rate.decay_seconds",
          "enforcement": "All buckets are independently enforced. An accepted request consumes one attempt from each bucket; a request is rejected when any bucket is exhausted.",
          "retry_after": "positive delta-seconds for the longest remaining exhausted bucket window",
          "pre_authentication": {
            "applies_to": "All event, batch, and generic webhook requests before project credential lookup.",
            "scope": "resolved source IP; invalid or missing IP values share one bounded unknown bucket",
            "default_requests": 600,
            "window_seconds_default": 60,
            "limit_configuration": "personal.limits.rate.ingestion_pre_auth_per_ip_per_minute",
            "trusted_proxy_configuration": "personal.limits.rate.ingestion_trusted_proxies",
            "proxy_headers": "CF-Connecting-IP and X-Forwarded-For are honored only when REMOTE_ADDR matches a configured trusted proxy CIDR."
          },
          "buckets": [
            {
              "scope": "credential",
              "default_requests": 60,
              "limit_configuration": "personal.limits.rate.ingestion_key_per_minute"
            },
            {
              "scope": "project",
              "default_requests": 120,
              "limit_configuration": "personal.limits.rate.ingestion_project_per_minute"
            },
            {
              "scope": "workspace",
              "default_requests": 300,
              "limit_configuration": "personal.limits.rate.ingestion_workspace_per_minute"
            }
          ]
        },
        "x-idempotency": "When Idempotency-Key is supplied, the server stores a batch receipt scoped to workspace, project, environment, and key hash. The fixed per-deployment dedupe horizon for keyed batch receipts and producer event keys is configured by personal.ingestion.idempotency_retention_days (default 30 days). While the receipt is unexpired, the same key and identical request body resumes or returns the same receipt and item outcomes; the same key with a different body returns 409 idempotency_conflict. After expiry, the same producer key may be accepted as a new event and cause new side effects. The receipt_id can be read from the scoped event-receipt endpoint. Without the header, no batch-level replay receipt is created; per-event IDs still use the event-key horizon. Batch receipts expire at expires_at and are removed by the bounded personal:prune-retention process; event-payload retention remains independently governed by project policy. The receipt snapshot does not contain payload. Network exactly-once delivery or side effects are not guaranteed.",
        "x-error-contract": {
          "unauthenticated": {
            "status": 401,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "unauthenticated"
              }
            }
          },
          "insufficient_scope": {
            "status": 403,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "insufficient_scope"
              }
            }
          },
          "rate_limit_exceeded": {
            "status": 429,
            "retryable": true,
            "retry_after": "delta-seconds",
            "example": {
              "error": {
                "code": "rate_limit_exceeded",
                "message": "The request limit has been reached.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "payload_too_large": {
            "status": 413,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "payload_too_large",
                "message": "The event payload is too large.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "signature_headers_incomplete": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_headers_incomplete"
              }
            }
          },
          "signature_timestamp_invalid": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_timestamp_invalid"
              }
            }
          },
          "signature_timestamp_expired": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_timestamp_expired"
              }
            }
          },
          "signature_nonce_invalid": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_nonce_invalid"
              }
            }
          },
          "signature_invalid": {
            "status": 401,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_invalid"
              }
            }
          },
          "signature_replay": {
            "status": 409,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_replay"
              }
            }
          },
          "malformed_json": {
            "status": 400,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "malformed_json",
                "message": "The batch body is not valid JSON.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "validation_failed": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "validation_failed",
                "message": "The batch request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "batch_limit_exceeded": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "batch_limit_exceeded",
                "message": "The batch request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "idempotency_conflict": {
            "status": 409,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "idempotency_conflict",
                "message": "The batch request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "ingestion_temporarily_unavailable": {
            "status": 503,
            "retryable": true,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "ingestion_temporarily_unavailable",
                "message": "The request could not be processed at this time.",
                "request_id": "01J00000000000000000000000",
                "details": []
              },
              "receipt_id": "01J00000000000000000000000",
              "status": "incomplete"
            }
          }
        },
        "x-error-contract-note": "The response body has no top-level retryable field. retryable describes whether clients may automatically retry the same unchanged request; false means correct the request or re-check quota before resubmission. rate_limit_exceeded carries Retry-After as positive delta-seconds; all other listed codes omit it.",
        "x-batch-item-error-contract": {
          "validation_failed": {
            "http_status": 202,
            "retryable": false,
            "retry_after": "not-emitted"
          },
          "payload_too_large": {
            "http_status": 202,
            "retryable": false,
            "retry_after": "not-emitted"
          },
          "billing_quota_exceeded": {
            "http_status": 202,
            "retryable": false,
            "retry_after": "not-emitted"
          },
          "idempotency_conflict": {
            "http_status": 202,
            "retryable": false,
            "retry_after": "not-emitted"
          }
        }
      }
    },
    "/v1/hooks/{source}": {
      "post": {
        "operationId": "api_post_v1_hooks_source",
        "summary": "Accept a generically signed webhook event",
        "description": "This operation documents the generic Givemora HMAC signature mode. Provider-specific signature formats are outside this generic contract and are not guaranteed here.",
        "security": [
          {
            "ProjectCredential": []
          }
        ],
        "parameters": [
          {
            "name": "source",
            "in": "path",
            "required": true,
            "description": "Lowercase source identifier.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9_-]{0,31}$"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "name": "X-Givemora-Timestamp",
            "in": "header",
            "required": true,
            "description": "Decimal Unix timestamp in seconds; accepted within personal.ingestion.signature_tolerance_seconds (default 300 seconds).",
            "schema": {
              "type": "string",
              "pattern": "^-?\\d+$"
            }
          },
          {
            "name": "X-Givemora-Nonce",
            "in": "header",
            "required": true,
            "description": "Unique visible-ASCII nonce for this project credential; 1–128 characters. Reuse is rejected.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[!-~]+$"
            }
          },
          {
            "name": "X-Givemora-Signature",
            "in": "header",
            "required": true,
            "description": "Generic Givemora HMAC-SHA256 signature of timestamp + '.' + nonce + '.' + the exact raw request body bytes.",
            "schema": {
              "type": "string",
              "pattern": "^sha256=[a-f0-9]{64}$"
            }
          },
          {
            "name": "X-Givemora-Event-Type",
            "in": "header",
            "required": false,
            "description": "Canonical event type override; when omitted, the default is webhook.<source> with hyphens replaced by underscores.",
            "schema": {
              "type": "string",
              "maxLength": 100,
              "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"
            }
          },
          {
            "name": "X-Givemora-Event-Id",
            "in": "header",
            "required": false,
            "description": "Optional producer event ID used for deduplication. If Idempotency-Key is also supplied, the values must match.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          {
            "name": "X-Givemora-Occurred-At",
            "in": "header",
            "required": false,
            "description": "Optional RFC3339 timestamp with timezone for the canonical event.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "X-Givemora-Severity",
            "in": "header",
            "required": false,
            "description": "Optional canonical event severity; defaults to info.",
            "schema": {
              "type": "string",
              "enum": [
                "info",
                "success",
                "warning",
                "critical"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Send a non-empty JSON object as the raw provider body with application/json. The controller parses raw request bytes as JSON and does not gate parsing on Content-Type; empty objects, JSON arrays, and malformed JSON are rejected. The full object becomes canonical event data, with sensitive key names redacted. The configured event-payload byte limit defaults to 256 KiB and may be tightened by the server.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "minProperties": 1,
                "additionalProperties": true
              },
              "example": {
                "id": "evt-123",
                "status": "paid",
                "external_reference": "order-123"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The normalized event was durably accepted or matched as a duplicate.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AcceptedEvent"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/EventIngestionError"
          },
          "401": {
            "$ref": "#/components/responses/EventIngestionError"
          },
          "403": {
            "$ref": "#/components/responses/EventIngestionError"
          },
          "409": {
            "$ref": "#/components/responses/EventIngestionError"
          },
          "413": {
            "$ref": "#/components/responses/EventIngestionError"
          },
          "422": {
            "$ref": "#/components/responses/EventIngestionError"
          },
          "429": {
            "$ref": "#/components/responses/EventIngestionRateLimited"
          },
          "503": {
            "$ref": "#/components/responses/EventIngestionError"
          }
        },
        "x-webhook-signature": {
          "mode": "generic HMAC-SHA256",
          "required_headers": [
            "X-Givemora-Timestamp",
            "X-Givemora-Nonce",
            "X-Givemora-Signature"
          ],
          "algorithm": "HMAC-SHA256",
          "key": "raw project bearer credential",
          "signing_input": "{timestamp}.{nonce}.{raw-request-body-bytes}",
          "signature_header_format": "sha256=<64 lowercase hexadecimal characters>",
          "timestamp_tolerance": "personal.ingestion.signature_tolerance_seconds (default 300 seconds)",
          "nonce_scope": "unique per project credential; a replay is rejected",
          "provider_native_formats": "Provider-specific signature formats are outside this generic contract and are not guaranteed by this OpenAPI document."
        },
        "x-webhook-normalization": {
          "source": "lowercase identifier matching ^[a-z][a-z0-9_-]{0,31}$",
          "provider_body": "JSON object mapped to canonical event data",
          "event_type": "X-Givemora-Event-Type or webhook.<source> (hyphens become underscores)",
          "event_id": "X-Givemora-Event-Id, optionally equal to Idempotency-Key",
          "occurred_at": "Optional X-Givemora-Occurred-At; RFC3339 with timezone",
          "severity": "Optional X-Givemora-Severity; defaults to info"
        },
        "x-idempotency": "Idempotency-Key is optional and must be 1–128 visible ASCII characters. If X-Givemora-Event-Id is also supplied, the two values must match. Event-key deduplication is scoped to workspace, project, environment, and producer key with the fixed per-deployment horizon personal.ingestion.idempotency_retention_days (default 30 days). While the receipt is unexpired, the same key and normalized body replays the stored result and the same key with a different body conflicts; after expiry, the producer key may be accepted as a new event and cause new side effects.",
        "x-success-status": 202,
        "x-contract-status": "live",
        "x-route-source": "App\\Http\\Controllers\\Api\\V1\\IncomingWebhookController@store",
        "x-authentication": {
          "scheme": "ProjectCredential",
          "scope": "events:write"
        },
        "x-rate-limit-policy": {
          "pre_authentication": {
            "applies_to": "All event, batch, and generic webhook requests before project credential lookup.",
            "scope": "resolved source IP; invalid or missing IP values share one bounded unknown bucket",
            "default_requests": 600,
            "window_seconds_default": 60,
            "limit_configuration": "personal.limits.rate.ingestion_pre_auth_per_ip_per_minute",
            "trusted_proxy_configuration": "personal.limits.rate.ingestion_trusted_proxies",
            "proxy_headers": "CF-Connecting-IP and X-Forwarded-For are honored only when REMOTE_ADDR matches a configured trusted proxy CIDR."
          }
        },
        "x-error-contract": {
          "unauthenticated": {
            "status": 401,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "unauthenticated"
              }
            }
          },
          "insufficient_scope": {
            "status": 403,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "insufficient_scope"
              }
            }
          },
          "signature_headers_incomplete": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_headers_incomplete"
              }
            }
          },
          "signature_timestamp_invalid": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_timestamp_invalid"
              }
            }
          },
          "signature_timestamp_expired": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_timestamp_expired"
              }
            }
          },
          "signature_nonce_invalid": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_nonce_invalid"
              }
            }
          },
          "signature_invalid": {
            "status": 401,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_invalid"
              }
            }
          },
          "signature_replay": {
            "status": 409,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "signature_replay"
              }
            }
          },
          "malformed_json": {
            "status": 400,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "malformed_json",
                "message": "The webhook body is not valid JSON.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "validation_failed": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "validation_failed",
                "message": "The webhook request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "idempotency_key_mismatch": {
            "status": 422,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "idempotency_key_mismatch",
                "message": "The webhook request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "idempotency_conflict": {
            "status": 409,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "idempotency_conflict",
                "message": "The webhook request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "payload_too_large": {
            "status": 413,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "payload_too_large",
                "message": "The event payload is too large.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "rate_limit_exceeded": {
            "status": 429,
            "retryable": true,
            "retry_after": "delta-seconds",
            "example": {
              "error": {
                "code": "rate_limit_exceeded",
                "message": "The request limit has been reached.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "billing_quota_exceeded": {
            "status": 429,
            "retryable": false,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "billing_quota_exceeded",
                "message": "The event request is invalid.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          },
          "ingestion_temporarily_unavailable": {
            "status": 503,
            "retryable": true,
            "retry_after": "not-emitted",
            "example": {
              "error": {
                "code": "ingestion_temporarily_unavailable",
                "message": "The request could not be processed at this time.",
                "request_id": "01J00000000000000000000000",
                "details": []
              }
            }
          }
        },
        "x-error-contract-note": "Retryability is operation metadata and is not a JSON property. Only rate_limit_exceeded emits Retry-After as delta-seconds."
      }
    },
    "/v1/project-credential-requests": {
      "post": {
        "operationId": "api_post_v1_project_credential_requests",
        "summary": "Request a first project credential",
        "description": "Create an opaque project-credential request without requiring an existing credential. The POST returns HTTP 202 and current lifecycle metadata; an idempotent replay may therefore report pending, approved, rejected, issued, acknowledged, or expired status. The target workspace and project must already exist. Submit either their exact names/slug or explicit IDs. Ambiguous and unknown targets receive the same opaque 202 response; only a God operator can resolve and approve an existing target. The client must generate and persist a 32-byte random base64url retrieval_proof, exact body, and Idempotency-Key before the first attempt. A successful submission returns metadata only; no active key exists until God approval and claim. Pending requests expire after 24 hours. Request bodies are limited to 8 KiB; creation is limited to 5 requests per minute per IP and global pending capacity is 10,000. Approved-but-unclaimed requests also expire after 24 hours. Request and idempotency metadata is retained for 30 days after request expiry, then purged. Pending capacity is 100 per resolved workspace/project pair, 10 per unresolved reference pair, and 1,000 unresolved globally within 10,000 total. Idempotent retries consume no additional slot; capacity exhaustion returns 429 with Retry-After.",
        "security": [],
        "x-authentication": {
          "scheme": null
        },
        "x-public-access": {
          "reason": "A client without an existing project credential must be able to request one; approval and key delivery remain bound to the private retrieval proof and God decision."
        },
        "x-success-status": 202,
        "x-contract-status": "live",
        "x-idempotency": {
          "key": "required Idempotency-Key header",
          "scope": "client key and canonical request body",
          "replay": "Same key and same body return the same request’s current opaque lifecycle metadata, which may reflect issued or acknowledged; a changed body conflicts.",
          "retention": "Request/idempotency metadata retained 30 days after request expiry."
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[!-~]{1,128}$"
            },
            "description": "Required 1–128 printable ASCII characters; reuse the same value with the exact same body for an idempotent retry."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "workspace_id": {
                    "type": "string",
                    "description": "Explicit existing workspace ID."
                  },
                  "project_slug": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 63
                  },
                  "project_id": {
                    "type": "string",
                    "description": "Explicit existing project ID."
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "development",
                      "staging",
                      "production"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "retrieval_proof": {
                    "type": "string",
                    "minLength": 43,
                    "maxLength": 128,
                    "pattern": "^[A-Za-z0-9_-]{43,128}$",
                    "description": "Client-generated random base64url value from at least 32 random bytes, without padding. A 32-byte value is 43 characters. Persist securely; never log or share it."
                  }
                },
                "required": [
                  "environment",
                  "name",
                  "retrieval_proof"
                ],
                "additionalProperties": false,
                "oneOf": [
                  {
                    "required": [
                      "workspace_name",
                      "project_slug"
                    ],
                    "not": {
                      "anyOf": [
                        {
                          "required": [
                            "workspace_id"
                          ]
                        },
                        {
                          "required": [
                            "project_id"
                          ]
                        }
                      ]
                    }
                  },
                  {
                    "required": [
                      "workspace_id",
                      "project_id"
                    ],
                    "not": {
                      "anyOf": [
                        {
                          "required": [
                            "workspace_name"
                          ]
                        },
                        {
                          "required": [
                            "project_slug"
                          ]
                        }
                      ]
                    }
                  }
                ]
              },
              "examples": {
                "fusionpointai_production": {
                  "summary": "Existing named target; synthetic example",
                  "value": {
                    "workspace_name": "fusionpointai",
                    "project_slug": "fusionpointai",
                    "environment": "production",
                    "name": "fusionpointai production",
                    "retrieval_proof": "<43-to-128-character-base64url-proof>"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Opaque request metadata; contains no project credential. On an idempotent replay, status reflects the current request lifecycle and may be issued or acknowledged.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "request_code": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "approved",
                            "rejected",
                            "issued",
                            "acknowledged",
                            "expired"
                          ]
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "poll_interval": {
                          "type": "integer",
                          "const": 5
                        },
                        "revision": {
                          "type": "integer",
                          "minimum": 1
                        }
                      },
                      "required": [
                        "id",
                        "request_code",
                        "status",
                        "expires_at",
                        "poll_interval",
                        "revision"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "404": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "409": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "413": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "422": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "429": {
            "$ref": "#/components/responses/P9StableRateLimited"
          }
        },
        "x-error-contract": {
          "idempotency_conflict": {
            "status": 409,
            "retryable": false,
            "example": {
              "error": {
                "code": "idempotency_conflict"
              }
            }
          },
          "payload_too_large": {
            "status": 413,
            "retryable": false,
            "example": {
              "error": {
                "code": "payload_too_large"
              }
            }
          },
          "validation_failed": {
            "status": 422,
            "retryable": false,
            "example": {
              "error": {
                "code": "validation_failed"
              }
            }
          },
          "rate_limit_exceeded": {
            "status": 429,
            "retryable": true,
            "retry_after": "delta-seconds",
            "example": {
              "error": {
                "code": "rate_limit_exceeded"
              }
            }
          }
        },
        "x-request-body-limit-bytes": 8192,
        "x-rate-limit": {
          "limit": 5,
          "period_seconds": 60,
          "key": "IP",
          "retry_after_on_429": true,
          "config_backed": true
        },
        "x-pending-capacity": {
          "total": 10000,
          "per_resolved_workspace_project_pair": 100,
          "per_unresolved_reference_pair": 10,
          "unresolved_global": 1000,
          "idempotent_retries_consume_extra_capacity": false,
          "config_backed": true
        },
        "x-cache": "no-store",
        "x-capacity-limit-status": 429,
        "x-capacity-limit-retry-after": true
      }
    },
    "/v1/project-credential-requests/{id}": {
      "get": {
        "operationId": "api_get_v1_project_credential_requests_id",
        "summary": "Read project credential request status",
        "description": "Return lifecycle metadata only. The retrieval proof is required; an unknown ID and an incorrect proof use the same 404 request_not_found response. This operation never returns a project key.",
        "security": [],
        "x-authentication": {
          "scheme": "Bearer retrieval proof"
        },
        "x-success-status": 200,
        "x-contract-status": "live",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Opaque request ID returned by the submission response."
          },
          {
            "name": "Authorization",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^Bearer .+$"
            },
            "description": "Bearer token is the client-generated retrieval_proof."
          }
        ],
        "responses": {
          "200": {
            "description": "Request lifecycle metadata only.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "request_code": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "approved",
                            "rejected",
                            "issued",
                            "acknowledged",
                            "expired"
                          ]
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "poll_interval": {
                          "type": "integer",
                          "const": 5
                        },
                        "revision": {
                          "type": "integer",
                          "minimum": 1
                        }
                      },
                      "required": [
                        "id",
                        "request_code",
                        "status",
                        "expires_at",
                        "poll_interval",
                        "revision"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "404": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "410": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "429": {
            "$ref": "#/components/responses/P9StableRateLimited"
          }
        },
        "x-error-contract": {
          "request_not_found": {
            "status": 404,
            "retryable": false,
            "example": {
              "error": {
                "code": "request_not_found"
              }
            }
          },
          "request_expired": {
            "status": 410,
            "retryable": false,
            "example": {
              "error": {
                "code": "request_expired"
              }
            }
          },
          "rate_limit_exceeded": {
            "status": 429,
            "retryable": true,
            "retry_after": "delta-seconds",
            "example": {
              "error": {
                "code": "rate_limit_exceeded"
              }
            }
          }
        },
        "x-rate-limit": {
          "limit": 30,
          "period_seconds": 60,
          "key": "request and IP",
          "aggregate_limit": 120,
          "aggregate_period_seconds": 60,
          "aggregate_key": "IP",
          "retry_after_on_429": true,
          "config_backed": true
        },
        "x-cache": "no-store"
      }
    },
    "/v1/project-credential-requests/{id}/claim": {
      "post": {
        "operationId": "api_post_v1_project_credential_requests_id_claim",
        "summary": "Claim an approved project credential",
        "description": "Requires the request retrieval proof and an approved request. The first response is 201; replay within the 15-minute encrypted delivery window returns the same token as 200 so the client can recover from an ambiguous timeout. Store the secret securely and acknowledge possession promptly. Pending requests cannot issue a credential. Expiration of this replay ciphertext does not revoke the issued key. A client that still has the key may acknowledge later; if it lost the key after replay expiry, a new request or authorized issuance is required.",
        "security": [],
        "x-authentication": {
          "scheme": "Bearer retrieval proof"
        },
        "x-success-status": 201,
        "x-contract-status": "live",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Opaque request ID returned by the submission response."
          },
          {
            "name": "Authorization",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^Bearer .+$"
            },
            "description": "Bearer token is the client-generated retrieval_proof."
          }
        ],
        "responses": {
          "201": {
            "description": "Credential issued once to the authorized requester.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string"
                        },
                        "credential_id": {
                          "type": "string"
                        },
                        "project_id": {
                          "type": "string"
                        },
                        "environment": {
                          "type": "string",
                          "enum": [
                            "development",
                            "staging",
                            "production"
                          ]
                        },
                        "replay_expires_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "token",
                        "credential_id",
                        "project_id",
                        "environment",
                        "replay_expires_at"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "200": {
            "description": "Idempotent replay of the still-live encrypted delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string"
                        },
                        "credential_id": {
                          "type": "string"
                        },
                        "project_id": {
                          "type": "string"
                        },
                        "environment": {
                          "type": "string",
                          "enum": [
                            "development",
                            "staging",
                            "production"
                          ]
                        },
                        "replay_expires_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "token",
                        "credential_id",
                        "project_id",
                        "environment",
                        "replay_expires_at"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "403": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "404": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "409": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "410": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "429": {
            "$ref": "#/components/responses/P9StableRateLimited"
          }
        },
        "x-error-contract": {
          "approval_required": {
            "status": 409,
            "retryable": false,
            "example": {
              "error": {
                "code": "approval_required"
              }
            }
          },
          "request_rejected": {
            "status": 403,
            "retryable": false,
            "example": {
              "error": {
                "code": "request_rejected"
              }
            }
          },
          "request_not_found": {
            "status": 404,
            "retryable": false,
            "example": {
              "error": {
                "code": "request_not_found"
              }
            }
          },
          "request_expired": {
            "status": 410,
            "retryable": false,
            "example": {
              "error": {
                "code": "request_expired"
              }
            }
          },
          "delivery_expired": {
            "status": 410,
            "retryable": false,
            "example": {
              "error": {
                "code": "delivery_expired"
              }
            }
          },
          "credential_unavailable": {
            "status": 410,
            "retryable": false,
            "example": {
              "error": {
                "code": "credential_unavailable"
              }
            }
          },
          "delivery_acknowledged": {
            "status": 410,
            "retryable": false,
            "example": {
              "error": {
                "code": "delivery_acknowledged"
              }
            }
          }
        },
        "x-replay-window-seconds": 900,
        "x-cache": "no-store",
        "x-rate-limit": {
          "limit": 30,
          "period_seconds": 60,
          "key": "request and IP",
          "aggregate_limit": 120,
          "aggregate_period_seconds": 60,
          "aggregate_key": "IP",
          "retry_after_on_429": true,
          "config_backed": true
        },
        "x-request-body-limit-bytes": 8192
      }
    },
    "/v1/project-credential-requests/{id}/acknowledge": {
      "post": {
        "operationId": "api_post_v1_project_credential_requests_id_acknowledge",
        "summary": "Acknowledge project credential delivery",
        "description": "Requires the same retrieval proof and the issued project key in the request body, proving possession. A successful acknowledgement clears the encrypted replay secret. The request body contains a secret and must not be logged.",
        "security": [],
        "x-authentication": {
          "scheme": "Bearer retrieval proof"
        },
        "x-success-status": 200,
        "x-contract-status": "live",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Opaque request ID returned by the submission response."
          },
          {
            "name": "Authorization",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^Bearer .+$"
            },
            "description": "Bearer token is the client-generated retrieval_proof."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "token"
                ],
                "additionalProperties": false
              },
              "examples": {
                "shape_only": {
                  "summary": "Shape only; never use a real key in examples",
                  "value": {
                    "token": "<issued-project-key>"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credential delivery acknowledged and encrypted replay material cleared.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "const": "acknowledged"
                        }
                      },
                      "required": [
                        "status"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "404": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "410": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "422": {
            "$ref": "#/components/responses/P9StableApiError"
          },
          "429": {
            "$ref": "#/components/responses/P9StableRateLimited"
          }
        },
        "x-error-contract": {
          "request_not_found": {
            "status": 404,
            "retryable": false,
            "example": {
              "error": {
                "code": "request_not_found"
              }
            }
          },
          "delivery_acknowledged": {
            "status": 410,
            "retryable": false,
            "example": {
              "error": {
                "code": "delivery_acknowledged"
              }
            }
          },
          "delivery_expired": {
            "status": 410,
            "retryable": false,
            "example": {
              "error": {
                "code": "delivery_expired"
              }
            }
          },
          "credential_unavailable": {
            "status": 410,
            "retryable": false,
            "example": {
              "error": {
                "code": "credential_unavailable"
              }
            }
          }
        },
        "x-rate-limit": {
          "limit": 30,
          "period_seconds": 60,
          "key": "request and IP",
          "aggregate_limit": 120,
          "aggregate_period_seconds": 60,
          "aggregate_key": "IP",
          "retry_after_on_429": true,
          "config_backed": true
        },
        "x-cache": "no-store"
      }
    }
  },
  "x-privacy-export-contract": {
    "subject_link": "exact top-level payload.subject.id",
    "historical_coverage": "Retained events with an exact top-level subject.id match, including successfully indexed historical rows; excludes data.* or free-text links, pruned events, backups, internal profile records, and invitation history.",
    "max_records": 5000,
    "max_plaintext_bytes": 5242880,
    "all_or_nothing": true,
    "artifact_ttl_hours": 24,
    "tombstone_days": 30,
    "redaction_limits": "Known credentials, codes, and secrets are redacted and session material is removed; unknown sensitive values may remain.",
    "generation_enabled_by_default": false,
    "generation_enablement_gate": "dedicated keyrings and historical index backfill verified",
    "downloads_cache": {
      "Cache-Control": "private, no-store, max-age=0",
      "Pragma": "no-cache"
    },
    "api_error_codes_locale_independent": true
  },
  "components": {
    "securitySchemes": {
      "ProjectCredential": {
        "type": "http",
        "scheme": "bearer",
        "description": "Project environment credential, with events:write scope."
      }
    },
    "headers": {
      "IngestionRequestId": {
        "required": true,
        "description": "Matches the request_id value in the JSON response body.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._-]{1,100}$"
        }
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[!-~]+$"
        }
      }
    },
    "schemas": {
      "Event": {
        "type": "object",
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "description": "Unknown or reserved top-level fields are rejected. data/context/actor/subject must be JSON objects. Sensitive key names are redacted server-side.",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Optional producer-assigned event ID used as the event deduplication key. This is distinct from the server-assigned event_id returned after acceptance."
          },
          "type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "description": "RFC3339 timestamp with timezone."
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "success",
              "warning",
              "critical"
            ],
            "default": "info"
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "summary": {
                "type": "string",
                "maxLength": 500
              },
              "summary_translations": {
                "type": "object",
                "maxProperties": 8,
                "additionalProperties": {
                  "type": "string",
                  "maxLength": 500
                }
              }
            }
          },
          "context": {
            "type": "object",
            "additionalProperties": true
          },
          "actor": {
            "type": "object",
            "additionalProperties": true
          },
          "subject": {
            "type": "object",
            "additionalProperties": true
          },
          "tags": {
            "type": "array",
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 50
            }
          },
          "correlation_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "AcceptedEvent": {
        "type": "object",
        "required": [
          "accepted",
          "event_id",
          "duplicate",
          "received_at",
          "routing",
          "request_id"
        ],
        "properties": {
          "accepted": {
            "const": true
          },
          "event_id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$",
            "description": "Server-assigned ULID of the persisted event. It is distinct from the producer-assigned Event.id used for deduplication."
          },
          "duplicate": {
            "type": "boolean"
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "routing": {
            "type": "string"
          },
          "routing_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "routing_explain": {},
          "request_id": {
            "type": "string"
          },
          "schema_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "schema_version": {
            "type": [
              "integer",
              "null"
            ]
          },
          "schema_warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "BatchResult": {
        "type": "object",
        "required": [
          "accepted",
          "receipt_id",
          "status",
          "items",
          "request_id"
        ],
        "properties": {
          "accepted": {
            "const": true
          },
          "receipt_id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$",
            "description": "Server-assigned ULID for the durable batch receipt."
          },
          "status": {
            "const": "completed"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchItemResult"
            }
          },
          "request_id": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "CatalogResponse": {
        "type": "object",
        "required": [
          "data",
          "request_id"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "version",
              "template_version",
              "locale",
              "events",
              "templates",
              "usage"
            ],
            "properties": {
              "version": {
                "type": "integer",
                "const": 1
              },
              "template_version": {
                "type": "integer",
                "const": 2
              },
              "locale": {
                "type": "string"
              },
              "events": {
                "type": "array"
              },
              "templates": {
                "type": "array"
              },
              "usage": {
                "type": "object",
                "required": [
                  "endpoint",
                  "note"
                ],
                "properties": {
                  "endpoint": {
                    "type": "string"
                  },
                  "note": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": true
          },
          "request_id": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "EventIngestionErrorBody": {
        "type": "object",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "unauthenticated",
              "insufficient_scope",
              "rate_limit_exceeded",
              "payload_too_large",
              "signature_headers_incomplete",
              "signature_timestamp_invalid",
              "signature_timestamp_expired",
              "signature_nonce_invalid",
              "signature_invalid",
              "signature_replay",
              "malformed_json",
              "validation_failed",
              "idempotency_key_mismatch",
              "idempotency_conflict",
              "billing_quota_exceeded",
              "ingestion_temporarily_unavailable",
              "batch_limit_exceeded"
            ]
          },
          "message": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "details": {},
          "reason": {
            "type": "string"
          }
        },
        "additionalProperties": true,
        "description": "Stable top-level error shape for event ingestion. Authentication failures may contain only code; controller errors may also include message, request_id, and details. Retryability is operation metadata and is not a JSON property."
      },
      "EventIngestionApiError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/EventIngestionErrorBody"
          }
        },
        "additionalProperties": true
      },
      "EventBatchIncompleteError": {
        "type": "object",
        "required": [
          "error",
          "receipt_id",
          "status"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/EventIngestionErrorBody"
          },
          "receipt_id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$",
            "description": "Server-assigned ULID for the durable batch receipt."
          },
          "status": {
            "const": "incomplete"
          }
        },
        "additionalProperties": false
      },
      "BatchItemResult": {
        "type": "object",
        "required": [
          "index",
          "accepted",
          "status",
          "retryable"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "accepted": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "accepted",
              "quarantined",
              "rejected"
            ]
          },
          "retryable": {
            "type": "boolean",
            "description": "Currently false for every batch item result."
          },
          "event_id": {
            "type": "string",
            "pattern": "^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$",
            "description": "Server-assigned ULID of the persisted event. It is distinct from the producer-assigned Event.id used for deduplication."
          },
          "duplicate": {
            "type": "boolean"
          },
          "routing": {
            "type": "string"
          },
          "routing_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "routing_explain": {},
          "schema_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "schema_version": {
            "type": [
              "integer",
              "null"
            ]
          },
          "schema_warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "error": {
            "$ref": "#/components/schemas/EventIngestionErrorBody"
          }
        },
        "additionalProperties": true
      },
      "P9StableErrorCode": {
        "type": "string",
        "description": "Stable machine-readable error code emitted by documented P9 API operations.",
        "enum": [
          "unauthenticated",
          "forbidden",
          "not_found",
          "project_slug_exists",
          "secret_response_expired",
          "audit_integrity_failed",
          "validation_failed",
          "rate_limit_exceeded",
          "confirmation_required",
          "storage_unavailable",
          "workspace_scope_mismatch",
          "idempotency_conflict",
          "operation_in_progress",
          "incompatible_schema_version",
          "schema_exists",
          "event_replay.authorization_denied",
          "event_replay.run_not_found",
          "event_replay.project_scope_mismatch",
          "event_replay.snapshot_scope_invalid",
          "event_replay.snapshot_scope_mismatch",
          "event_replay.idempotency_conflict",
          "event_replay.run_terminal",
          "event_replay.run_not_paused",
          "event_replay.run_not_resumable",
          "event_replay.routing_policy_changed",
          "event_replay.confirmation_required",
          "event_replay.cursor_invalid",
          "event_replay.cursor_unavailable",
          "event_replay.page_limit_invalid",
          "event_replay.invalid_idempotency_key",
          "event_replay.snapshot_limit_exceeded",
          "event_replay.snapshot_membership_invalid",
          "event_replay.partial_ack_required",
          "event_replay.audit_invalid",
          "event_replay.lease_lost",
          "event_replay.projection_chunk_failed",
          "event_replay.routing_policy_too_large",
          "event_replay.run_scope_invalid",
          "event_replay.snapshot_changed",
          "workspace_required",
          "staff_step_up_required",
          "insufficient_scope",
          "provider_unavailable",
          "capability_unavailable",
          "audit_unavailable",
          "signature_headers_incomplete",
          "signature_timestamp_invalid",
          "signature_timestamp_expired",
          "signature_nonce_invalid",
          "signature_invalid",
          "signature_replay",
          "malformed_json",
          "idempotency_key_mismatch",
          "payload_too_large",
          "billing_quota_exceeded",
          "ingestion_temporarily_unavailable",
          "batch_limit_exceeded",
          "event_replay.workspace_scope_mismatch",
          "event_replay.idempotency_key_invalid",
          "event_replay.workspace_required",
          "idempotency_key_required",
          "resource_not_found",
          "schedule_conflict",
          "event_replay.operation_in_progress",
          "unknown_requires_allow_duplicate",
          "delivery_not_resendable",
          "project_paused",
          "preview_unavailable",
          "report_results_unavailable",
          "conflict",
          "quota_exceeded",
          "lower_bound_ack_required",
          "content_unavailable",
          "archive_unavailable",
          "export_cancel_conflict",
          "export_quota_or_request_rejected",
          "operation_outcome_unknown",
          "provider_rejected",
          "receipt_not_found",
          "receipt_not_reconcilable",
          "report_preview_budget_exceeded",
          "report_version_conflict"
        ]
      },
      "P9StableErrorBody": {
        "type": "object",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/P9StableErrorCode"
          },
          "message": {
            "type": "string"
          },
          "request_id": {
            "type": "string",
            "maxLength": 26
          },
          "details": {}
        },
        "additionalProperties": true
      },
      "P9StableApiError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/P9StableErrorBody"
          },
          "request_id": {
            "type": "string",
            "maxLength": 26
          }
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "EventIngestionError": {
        "description": "An event-ingestion error. The code is stable; the human message is localized and may vary. See the operation x-error-contract for status, retryability, and Retry-After behavior.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventIngestionApiError"
            },
            "examples": {
              "unauthenticated": {
                "summary": "Missing or invalid project credential",
                "value": {
                  "error": {
                    "code": "unauthenticated"
                  }
                }
              },
              "malformedJson": {
                "summary": "Malformed single-event JSON",
                "value": {
                  "error": {
                    "code": "malformed_json",
                    "message": "The event body is not valid JSON.",
                    "request_id": "01J00000000000000000000000",
                    "details": []
                  }
                }
              },
              "validationFailed": {
                "summary": "Event validation failed",
                "value": {
                  "error": {
                    "code": "validation_failed",
                    "message": "The event request is invalid.",
                    "request_id": "01J00000000000000000000000",
                    "details": {
                      "type": [
                        "The type field format is invalid."
                      ]
                    }
                  }
                }
              },
              "Err_401_signature_invalid_46b52610": {
                "$ref": "#/components/examples/Err_401_signature_invalid_46b52610"
              },
              "Err_403_insufficient_scope_33daa641": {
                "$ref": "#/components/examples/Err_403_insufficient_scope_33daa641"
              },
              "Err_409_signature_replay_75dc5f18": {
                "$ref": "#/components/examples/Err_409_signature_replay_75dc5f18"
              },
              "Err_413_payload_too_large_98e46177": {
                "$ref": "#/components/examples/Err_413_payload_too_large_98e46177"
              },
              "Err_422_signature_headers_incomplete_6c300872": {
                "$ref": "#/components/examples/Err_422_signature_headers_incomplete_6c300872"
              },
              "Err_503_ingestion_temporarily_unavailabl_2d8c15fe": {
                "$ref": "#/components/examples/Err_503_ingestion_temporarily_unavailabl_2d8c15fe"
              }
            }
          }
        }
      },
      "EventIngestionCorrelatedError": {
        "description": "An event-ingestion controller or payload-limit error. These paths always include X-Request-Id; authentication middleware errors use EventIngestionError and omit it.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/IngestionRequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventIngestionApiError"
            },
            "examples": {
              "Err_400_malformed_json_2ede1fa2": {
                "$ref": "#/components/examples/Err_400_malformed_json_2ede1fa2"
              },
              "Err_409_signature_replay_75dc5f18": {
                "$ref": "#/components/examples/Err_409_signature_replay_75dc5f18"
              },
              "Err_413_payload_too_large_98e46177": {
                "$ref": "#/components/examples/Err_413_payload_too_large_98e46177"
              },
              "Err_422_signature_headers_incomplete_6c300872": {
                "$ref": "#/components/examples/Err_422_signature_headers_incomplete_6c300872"
              },
              "Err_503_ingestion_temporarily_unavailabl_2d8c15fe": {
                "$ref": "#/components/examples/Err_503_ingestion_temporarily_unavailabl_2d8c15fe"
              },
              "Err_422_signature_timestamp_invalid_35eb40b7": {
                "$ref": "#/components/examples/Err_422_signature_timestamp_invalid_35eb40b7"
              },
              "Err_409_idempotency_conflict_017cd0e2": {
                "$ref": "#/components/examples/Err_409_idempotency_conflict_017cd0e2"
              }
            }
          }
        }
      },
      "EventIngestionRateLimited": {
        "description": "429 may mean rate_limit_exceeded (automatic retry is appropriate after the positive delta-seconds Retry-After) or billing_quota_exceeded (do not automatically retry; no Retry-After header is emitted).",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/IngestionRequestId"
          },
          "Retry-After": {
            "required": false,
            "description": "Present only for rate_limit_exceeded; positive delay in seconds, never an HTTP-date.",
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventIngestionApiError"
            },
            "examples": {
              "rateLimitExceeded": {
                "summary": "Retryable ingestion rate limit",
                "value": {
                  "error": {
                    "code": "rate_limit_exceeded",
                    "message": "The request limit has been reached.",
                    "request_id": "01J00000000000000000000000",
                    "details": []
                  }
                }
              },
              "billingQuotaExceeded": {
                "summary": "Quota limit without Retry-After",
                "value": {
                  "error": {
                    "code": "billing_quota_exceeded",
                    "message": "The event request is invalid.",
                    "request_id": "01J00000000000000000000000",
                    "details": {
                      "reason": [
                        "event_volume_limit"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "x-error-contract": {
          "rate_limit_exceeded": {
            "status": 429,
            "retryable": true,
            "retry_after": "delta-seconds"
          },
          "billing_quota_exceeded": {
            "status": 429,
            "retryable": false,
            "retry_after": "not-emitted"
          }
        }
      },
      "EventBatchRateLimited": {
        "description": "The batch request was rate limited. Retry after the positive delta-seconds Retry-After value; billing quota failures are represented as HTTP 202 item results instead.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/IngestionRequestId"
          },
          "Retry-After": {
            "required": true,
            "description": "Positive delay in seconds, never an HTTP-date.",
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventIngestionApiError"
            },
            "examples": {
              "rateLimitExceeded": {
                "summary": "Retryable batch rate limit",
                "value": {
                  "error": {
                    "code": "rate_limit_exceeded",
                    "message": "The request limit has been reached.",
                    "request_id": "01J00000000000000000000000",
                    "details": []
                  }
                }
              }
            }
          }
        },
        "x-error-contract": {
          "rate_limit_exceeded": {
            "status": 429,
            "retryable": true,
            "retry_after": "delta-seconds"
          }
        }
      },
      "EventBatchIncomplete": {
        "description": "The batch could not finish because ingestion capacity was temporarily unavailable. No Retry-After header is emitted.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/IngestionRequestId"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventBatchIncompleteError"
            },
            "examples": {
              "ingestionTemporarilyUnavailable": {
                "summary": "Incomplete batch due to temporary capacity failure",
                "value": {
                  "error": {
                    "code": "ingestion_temporarily_unavailable",
                    "message": "The request could not be processed at this time.",
                    "request_id": "01J00000000000000000000000",
                    "details": {
                      "reason": [
                        "disk_usage_limit"
                      ]
                    }
                  },
                  "receipt_id": "01J00000000000000000000000",
                  "status": "incomplete"
                }
              }
            }
          }
        }
      },
      "P9StableRateLimited": {
        "description": "Retryable request-rate limit. Retry-After is a positive delta-seconds value.",
        "headers": {
          "Retry-After": {
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/P9StableApiError"
            },
            "examples": {
              "Err_429_rate_limit_exceeded_d94198d5": {
                "$ref": "#/components/examples/Err_429_rate_limit_exceeded_d94198d5"
              }
            }
          }
        }
      }
    },
    "examples": {
      "Err_429_rate_limit_exceeded_d94198d5": {
        "summary": "Stable rate_limit_exceeded error for HTTP 429",
        "value": {
          "error": {
            "code": "rate_limit_exceeded",
            "message": "The request limit has been reached.",
            "request_id": "01J00000000000000000000000",
            "details": []
          }
        }
      },
      "Err_400_malformed_json_2ede1fa2": {
        "summary": "Stable malformed_json error for HTTP 400",
        "value": {
          "error": {
            "code": "malformed_json",
            "message": "The event body is not valid JSON.",
            "request_id": "01J00000000000000000000000",
            "details": []
          }
        }
      },
      "Err_409_signature_replay_75dc5f18": {
        "summary": "Stable signature_replay error for HTTP 409",
        "value": {
          "error": {
            "code": "signature_replay"
          }
        }
      },
      "Err_413_payload_too_large_98e46177": {
        "summary": "Stable payload_too_large error for HTTP 413",
        "value": {
          "error": {
            "code": "payload_too_large",
            "message": "The event payload is too large.",
            "request_id": "01J00000000000000000000000",
            "details": []
          }
        }
      },
      "Err_422_signature_headers_incomplete_6c300872": {
        "summary": "Stable signature_headers_incomplete error for HTTP 422",
        "value": {
          "error": {
            "code": "signature_headers_incomplete"
          }
        }
      },
      "Err_503_ingestion_temporarily_unavailabl_2d8c15fe": {
        "summary": "Stable ingestion_temporarily_unavailable error for HTTP 503",
        "value": {
          "error": {
            "code": "ingestion_temporarily_unavailable",
            "message": "The request could not be processed at this time.",
            "request_id": "01J00000000000000000000000",
            "details": []
          }
        }
      },
      "Err_422_signature_timestamp_invalid_35eb40b7": {
        "summary": "Stable signature_timestamp_invalid error for HTTP 422",
        "value": {
          "error": {
            "code": "signature_timestamp_invalid"
          }
        }
      },
      "Err_409_idempotency_conflict_017cd0e2": {
        "summary": "Stable idempotency_conflict error for HTTP 409",
        "value": {
          "error": {
            "code": "idempotency_conflict",
            "message": "The batch request is invalid.",
            "request_id": "01J00000000000000000000000",
            "details": []
          }
        }
      },
      "Err_401_signature_invalid_46b52610": {
        "summary": "Stable signature_invalid error for HTTP 401",
        "value": {
          "error": {
            "code": "signature_invalid"
          }
        }
      },
      "Err_403_insufficient_scope_33daa641": {
        "summary": "Stable insufficient_scope error for HTTP 403",
        "value": {
          "error": {
            "code": "insufficient_scope"
          }
        }
      }
    }
  },
  "x-default-rate-limit-policies": {
    "management_token": {
      "applies_to": "Management route-group operations after token authentication and workspace authorization.",
      "key": "management token ID",
      "requests": 60,
      "window_seconds_default": 60,
      "window_seconds_configuration": "personal.limits.rate.decay_seconds",
      "exhausted_response": {
        "status": 429,
        "code": "rate_limit_exceeded",
        "retry_after": "positive delta-seconds"
      },
      "limiter_storage_failure": {
        "status": 503,
        "code": "storage_unavailable",
        "retry_after": "not-emitted"
      }
    },
    "credential_issuance": {
      "operation": "POST /v1/manage/projects/{project}/credentials",
      "additional_to": "management_token",
      "key": "management token owner user ID",
      "requests": 5,
      "window_seconds_default": 60,
      "window_seconds_configuration": "personal.limits.rate.decay_seconds",
      "exhausted_response": {
        "status": 429,
        "code": "rate_limit_exceeded",
        "retry_after": "positive delta-seconds"
      },
      "limiter_storage_failure": {
        "status": 503,
        "code": "storage_unavailable",
        "retry_after": "not-emitted"
      }
    }
  },
  "x-sdk-support-policy": "Packages begin at 0.1.0 preview. A stable 1.x SDK support claim requires green shared fixture tests, compilation/package validation, one successful acceptance flow, an explicit supported API version, and a tagged repository release. Breaking SDK changes before 1.0 increment minor versions; after 1.0 follow semver. API additive changes are compatible; removals/renames require a versioned API path and published sunset window.",
  "x-p9-route-coverage": {
    "included": "Registered P9 ingestion/catalog/event/schema/receipt routes; management and staff ordinary saved-report definition, run, export, and schedule routes; staff portfolio saved-report operations; and management portfolio run/export operations.",
    "excluded": "Management portfolio saved-report definition routes and unrelated platform, service-principal, explorer, replay, billing, delivery, and on-call routes are intentionally outside this artifact."
  }
}
