Lium Penalties API

The Penalties API from Lium — 2 operation(s) for penalties.

GitHub OpenAPI

Operations 2

GET /penalties List Penalties #
POST /penalties/{penalty_event_id}/dispute Open Dispute #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/lium-io:lium-io-penalties-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

lium-io-penalties-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Lium Miner Portal Penalties API
  version: 0.1.0
servers:
- url: /api
tags:
- name: Penalties
paths:
  /penalties:
    get:
      tags:
      - Penalties
      summary: List Penalties
      description: 'Every applied penalty on the caller''s rentals, newest first (no paging, no cap), each with the

        evidence the trigger recorded (`validator_reports`: the stale window and the validator''s failed

        reports in it, by reason), the revert if any, and the dispute state. `status`: active | reverted | disputed |

        open | accepted | rejected.'
      operationId: list_penalties_penalties_get
      security:
      - JwtAccessBearer: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(active|reverted|disputed|open|accepted|rejected)$
          - type: 'null'
          title: Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse_list_PenaltyResponse__'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /penalties/{penalty_event_id}/dispute:
    post:
      tags:
      - Penalties
      summary: Open Dispute
      description: 'File a dispute: reason (≤ 2000 chars) and up to 5 evidence URLs. One dispute per penalty

        (a decided one is not refiled here), only on the caller''s rentals, within 30 days of the penalty.

        The Lium team decides it; an accepted dispute reverts the penalty.'
      operationId: open_dispute_penalties__penalty_event_id__dispute_post
      security:
      - JwtAccessBearer: []
      parameters:
      - name: penalty_event_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Penalty Event Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenDisputeRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse_PenaltyResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    OpenDisputeRequest:
      properties:
        reason:
          type: string
          maxLength: 2000
          minLength: 1
          title: Reason
        evidence_urls:
          items:
            type: string
            maxLength: 2083
            minLength: 1
            format: uri
          type: array
          maxItems: 5
          title: Evidence Urls
      type: object
      required:
      - reason
      title: OpenDisputeRequest
    PenaltyReasonCount:
      properties:
        reason_code:
          type: string
          title: Reason Code
        count:
          type: integer
          title: Count
      type: object
      required:
      - reason_code
      - count
      title: PenaltyReasonCount
      description: How many of the failed reports in the window carried one reason code.
    PenaltyDisputeResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        status:
          type: string
          title: Status
        reason:
          type: string
          title: Reason
        evidence_urls:
          items:
            type: string
          type: array
          title: Evidence Urls
        created_at:
          type: string
          format: date-time
          title: Created At
        decision:
          anyOf:
          - type: string
          - type: 'null'
          title: Decision
        decision_note:
          anyOf:
          - type: string
          - type: 'null'
          title: Decision Note
        decided_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Decided At
        revert_event_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Revert Event Id
      type: object
      required:
      - id
      - status
      - reason
      - evidence_urls
      - created_at
      title: PenaltyDisputeResponse
    PenaltyRentalResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        pod_id:
          type: string
          format: uuid
          title: Pod Id
        executor_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Executor Id
        machine_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Machine Name
        gpu_type:
          type: string
          title: Gpu Type
        gpu_count:
          type: integer
          title: Gpu Count
        rental_start_time:
          type: string
          format: date-time
          title: Rental Start Time
        rental_end_time:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Rental End Time
        close_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Close Reason
      type: object
      required:
      - id
      - pod_id
      - gpu_type
      - gpu_count
      - rental_start_time
      title: PenaltyRentalResponse
    PenaltyFailedReport:
      properties:
        received_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Received At
        job_batch_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Job Batch Id
        validator_hotkey:
          anyOf:
          - type: string
          - type: 'null'
          title: Validator Hotkey
        reason_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason Code
        check_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Check Id
        log_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Log Status
      type: object
      title: PenaltyFailedReport
      description: 'One failed validator report in the window. Only the most recent reports are listed; the parent''s

        `failed_count` is the full number.'
    DetailResponse_list_PenaltyResponse__:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
          default: true
        data:
          items:
            $ref: '#/components/schemas/PenaltyResponse'
          type: array
          title: Data
          description: Single item data
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Response timestamp
      type: object
      required:
      - data
      title: DetailResponse[list[PenaltyResponse]]
    DetailResponse_PenaltyResponse_:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful
          default: true
        data:
          $ref: '#/components/schemas/PenaltyResponse'
          description: Single item data
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Response timestamp
      type: object
      required:
      - data
      title: DetailResponse[PenaltyResponse]
    PenaltyStaleWindow:
      properties:
        since:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Since
        since_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Since Source
        until:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Until
      type: object
      title: PenaltyStaleWindow
      description: 'The period the penalty was decided on: from the node''s last positive validator report

        (`since_source` = last_positive_report; `since` is empty with no_positive_report_on_record) to

        the moment the penalty was decided (`until`).'
    PenaltyValidatorReports:
      properties:
        window:
          $ref: '#/components/schemas/PenaltyStaleWindow'
        failed_count:
          type: integer
          title: Failed Count
          default: 0
        reasons:
          items:
            $ref: '#/components/schemas/PenaltyReasonCount'
          type: array
          title: Reasons
        failed:
          items:
            $ref: '#/components/schemas/PenaltyFailedReport'
          type: array
          title: Failed
      type: object
      required:
      - window
      title: PenaltyValidatorReports
      description: 'The window a penalty was decided on and the failed validator reports in it, counted by reason

        code.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PenaltyRevertResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        reverted_by:
          type: string
          enum:
          - system
          - staff
          title: Reverted By
        revert_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Revert Mode
      type: object
      required:
      - id
      - created_at
      - reverted_by
      title: PenaltyRevertResponse
    PenaltyResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        reason_code:
          type: string
          title: Reason Code
        amount_withheld:
          anyOf:
          - type: number
          - type: 'null'
          title: Amount Withheld
        settlement_pending:
          type: boolean
          title: Settlement Pending
          default: false
        renter_refund_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Renter Refund Usd
        provider_debt_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Provider Debt Usd
        provider_debt_repriced_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Provider Debt Repriced Usd
        provider_debt_withheld_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Provider Debt Withheld Usd
        hours_charged:
          anyOf:
          - type: number
          - type: 'null'
          title: Hours Charged
        created_at:
          type: string
          format: date-time
          title: Created At
        applied_by:
          type: string
          enum:
          - system
          - staff
          title: Applied By
        billing_days:
          items:
            type: string
          type: array
          title: Billing Days
        refund_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Refund Status
        rental:
          $ref: '#/components/schemas/PenaltyRentalResponse'
        trigger:
          anyOf:
          - type: string
          - type: 'null'
          title: Trigger
        validator_reports:
          anyOf:
          - $ref: '#/components/schemas/PenaltyValidatorReports'
          - type: 'null'
        reverted:
          anyOf:
          - $ref: '#/components/schemas/PenaltyRevertResponse'
          - type: 'null'
        dispute:
          anyOf:
          - $ref: '#/components/schemas/PenaltyDisputeResponse'
          - type: 'null'
        can_dispute:
          type: boolean
          title: Can Dispute
        cannot_dispute_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Cannot Dispute Reason
        dispute_window_closes_at:
          type: string
          format: date-time
          title: Dispute Window Closes At
      type: object
      required:
      - id
      - reason_code
      - amount_withheld
      - created_at
      - applied_by
      - rental
      - can_dispute
      - dispute_window_closes_at
      title: PenaltyResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    JwtAccessBearer:
      type: http
      scheme: bearer
    HTTPBearer:
      type: http
      scheme: bearer