{
  "openapi": "3.1.0",
  "info": {
    "title": "Veltor API",
    "version": "1.0.0",
    "description": "Abuse prevention API for SaaS. Requests reject unsupported fields. Decisions are limited to 16 KiB. Imports accept at most 1,000 rows."
  },
  "servers": [
    {
      "url": "https://veltor.tech"
    }
  ],
  "paths": {
    "/v1/decisions": {
      "post": {
        "summary": "Evaluate a stable benefit claim",
        "security": [
          {
            "serverKey": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[\\x21-\\x7e]+$"
            },
            "description": "Reuse for transport retries of exactly the same payload."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DecisionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decision recorded or replayed",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string"
                }
              },
              "Veltor-Grant-State": {
                "schema": {
                  "type": "string"
                }
              },
              "Veltor-Reservation-Expires-At": {
                "schema": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "id",
                    "decision"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "decision": {
                      "enum": [
                        "allow",
                        "deny"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/decisions/{id}": {
      "get": {
        "summary": "Read a masked decision explanation and current grant state",
        "security": [
          {
            "serverKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authorized resource in this key’s environment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/decisions/{id}/outcome": {
      "post": {
        "summary": "Record a known outcome",
        "security": [
          {
            "serverKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[\\x21-\\x7e]+$"
            },
            "description": "Reuse for transport retries of exactly the same payload."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutcomeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authorized resource in this key’s environment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/imports": {
      "post": {
        "summary": "Queue historical or reconciliation grants",
        "security": [
          {
            "serverKey": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[\\x21-\\x7e]+$"
            },
            "description": "Reuse for transport retries of exactly the same payload."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImportRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Authorized resource in this key’s environment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/imports/{id}": {
      "get": {
        "summary": "Read import progress and up to 100 row errors",
        "security": [
          {
            "serverKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authorized resource in this key’s environment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/observations": {
      "post": {
        "summary": "Issue a browser observation token scoped to an allowed Origin",
        "security": [
          {
            "publishableKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ObservationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authorized resource in this key’s environment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Structured technical error; never a policy denial",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "request_id"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "field": {
                          "type": "string"
                        },
                        "retryable": {
                          "type": "boolean"
                        }
                      }
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "serverKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Server key with the required endpoint permission"
      },
      "publishableKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Publishable browser key with observations:create permission"
      }
    },
    "schemas": {
      "DecisionRequest": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "benefit": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{0,63}$"
          },
          "claim_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[\\x21-\\x7e]+$"
          },
          "subject": {
            "type": "object",
            "properties": {
              "external_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "email": {
                "type": "string",
                "maxLength": 254,
                "format": "email",
                "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
              },
              "email_verified": {
                "type": "boolean"
              }
            },
            "required": [
              "email"
            ],
            "additionalProperties": false
          },
          "context": {
            "type": "object",
            "properties": {
              "ip": {
                "type": "string",
                "maxLength": 45
              },
              "user_agent": {
                "type": "string",
                "maxLength": 512
              },
              "session_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            },
            "required": [
              "ip"
            ],
            "additionalProperties": false
          },
          "identifiers": {
            "type": "object",
            "properties": {
              "device_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "device_token": {
                "type": "string",
                "maxLength": 4096
              },
              "browser_cookie_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "payment": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "scope": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "fingerprint": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  }
                },
                "required": [
                  "provider",
                  "scope",
                  "fingerprint"
                ],
                "additionalProperties": false
              },
              "phone_hash": {
                "type": "object",
                "properties": {
                  "algorithm": {
                    "type": "string",
                    "const": "hmac-sha256"
                  },
                  "key_version": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[\\x21-\\x7e]+$"
                  },
                  "value": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  }
                },
                "required": [
                  "algorithm",
                  "key_version",
                  "value"
                ],
                "additionalProperties": false
              },
              "phone_verified": {
                "type": "boolean"
              },
              "workspace_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "organization_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "installation_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              },
              "custom": {
                "maxItems": 10,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string",
                      "pattern": "^[a-z][a-z0-9_]{0,63}$"
                    },
                    "value_hash": {
                      "type": "object",
                      "properties": {
                        "algorithm": {
                          "type": "string",
                          "const": "hmac-sha256"
                        },
                        "key_version": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 128,
                          "pattern": "^[\\x21-\\x7e]+$"
                        },
                        "value": {
                          "type": "string",
                          "pattern": "^[a-f0-9]{64}$"
                        }
                      },
                      "required": [
                        "algorithm",
                        "key_version",
                        "value"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "key",
                    "value_hash"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "additionalProperties": false
          },
          "referral": {
            "type": "object",
            "properties": {
              "event_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[\\x21-\\x7e]+$"
              },
              "referred_subject": {
                "type": "object",
                "properties": {
                  "external_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "email": {
                    "type": "string",
                    "maxLength": 254,
                    "format": "email",
                    "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
                  },
                  "email_verified": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "external_id",
                  "email"
                ],
                "additionalProperties": false
              },
              "qualified": {
                "type": "boolean",
                "const": true
              }
            },
            "required": [
              "event_id",
              "referred_subject",
              "qualified"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "benefit",
          "claim_id",
          "subject",
          "context"
        ],
        "additionalProperties": false
      },
      "OutcomeRequest": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "outcome": {
            "type": "string",
            "enum": [
              "granted",
              "not_granted",
              "reversed"
            ]
          },
          "reason": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500
          },
          "external_grant_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[\\x21-\\x7e]+$"
          }
        },
        "required": [
          "outcome"
        ],
        "additionalProperties": false
      },
      "ImportRequest": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "grants": {
            "minItems": 1,
            "maxItems": 1000,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "external_grant_id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[\\x21-\\x7e]+$"
                },
                "benefit": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9_]{0,63}$"
                },
                "subject": {
                  "type": "object",
                  "properties": {
                    "external_id": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 128
                    },
                    "email": {
                      "type": "string",
                      "maxLength": 254,
                      "format": "email",
                      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
                    },
                    "email_verified": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "email"
                  ],
                  "additionalProperties": false
                },
                "granted_at": {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                },
                "claim_id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "pattern": "^[\\x21-\\x7e]+$"
                },
                "referral": {
                  "type": "object",
                  "properties": {
                    "event_id": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 128,
                      "pattern": "^[\\x21-\\x7e]+$"
                    },
                    "referred_subject": {
                      "type": "object",
                      "properties": {
                        "external_id": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 128
                        },
                        "email": {
                          "type": "string",
                          "maxLength": 254,
                          "format": "email",
                          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
                        },
                        "email_verified": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "external_id",
                        "email"
                      ],
                      "additionalProperties": false
                    },
                    "qualified": {
                      "type": "boolean",
                      "const": true
                    }
                  },
                  "required": [
                    "event_id",
                    "referred_subject",
                    "qualified"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "benefit",
                "subject",
                "granted_at"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "grants"
        ],
        "additionalProperties": false
      },
      "ObservationRequest": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "claim_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[\\x21-\\x7e]+$"
          },
          "fingerprint": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "browser": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "algorithm": {
            "type": "string",
            "maxLength": 32,
            "pattern": "^5\\."
          },
          "nonce": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          }
        },
        "required": [
          "claim_id",
          "fingerprint",
          "browser",
          "algorithm",
          "nonce"
        ],
        "additionalProperties": false
      }
    }
  }
}
