zvid-io Credits API

openapi: 3.2.0
info:
  title: Zvid Io Credits API
  version: 1.1.0
  contact:
    name: Zvid Support
    url: https://zvid.io/contact
  description: 'Operations tagged Credits across 2 of this provider''s published API definitions: openapi.yaml, zvid-io-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.zvid.io
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Credits
  description: Credit balance and transaction management
paths:
  /api/credits/balance:
    get:
      tags:
      - Credits
      summary: Get credit balance
      description: Retrieve the authenticated user's current credit balance
      operationId: getCreditBalance
      responses:
        '200':
          description: Credit balance retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalance'
              example:
                balance: 1800
                subscriptionCredits: 1200
                addonCredits:
                  balance: 600
                  totalEarned: 1000
                  totalSpent: 400
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Failed to get credit balance
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
    servers:
    - url: https://api.zvid.io
      description: Production server
  /api/credits/transactions:
    get:
      tags:
      - Credits
      summary: Get transaction history
      description: Retrieve paginated list of credit transactions
      operationId: getTransactions
      parameters:
      - name: page
        in: query
        description: Page number
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Transaction history retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
    servers:
    - url: https://api.zvid.io
      description: Production server
  /api/credits/usage-stats:
    get:
      tags:
      - Credits
      summary: Get usage statistics
      description: Retrieve credit usage statistics for a specified timeframe
      operationId: getUsageStats
      parameters:
      - name: timeframe
        in: query
        description: Timeframe for statistics (24h, 7d, or 30d)
        schema:
          type: string
          enum:
          - 24h
          - 7d
          - 30d
          default: 30d
          example: 30d
        examples:
          last24hours:
            value: 24h
            summary: Last 24 hours
          last7days:
            value: 7d
            summary: Last 7 days
          last30days:
            value: 30d
            summary: Last 30 days
      responses:
        '200':
          description: Usage statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageStats'
              example:
                timeframe: 30d
                totalSpent: 500
                totalEarned: 1000
                totalRefunded: 50
                dailyUsage:
                - date: '2025-01-15'
                  spent: 100
                  earned: 0
                - date: '2025-01-14'
                  spent: 75
                  earned: 500
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
    servers:
    - url: https://api.zvid.io
      description: Production server
components:
  schemas:
    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: Validation failed
        message:
          type: string
          example: Please check your input and try again
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                example: name
              message:
                type: string
                example: Name is required
            required:
            - field
            - message
            additionalProperties: false
        planLimits:
          type: object
          description: Present on render validation errors; contains the authenticated user's current render limits.
          additionalProperties: true
      required:
      - error
      additionalProperties: true
    UsageStats:
      type: object
      properties:
        timeframe:
          type: string
          description: The timeframe for the statistics
          example: 30d
        totalSpent:
          type: integer
          description: Total credits spent in the timeframe
          example: 500
        totalEarned:
          type: integer
          description: Total credits earned in the timeframe
          example: 1000
        totalRefunded:
          type: integer
          description: Total credits refunded in the timeframe
          example: 50
        dailyUsage:
          type: array
          description: Daily breakdown of credit usage
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                description: Date of the usage
                example: '2025-01-15'
              spent:
                type: integer
                description: Credits spent on this day
                example: 100
              earned:
                type: integer
                description: Credits earned on this day
                example: 0
            required:
            - date
            - spent
            - earned
            additionalProperties: false
      required:
      - timeframe
      - totalSpent
      - totalEarned
      - totalRefunded
      - dailyUsage
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Human-readable error message
      required:
      - error
      additionalProperties: true
    Transaction:
      type: object
      properties:
        id:
          type: integer
          example: 456
        userId:
          type: integer
          example: 123
        amount:
          type: integer
          description: Transaction amount (positive for additions, negative for deductions)
          example: -10
        transactionType:
          type: string
          enum:
          - earned
          - spent
          - admin_adjustment
          - credit_pack
          - revoke
          - plan_change_adjustment
          description: Type of transaction
          example: spent
        creditSource:
          type:
          - string
          - 'null'
          enum:
          - addon
          - subscription
          description: Credit pool affected by this transaction
          example: subscription
        subscriptionCreditPeriodId:
          type:
          - integer
          - 'null'
          description: Subscription credit period touched by this transaction, if applicable
          example: 42
        jobId:
          type:
          - string
          - 'null'
          format: uuid
          description: Related job ID (if applicable)
          example: 550e8400-e29b-41d4-a716-446655440000
        description:
          type: string
          example: 'Video render: 1920x1080, 30s'
        metadata:
          oneOf:
          - type: object
            additionalProperties: true
          - type: string
          - type: 'null'
          example: null
        createdAt:
          type: string
          format: date-time
          example: '2025-01-15T10:30:00.000Z'
      required:
      - id
      - userId
      - amount
      - transactionType
      - createdAt
      additionalProperties: false
    AuthenticationError:
      type: object
      properties:
        error:
          type: string
          description: Error type
          example: API key required
        message:
          type: string
          description: Human-readable error message
          example: Please provide an API key in the X-API-Key header or Authorization header
      required:
      - error
      additionalProperties: false
    TransactionList:
      type: object
      properties:
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        pagination:
          type: object
          properties:
            page:
              type: integer
              example: 1
            limit:
              type: integer
              example: 20
            total:
              type: integer
              example: 100
            totalPages:
              type: integer
              example: 5
            hasNext:
              type: boolean
              description: Whether there are more pages after the current one
              example: true
            hasPrev:
              type: boolean
              description: Whether there are pages before the current one
              example: false
          required:
          - page
          - limit
          - total
          - totalPages
          - hasNext
          - hasPrev
          additionalProperties: false
      required:
      - transactions
      - pagination
      additionalProperties: false
    CreditBalance:
      type: object
      properties:
        balance:
          type: integer
          description: Total available credits from subscription and add-on pools
          example: 1800
        subscriptionCredits:
          type: integer
          description: Credits remaining in the current subscription period
          example: 1200
        addonCredits:
          type: object
          description: Add-on credit pool and historical add-on totals
          properties:
            balance:
              type: integer
              description: Available add-on credits
              example: 600
            totalEarned:
              type: integer
              description: Total add-on credits earned over all time
              example: 1000
            totalSpent:
              type: integer
              description: Total add-on credits spent over all time
              example: 400
          required:
          - balance
          - totalEarned
          - totalSpent
          additionalProperties: false
      required:
      - balance
      - subscriptionCredits
      - addonCredits
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Create one in your dashboard.
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Dashboard JWT in Authorization: Bearer <token>, only on operations that explicitly list this scheme. Prefer x-api-key for REST integrations. OAuth for hosted MCP is a separate connection at https://mcp.zvid.io/mcp.'
x-refined-from:
- openapi.yaml
- zvid-io-openapi.yaml