{
  "openapi": "3.1.0",
  "info": {
    "title": "WORO Data Exchange API",
    "version": "1.0.0",
    "description": "Use WORO as middleware for one-time data exchange: write bytes through the API, share the redeem token, and let the recipient retrieve the original bytes once. WORO uses a conditional claim so concurrent reads cannot both retrieve the same stored object."
  },
  "servers": [
    {
      "url": "https://woro.veilgroup.au",
      "description": "WORO production API"
    }
  ],
  "paths": {
    "/secret": {
      "post": {
        "operationId": "writeSecret",
        "summary": "Write a value for one-time exchange",
        "description": "Stores raw request-body bytes without text decoding. WORO deletes the stored value on read; unredeemed values expire after 14 days. A successful write consumes one account credit. The x-api-key value is a customer write token.",
        "security": [
          {
            "WriteToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Raw data payload, up to 1 MiB. WORO stores and returns the original bytes. Its Content-Type is retained as metadata; if omitted, it defaults to application/octet-stream.",
          "content": {
            "text/plain": {
              "schema": {
                "type": "string"
              },
              "example": "hello from WORO"
            },
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              },
              "example": {
                "message": "hello from WORO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Value stored. Share the returned redeem token with the intended recipient.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "token",
                    "expiresAt"
                  ],
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Redeem token. Anyone possessing it can attempt retrieval."
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                },
                "example": {
                  "token": "<redeem-token>",
                  "expiresAt": "2026-10-14T12:00:00.000Z"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "403": {
            "$ref": "#/components/responses/InvalidWriteToken"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/secret/{redeemToken}": {
      "get": {
        "operationId": "readSecret",
        "summary": "Read an exchange once",
        "description": "Claims the exchange, returns the original payload, and deletes the stored object on read. No account authentication is required. Only one request can claim an exchange. A redeemed status does not prove the recipient received the HTTP response.",
        "security": [],
        "parameters": [
          {
            "name": "redeemToken",
            "in": "path",
            "required": true,
            "description": "Redeem token returned in the `token` field by POST /secret.",
            "schema": {
              "type": "string"
            },
            "example": "replace-with-redeem-token"
          }
        ],
        "responses": {
          "200": {
            "description": "Original payload bytes. This request deletes the stored value on read. WORO returns the saved Content-Type metadata (or application/octet-stream if none was provided) and sets Content-Disposition: attachment to avoid inline rendering. If the client accepts gzip and compression saves at least 32 bytes, the response is returned with Content-Encoding: gzip.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "WriteToken": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Enter the write token from your WORO account. It authorizes secret writes and consumes credits."
      }
    },
    "responses": {
      "InsufficientCredits": {
        "description": "Account has no available write credits.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InvalidWriteToken": {
        "description": "Write token is invalid or revoked.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "Request body exceeds the 1 MiB payload limit.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Redeem token is unknown, expired, currently claimed, revoked, or already redeemed.",
        "content": {
          "text/plain": {
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "ServerError": {
        "description": "Unexpected service error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}