pricklymails-com Wallet API

openapi: 3.2.0
info:
  title: Pricklymails Com Wallet API
  version: 0.9.0
  contact:
    email: support@pricklymails.com
  license:
    name: Proprietary
  description: 'Operations tagged wallet across 2 of this provider''s published API definitions: pricklymails-com-openapi.json, pricklymails-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Wallet
  description: Your token balance and its ledger.
paths:
  /api/wallet:
    get:
      tags:
      - Wallet
      summary: Returns the caller's current credit balance
      description: Returns a zero balance with HTTP 200 when the account has never made a wallet transaction.
      operationId: get_wallet_balance
      responses:
        '200':
          description: Current credit balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletBalanceResponse'
        '401':
          description: Missing or invalid API key, session token, or agent token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: The key or agent token lacks the `billing:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
  /api/wallet/balance-history:
    get:
      tags:
      - Wallet
      summary: Returns a zero-filled, oldest-first series of the caller's available token…
      description: Accepts optional `granularity` (`"hour"` | `"day"` | `"week"` | `"month"`, default `"day"`; an unrecognized value falls back to `"day"`) and `days` (the number of whole `granularity` buckets the window covers, default 28, clamped to 1 to 364) query params, with the same defaults as `GET /api/stats/overview`.
      operationId: get_balance_history
      parameters:
      - name: granularity
        in: query
        description: 'Bucket width: `hour`, `day`, `week`, or `month` (default `day`).'
        required: false
        schema:
          type: string
      - name: days
        in: query
        description: 'Number of whole buckets the window covers at the chosen granularity, ending with the current, still-open bucket (default 28, clamped to 1..=364): 8 at `day` gives 8 buckets, 1 at `hour` gives 24, 364 at `month` gives 12.'
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      responses:
        '200':
          description: Zero-filled, oldest-first available-balance series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceHistoryRangeResponse'
        '401':
          description: Missing or invalid API key, session token, or agent token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: The key or agent token lacks the `billing:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
  /api/wallet/transactions:
    get:
      tags:
      - Wallet
      summary: Returns a paginated list of the caller's wallet transactions, newest first by…
      description: Accepts optional `limit` (default 20, cap 96) and `offset` (default 0) query params, plus an optional sort (`sort` = `occurred_at` | `amount` | `transaction_type`, `order` = `desc` | `asc`); an unknown `sort` or `order` value is a `400`. Each item carries `job_uuid`, the public UUID of the linked verification job, `null` for a credit or top-up transaction.
      operationId: list_wallet_transactions
      parameters:
      - name: limit
        in: query
        description: Number of transactions to return (default 20, cap 96).
        required: false
        schema:
          type: integer
          format: int64
      - name: offset
        in: query
        description: Number of transactions to skip (default 0).
        required: false
        schema:
          type: integer
          format: int64
      - name: sort
        in: query
        description: 'Field to order by: `occurred_at` (default), `amount`, or `transaction_type`.'
        required: false
        schema:
          type: string
      - name: order
        in: query
        description: 'Order direction: `desc` (default) or `asc`.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Paginated wallet transaction list, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletTransactionsResponse'
        '400':
          description: Unknown `sort` or `order` value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid API key, session token, or agent token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: The key or agent token lacks the `billing:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
  /api/wallet/transactions/grouped:
    get:
      tags:
      - Wallet
      summary: Returns the caller's wallet transactions grouped by verification job, newest…
      description: 'Every transaction sharing the same `job_uuid` (a reservation followed by its commit or cancel) forms one group; a credit or top-up (no linked job) is its own single-entry group. Accepts the same `limit` (default 20, cap 96), `offset` (default 0), and sort (`sort` = `occurred_at` | `amount` | `transaction_type`, `order` = `desc` | `asc`) parameters as `GET /api/wallet/transactions`, applied to groups rather than single transactions: `sort=occurred_at` orders by each group''s most recent entry, `sort=amount` by the group''s net signed amount, and `sort=transaction_type` by the type of the group''s most recent entry. An unknown `sort` or `order` value is a `400`.'
      operationId: list_wallet_transaction_groups
      parameters:
      - name: limit
        in: query
        description: Number of groups to return (default 20, cap 96).
        required: false
        schema:
          type: integer
          format: int64
      - name: offset
        in: query
        description: Number of groups to skip (default 0).
        required: false
        schema:
          type: integer
          format: int64
      - name: sort
        in: query
        description: 'Column to order groups by: `occurred_at` (default), `amount`, or `transaction_type`.'
        required: false
        schema:
          type: string
      - name: order
        in: query
        description: 'Order direction: `desc` (default) or `asc`.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Paginated, job-grouped wallet transaction list, newest group first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletTransactionGroupsResponse'
        '400':
          description: Unknown `sort` or `order` value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid API key, session token, or agent token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: The key or agent token lacks the `billing:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - bearer_api_key: []
      - jwt: []
