{
  "openapi": "3.0.0",
  "info": {
    "title": "Credits API",
    "version": "1.0.0",
    "description": "Credits management API",
    "termsOfService": "https://readcoop.eu/terms-and-conditions/",
    "contact": {
      "name": "API Support",
      "email": "info@readcoop.eu",
      "url": "https://readcoop.eu"
    },
    "license": {
      "name": "ISC",
      "url": "https://opensource.org/licenses/ISC"
    }
  },
  "servers": [
    {
      "url": "https://api-credit.transkribus.org",
      "description": "Production server"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT Bearer token authentication"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                },
                "statusCode": {
                  "type": "number",
                  "example": 400
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "example": "Unauthorized"
                },
                "message": {
                  "type": "string"
                },
                "statusCode": {
                  "type": "number",
                  "example": 401
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "example": "Not Found"
                },
                "message": {
                  "type": "string"
                },
                "statusCode": {
                  "type": "number",
                  "example": 404
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "example": "Internal Server Error"
                },
                "message": {
                  "type": "string"
                },
                "statusCode": {
                  "type": "number",
                  "example": 500
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/user/balance": {
      "get": {
        "summary": "Get the authenticated user's credit balance",
        "description": "User identity comes from the bearer token (trp_user_id).\nBALANCE_SOURCE=legacy (dual-read phase) returns the legacy shape;\non legacy outage it falls back to the local computation with\nheader X-Balance-Source: new_degraded. Locally computed balances\nadditionally carry superModelEligibleBalance — the sum of\npersonal package balances that may pay for super-model (TrHtr)\njobs (welcome-standard credits are excluded). Frontends treat an\nabsent field as \"eligibility gate unavailable\".\nWhen ENABLE_WELCOME_GRANT=true this read lazily creates the\none-time welcome grant (20 super-eligible + 30 restricted).\n",
        "tags": [
          "Credits"
        ],
        "responses": {
          "200": {
            "description": "{ userId, addOn, scholar, organisation, superModelEligibleBalance? }"
          }
        },
        "operationId": "get-user-balance"
      }
    },
    "/user/packages": {
      "get": {
        "summary": "Get user's package overview (all packages with their transactions)",
        "tags": [
          "Credits"
        ],
        "operationId": "get-user-packages"
      }
    },
    "/user/transactionHistory": {
      "get": {
        "summary": "Get user's transaction history (flat list of job-related transactions)",
        "tags": [
          "Credits"
        ],
        "operationId": "get-user-transactionhistory"
      }
    },
    "/user/purchases": {
      "get": {
        "summary": "Get user's purchase history (initial transactions only)",
        "tags": [
          "Credits"
        ],
        "operationId": "get-user-purchases"
      }
    },
    "/organization/{organizationId}/balance": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "organizationId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "summary": "Get organization's credit balance",
        "tags": [
          "Credits"
        ],
        "operationId": "get-organization-organizationid-balance"
      }
    },
    "/collection/{collectionId}/balance": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "collectionId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "summary": "Get collection's credit balance",
        "tags": [
          "Credits"
        ],
        "operationId": "get-collection-collectionid-balance"
      }
    },
    "/collection/{collectionId}/transactions": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "collectionId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "summary": "Get collection's transaction history grouped by package",
        "tags": [
          "Credits"
        ],
        "operationId": "get-collection-collectionid-transactions"
      }
    },
    "/spending-limit": {
      "post": {
        "summary": "Set a spending limit for a user on an organization",
        "tags": [
          "Credits"
        ],
        "operationId": "post-spending-limit"
      }
    },
    "/organization/{organizationId}/limits": {
      "get": {
        "summary": "Get all spending limits for an organization (admin/manager only)",
        "description": "Returns all members with their spending limits and consumption. User is authenticated via JWT token.",
        "tags": [
          "Credits"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "organizationId",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "operationId": "get-organization-organizationid-limits"
      }
    },
    "/costs": {
      "get": {
        "summary": "Calculate cost breakdown for a job",
        "description": "Returns how credits would be consumed from different pools (team, scholar, topup). Proxy phase: when colId AND modelId are provided (and WRITE_MODE=proxy), the preview is proxied to the legacy TRP costs endpoints (collection-package aware) and translated into the same schema; the `source` response field says which path answered (legacy | local | local-fallback).\n",
        "tags": [
          "Credits"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "nrOfPages",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "modelType",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "provider",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "docType",
            "required": true,
            "schema": {
              "type": "integer",
              "enum": [
                0,
                1
              ]
            }
          },
          {
            "in": "query",
            "name": "colId",
            "description": "Legacy collection id — with modelId, enables the legacy proxy",
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "modelId",
            "description": "Legacy model id — with colId, enables the legacy proxy",
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "credits",
            "description": "Legacy credit selection strategy (omitted → AUTO)",
            "schema": {
              "type": "string",
              "enum": [
                "USER_ONLY",
                "COLLECTION_ONLY"
              ]
            }
          }
        ],
        "operationId": "get-costs"
      }
    },
    "/add-ons/assign-to-org": {
      "post": {
        "summary": "Share personal topup credits to the organization pool",
        "description": "Shares personal topup credits to the organization pool.\n- Uses largest-first strategy to select packages\n- Automatically splits packages as needed\n- Any organization member can share their own topups\n",
        "tags": [
          "Credits"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount"
                ],
                "properties": {
                  "amount": {
                    "type": "number",
                    "description": "Amount of topup credits to share"
                  }
                }
              }
            }
          }
        },
        "operationId": "post-add-ons-assign-to-org"
      }
    },
    "/add-ons/reclaim-from-org": {
      "post": {
        "summary": "Reclaim add-on credits from organization",
        "description": "Reclaims add-on credits that the user has assigned to the organization.\n- Only allowed if no transactions have occurred on the package (prevents reclaim after usage)\n- Returns all assigned packages to personal topup pool\n- Intended for reverting accidental assignments\n",
        "tags": [
          "Credits"
        ],
        "operationId": "post-add-ons-reclaim-from-org"
      }
    }
  },
  "tags": []
}
