{
  "openapi": "3.1.0",
  "info": {
    "title": "Piipe Secure PII API",
    "version": "2.0.0",
    "description": "The Piipe SDK sends one fixed authenticated request envelope and verifies the complete authenticated response before releasing any result. Application operations such as store, search, retrieve, update and delete are encoded inside the envelope and remain scoped to the provisioned organisation, application and purpose."
  },
  "servers": [
    {
      "url": "https://api.piipe.io",
      "description": "Piipe production API"
    }
  ],
  "tags": [
    {
      "name": "Secure exchange",
      "description": "Fixed authenticated-envelope transport used by the Piipe SDK."
    },
    {
      "name": "Service health",
      "description": "Fail-closed service readiness without customer data."
    }
  ],
  "paths": {
    "/api/v1/envelope": {
      "post": {
        "operationId": "exchangePiipeEnvelope",
        "tags": [
          "Secure exchange"
        ],
        "summary": "Exchange one authenticated Piipe request",
        "description": "Accepts exactly one 112-byte application/vnd.piipe.envelope-v1 request and returns exactly one 352-byte response in the same media type. The SDK authenticates the response and its request binding before exposing the operation result. Callers should use the Piipe SDK rather than constructing frames directly.",
        "parameters": [
          {
            "name": "Cache-Control",
            "in": "header",
            "required": true,
            "description": "Requests must prohibit storage by intermediaries.",
            "schema": {
              "type": "string",
              "const": "no-store"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/vnd.piipe.envelope-v1": {
              "schema": {
                "$ref": "#/components/schemas/AuthenticatedRequestEnvelope"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The fixed authenticated response envelope. A transport-level 200 does not replace SDK authentication or operation-status checks.",
            "headers": {
              "Cache-Control": {
                "required": true,
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/vnd.piipe.envelope-v1": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticatedResponseEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadEnvelope"
          },
          "408": {
            "$ref": "#/components/responses/RequestTimeout"
          },
          "413": {
            "$ref": "#/components/responses/WrongLength"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/ServiceTimeout"
          }
        },
        "security": [],
        "x-piipe-request-bytes": 112,
        "x-piipe-response-bytes": 352,
        "x-piipe-application-envelope-authentication": "required",
        "x-piipe-replay-sequence-required": true,
        "x-piipe-sdk-recommended": true
      }
    },
    "/healthz": {
      "get": {
        "operationId": "getPiipeServiceHealth",
        "tags": [
          "Service health"
        ],
        "summary": "Check fail-closed service readiness",
        "description": "Returns ready only when the secure service path is available. It contains no customer identifiers, credentials or protected values.",
        "responses": {
          "200": {
            "description": "The secure service path is ready.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "503": {
            "description": "The secure service path is not ready.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthUnavailableResponse"
                }
              }
            }
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "schemas": {
      "AuthenticatedRequestEnvelope": {
        "type": "string",
        "format": "binary",
        "minLength": 112,
        "maxLength": 112,
        "description": "Exactly one SDK-created authenticated request envelope."
      },
      "AuthenticatedResponseEnvelope": {
        "type": "string",
        "format": "binary",
        "minLength": 352,
        "maxLength": 352,
        "description": "Exactly two independently authenticated response frames, returned as one 352-byte body."
      },
      "HealthResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok",
          "ready"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "ready": {
            "type": "boolean",
            "const": true
          }
        }
      },
      "HealthUnavailableResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok",
          "ready"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "ready": {
            "type": "boolean",
            "const": false
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          }
        }
      }
    },
    "responses": {
      "BadEnvelope": {
        "description": "The request envelope was malformed or rejected without disclosing which security check failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RequestTimeout": {
        "description": "The request body did not arrive within the bounded input window.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "WrongLength": {
        "description": "The request body exceeded the one-envelope limit.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "The request media type was not application/vnd.piipe.envelope-v1.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "The bounded application or service rate was exceeded before the operation was admitted.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The secure service path is not ready, so the operation was not released.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServiceTimeout": {
        "description": "The bounded secure-service transaction did not complete. Reconcile mutation state before retrying.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}