components:
  schemas:
    ApiErrorBody:
      type: object
      description: 'Error envelope returned with every non-success status: `{ "error": { "code", "message" } }`.'
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
          description: Error detail.
    BalanceHistoryRangePoint:
      type: object
      description: A single point in the range-selectable balance-history response body.
      required:
      - date
      - balance
      properties:
        balance:
          type: integer
          format: int32
          description: Available token balance at the end of the bucket.
          minimum: 0
        date:
          type: string
          description: Start of the bucket, as an RFC 3339 timestamp, which keeps the hour for the `"hour"` granularity.
    BalanceHistoryRangeResponse:
      type: object
      description: JSON response body for `GET /api/wallet/balance-history`.
      required:
      - points
      properties:
        points:
          type: array
          items:
            $ref: '#/components/schemas/BalanceHistoryRangePoint'
          description: The available balance series, oldest first.
    WalletTransactionGroupItem:
      type: object
      description: 'A single entry of the job-grouped response: every transaction sharing the same `job_uuid` collapsed into one group.'
      required:
      - last_status
      - net_amount
      - occurred_at
      - entries
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/WalletTransactionItem'
          description: Every transaction in the group, oldest first (for example a reservation followed by its commit or cancel).
        job_uuid:
          type:
          - string
          - 'null'
          format: uuid
          description: Public UUID of the linked verification job. `null` for a credit or top-up, which is its own single-entry group.
        last_status:
          type: string
          description: 'The transaction type of the group''s most recent entry (`"Reservation"`, `"Commit"`, `"Cancel"`, `"Credit"` or

            `"Debit"`), which is the job''s current billing state.'
        net_amount:
          type: integer
          format: int64
          description: 'The signed net effect of the whole group on the wallet: positive for a net inflow (a credit, or a

            canceled/refunded reservation), negative for a net outflow (a debit, a pending reservation, or a

            committed/billed job).'
        occurred_at:
          type: string
          format: date-time
          description: Timestamp of the group's most recent entry.
    WalletBalanceResponse:
      type: object
      description: JSON response body for `GET /api/wallet`.
      required:
      - available
      - reserved
      - total
      - updated_at
      - avg_daily_spend
      properties:
        available:
          type: integer
          format: int32
          description: Tokens available for immediate use.
          minimum: 0
        avg_daily_spend:
          type: integer
          format: int32
          description: 'Mean daily spend (committed plus debited tokens) over the last 30 days, rounded down.

            Divide `available` by it to estimate the remaining runway.'
          minimum: 0
        reserved:
          type: integer
          format: int32
          description: Tokens reserved by in-flight jobs.
          minimum: 0
        total:
          type: integer
          format: int32
          description: Total tokens (available + reserved), capped at 4294967295.
          minimum: 0
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the last balance update.
    WalletTransactionGroupsResponse:
      type: object
      description: JSON response body for `GET /api/wallet/transactions/grouped`.
      required:
      - groups
      - limit
      - offset
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/WalletTransactionGroupItem'
          description: Transaction groups of the page.
        limit:
          type: integer
          format: int64
          description: Page size applied after clamping, counted in groups.
        offset:
          type: integer
          format: int64
          description: Offset applied, counted in groups.
    ApiErrorDetail:
      type: object
      description: Detail of an error response.
      required:
      - code
      properties:
        code:
          type: string
          description: Stable key identifying the error (for example `"verify.invalid_uuid"`). Clients localize by this key.
        message:
          type:
          - string
          - 'null'
          description: 'Present on most error kinds and equal to `code`; the API returns no localized text.

            Absent for error kinds that carry no extra detail.'
    WalletTransactionsResponse:
      type: object
      description: JSON response body for `GET /api/wallet/transactions`.
      required:
      - transactions
      - limit
      - offset
      properties:
        limit:
          type: integer
          format: int64
          description: Page size applied after clamping.
        offset:
          type: integer
          format: int64
          description: Offset applied.
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/WalletTransactionItem'
          description: Transactions of the page.
    WalletTransactionItem:
      type: object
      description: A single transaction item in the response list.
      required:
      - transaction_type
      - amount
      - context
      - occurred_at
      properties:
        amount:
          type: integer
          format: int32
          description: Token amount moved.
          minimum: 0
        context:
          type: string
          description: Short label describing why the transaction happened.
        job_uuid:
          type:
          - string
          - 'null'
          format: uuid
          description: 'Public UUID of the linked verification job, when the transaction is tied to one.

            `null` for a credit or top-up transaction, which carries no job.'
        occurred_at:
          type: string
          format: date-time
          description: RFC 3339 timestamp of the transaction.
        transaction_type:
          type: string
          description: 'Transaction type: `"Credit"`, `"Debit"`, `"Reservation"`, `"Commit"` or `"Cancel"`.'
  securitySchemes:
    bearer_api_key:
      type: http
      scheme: bearer
      description: A `pm_live_*` or `pm_test_*` API key.
    jwt:
      type: http
      scheme: bearer
      description: A short-lived token from `/api/auth/login`, or `/oauth/token` for an agent.
x-refined-from:
- pricklymails-com-openapi.json
- pricklymails-com-openapi.yaml