{
  "openapi": "3.1.0",
  "info": {
    "title": "Sandocs Enterprise API",
    "version": "1.0.0",
    "description": "Always-AI document sanitization. Requires active verified Enterprise Web entitlement. No persistent document storage. Secret keys are server-only; browser uploads require scoped upload tokens."
  },
  "servers": [
    {
      "url": "https://sandocs.eu"
    }
  ],
  "components": {
    "securitySchemes": {
      "PublicKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Sandocs-Public-Key"
      },
      "BearerCredential": {
        "type": "http",
        "scheme": "bearer",
        "description": "Server sd_sk_ secret or browser sd_ut_ upload token."
      }
    },
    "schemas": {
      "Result": {
        "type": "object",
        "required": [
          "request_id",
          "client_reference",
          "integration_public_key",
          "document",
          "metadata",
          "usage"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "client_reference": {
            "type": "string"
          },
          "integration_public_key": {
            "type": "string"
          },
          "document": {
            "type": "object",
            "properties": {
              "mime_type": {
                "const": "image/png"
              },
              "encoding": {
                "const": "base64"
              },
              "data": {
                "type": "string",
                "contentEncoding": "base64"
              }
            }
          },
          "metadata": {
            "type": "object",
            "properties": {
              "ai": {
                "const": true
              },
              "recognized_fields": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    },
                    "confidence": {
                      "type": "number"
                    }
                  }
                }
              },
              "regions": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "country": {
                "type": "string"
              },
              "document_type": {
                "type": "string"
              },
              "risk_score": {
                "type": "integer"
              },
              "warning": {
                "type": "string"
              }
            }
          },
          "usage": {
            "type": "object"
          },
          "retention": {
            "type": "object"
          }
        }
      }
    }
  },
  "paths": {
    "/enterprise/api": {
      "post": {
        "operationId": "sanitizeDocument",
        "security": [
          {
            "PublicKey": [],
            "BearerCredential": []
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9_.:-]+$"
            },
            "description": "Random opaque key, stable across retries; do not use applicant personal data."
          }
        ],
        "description": "Raw JPEG/PNG/WebP <=25 MiB and 50MP. Options come exclusively from the account integration. Counts one shared monthly document per new idempotency operation. Max 2 concurrent/account; 60 new requests/min/integration. Retries: same payload+settings, 24h deduplication; up to 60s RAM-only replay (may end early on eviction/restart).",
        "requestBody": {
          "required": true,
          "content": {
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed PNG (no original) and recognized metadata. Metadata can contain personal data. The SHA-256 of these exact JSON response bytes is available from the authenticated receipt endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                }
              }
            },
            "headers": {
              "Idempotency-Replayed": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Sandocs-Request-ID": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "504": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/enterprise/api/upload-tokens": {
      "post": {
        "operationId": "createUploadToken",
        "security": [
          {
            "PublicKey": [],
            "BearerCredential": []
          }
        ],
        "description": "Server-only secret; no Origin header. Token bound to integration generation, allowed exact origin and one Idempotency-Key for 300 seconds. Your token adapter must authenticate/authorize applicants, verify CSRF, bind the client reference and apply abuse limits.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "origin",
                  "idempotency_key"
                ],
                "additionalProperties": false,
                "properties": {
                  "origin": {
                    "type": "string"
                  },
                  "idempotency_key": {
                    "type": "string",
                    "minLength": 16,
                    "maxLength": 128
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "upload_token, public_key, endpoint, expires_in, idempotency_key"
          },
          "401": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/enterprise/api/receipts/{request_id}": {
      "get": {
        "operationId": "verifyResultReceipt",
        "security": [
          {
            "PublicKey": [],
            "BearerCredential": []
          }
        ],
        "description": "Server-only secret. Verify SHA-256 of the EXACT raw JSON result bytes; bind its client_reference to the authenticated applicant before accepting output. Available for the 24-hour operation lifetime.",
        "parameters": [
          {
            "in": "path",
            "name": "request_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "request_id, state, result_sha256, created; never returns document content."
          },
          "401": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; no original or recognized data included in errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
