nxtgauge-backend-rust/docs/openapi.wallet-holds.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Nxtgauge — Wallet Holds (minimal, hand-maintained)",
    "version": "1.0.0",
    "description": "Covers only the routes deployed by the wallet-holds/printpdf release (see docs/LIVE_SERVER_RUNBOOK.md). This is deliberately narrow — the full backend has 341 routes across 19 services and none have utoipa annotations yet (tracked as a separate follow-up). Generated by hand from crates/contracts/src/profession_shared.rs (wallet_holds, wallet_release_hold) to give schemathesis something real to fuzz against today's change without taking on full OpenAPI generation."
  },
  "servers": [
    { "url": "https://api.nxtgauge.com" }
  ],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/api/photographers/wallet/me/holds": {
      "get": {
        "operationId": "listWalletHolds",
        "summary": "List the authenticated professional's tracecoin holds",
        "parameters": [
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of holds",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "pagination"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Hold" } },
                    "pagination": { "$ref": "#/components/schemas/Pagination" }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing/invalid JWT" },
          "500": { "description": "Server error" }
        }
      }
    },
    "/api/photographers/wallet/me/holds/{id}/release": {
      "post": {
        "operationId": "releaseWalletHold",
        "summary": "Release an ACTIVE hold owned by the authenticated professional",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "200": {
            "description": "Hold released, tracecoins returned to available balance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "message": { "type": "string" } }
                }
              }
            }
          },
          "401": { "description": "Missing/invalid JWT" },
          "404": { "description": "Hold not found or not owned by caller" },
          "409": { "description": "Hold exists but is not ACTIVE (already SETTLED/RELEASED/EXPIRED)" },
          "500": { "description": "Server error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
    },
    "schemas": {
      "Hold": {
        "type": "object",
        "required": ["id", "wallet_id", "user_id", "amount", "reason", "status", "created_at"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "wallet_id": { "type": "string", "format": "uuid" },
          "user_id": { "type": "string", "format": "uuid" },
          "amount": { "type": "integer" },
          "reason": { "type": "string" },
          "reference_id": { "type": "string", "format": "uuid", "nullable": true },
          "status": { "type": "string", "enum": ["ACTIVE", "SETTLED", "RELEASED", "EXPIRED"] },
          "expires_at": { "type": "string", "format": "date-time", "nullable": true },
          "settled_at": { "type": "string", "format": "date-time", "nullable": true },
          "settled_ledger_id": { "type": "string", "format": "uuid", "nullable": true },
          "released_at": { "type": "string", "format": "date-time", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Pagination": {
        "type": "object",
        "required": ["page", "limit"],
        "properties": {
          "page": { "type": "integer" },
          "limit": { "type": "integer" }
        }
      }
    }
  }
}