openapi: 3.2.0
info:
  title: Vaquill Ai India Credits API
  version: 1.0.0
  contact:
    name: Vaquill API Support
    url: https://www.vaquill.ai
    email: support@vaquill.ai
  license:
    name: Proprietary
    url: https://www.vaquill.ai/terms
  termsOfService: https://www.vaquill.ai/terms
  description: 'Operations tagged India Credits across 2 of this provider''s published API definitions: vaquill-ai-india-openapi.json, vaquill-ai-india-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.vaquill.ai
  description: Production
security:
- ApiKeyAuth: []
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: India Credits
paths:
  /api/v1/in/credits/balance:
    get:
      tags:
      - India Credits
      summary: Get your India API credit balance
      description: 'Returns the credits this API key''s account can spend right now.


        **Free.** Never charged, so it is safe to poll for low-balance alerting or to

        pre-flight a batch job.


        **Authentication:** any valid `vq_key_` key. No particular scope is required.


        Credits are account-wide and are **not** split by jurisdiction: the same balance

        funds the India legislation endpoints and the United States primary-law

        endpoints, from one ledger. This route and the United States

        `GET /api/v1/credits/balance` therefore report the same number, and spending on

        either surface moves both.


        Read `bySource` before assuming a balance is durable: `subscription` credits are

        use-it-or-lose-it at the period end, while `payg` credits you purchased persist

        and burn last. `nextExpiry` tells you what is about to be forfeited and when.


        ## Example


        ```bash

        curl https://api.vaquill.ai/api/v1/in/credits/balance \

        -H "Authorization: Bearer $VAQUILL_API_KEY"

        ```'
      operationId: get_india_credit_balance_api_v1_in_credits_balance_get
      responses:
        '200':
          description: Current spendable balance for the calling key's account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalCreditBalanceResponse'
              example:
                creditsRemaining: 103039.0
                usdRemaining: 1030.39
                bySource:
                - source: comp
                  credits: 20000.0
                - source: payg
                  credits: 64699.0
                - source: subscription
                  credits: 18340.0
                nextExpiry:
                  at: '2026-10-12T13:56:31Z'
                  credits: 18340.0
                plan: business
                totalPurchased: 143960.0
                totalConsumed: 48471.0
                rateLimit:
                  perMinute: 150
                  perHour: 2500
                  perDay: 10000
                asOf: '2026-09-19T12:34:56Z'
        '401':
          description: Missing, malformed or unrecognised API key. Note this endpoint accepts ONLY a `vq_key_` API key; a dashboard session token is rejected here.
          content:
            application/json:
              example:
                detail: Invalid token
        '429':
          description: Request-rate ceiling exceeded. Retry after the `Retry-After` header. Being throttled says nothing about your balance.
          content:
            application/json:
              example:
                detail: Rate limit exceeded. Try again in 42 seconds.
    servers:
    - url: https://api.vaquill.ai
      description: Production
components:
  schemas:
    CreditRateLimit:
      properties:
        perMinute:
          type: integer
          title: Perminute
          description: Requests allowed per minute on this key, plan multiplier already applied.
          examples:
          - 150
        perHour:
          type: integer
          title: Perhour
          description: Requests allowed per hour on this key.
          examples:
          - 2000
        perDay:
          type: integer
          title: Perday
          description: Requests allowed per day on this key.
          examples:
          - 10000
      type: object
      required:
      - perMinute
      - perHour
      - perDay
      title: CreditRateLimit
      description: 'Request-rate ceilings in force for the calling key.


        A SECOND, independent ceiling alongside credits, and the two are unrelated:

        you can hold credits and still be throttled, or sit far under these limits

        and be refused for an empty balance.'
    CreditSourceBreakdown:
      properties:
        source:
          type: string
          title: Source
          description: 'Where the credits came from. `bonus` (signup grant), `subscription` (plan allowance, use-it-or-lose-it), `payg` (purchased packs) and `comp` (complimentary) exist today, and this list is not closed: read the values rather than matching on a fixed set.'
          examples:
          - payg
        credits:
          type: number
          title: Credits
          description: Credits remaining in this source. 1 credit = $0.01.
          examples:
          - 1030.43
      type: object
      required:
      - source
      - credits
      title: CreditSourceBreakdown
      description: Live credits held under one funding source.
    ExternalCreditBalanceResponse:
      properties:
        creditsRemaining:
          type: number
          title: Creditsremaining
          description: 'Credits you can actually spend right now. Deliberately the same field name that metered responses return, so one name means one thing across the API.


            Derived from your live credit buckets under the same expiry rule the billing path applies, so it never promises credits a call would refuse to spend.'
          examples:
          - 103039.0
        usdRemaining:
          type: number
          title: Usdremaining
          description: '`creditsRemaining` in USD, at the published conversion rate (1 credit = $0.01). Provided so you do not have to hardcode the rate; `GET /api/v1/api-credits/pricing` is its source of truth.'
          examples:
          - 1030.39
        bySource:
          items:
            $ref: '#/components/schemas/CreditSourceBreakdown'
          type: array
          title: Bysource
          description: '`creditsRemaining` split by funding source, and it always sums to it. Worth reading because the sources do not behave alike: `subscription` credits are use-it-or-lose-it at the period end, while `payg` credits you bought are durable and burn last.'
        nextExpiry:
          anyOf:
          - $ref: '#/components/schemas/CreditExpiry'
          - type: 'null'
          description: The soonest expiry across your credits, or `null` if none of them expire. Poll this to avoid silently forfeiting an allowance.
        plan:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan
          description: Active API subscription tier, or `null` on pay-as-you-go. Also determines your rate-limit multiplier. Briefly cached, so a subscription change made seconds ago may not be reflected yet; `creditsRemaining` is always live.
          examples:
          - business
        totalPurchased:
          type: number
          title: Totalpurchased
          description: Lifetime credits added to this account.
          examples:
          - 150000.0
        totalConsumed:
          type: number
          title: Totalconsumed
          description: Lifetime credits spent by this account.
          examples:
          - 46961.0
        rateLimit:
          anyOf:
          - $ref: '#/components/schemas/CreditRateLimit'
          - type: 'null'
          description: 'How fast this key may call, as opposed to how much it may spend. The two ceilings are independent: holding credits does not exempt you from these, and staying under these does not pay for a call.


            These are the ceilings themselves, with your plan already applied, so you can size a client BEFORE issuing a request. The `X-RateLimit-*` headers on every response report the same ceilings plus your live headroom, and the two agree.'
        asOf:
          type: string
          format: date-time
          title: Asof
          description: When this balance was computed. The value is live, not cached, so this is the instant the buckets were read.
      type: object
      required:
      - creditsRemaining
      - usdRemaining
      - totalPurchased
      - totalConsumed
      - asOf
      title: ExternalCreditBalanceResponse
      description: Spendable credit balance for the calling API key's account.
    CreditExpiry:
      properties:
        at:
          type: string
          format: date-time
          title: At
          description: UTC instant at which the next credits expire.
          examples:
          - '2026-10-01T00:00:00Z'
        credits:
          type: number
          title: Credits
          description: Credits that expire at that instant. They stop being spendable immediately at `at`, not when the nightly sweep records it.
          examples:
          - 500.0
      type: object
      required:
      - at
      - credits
      title: CreditExpiry
      description: The soonest expiry, and what dies with it.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: vq_key_*
      description: 'API key issued from the developer dashboard. Pass as `Authorization: Bearer vq_key_...` (preferred).'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'The same API key as a bare header value: `X-API-Key: vq_key_...`. Equivalent to the Bearer form.'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: 'The same API key as a query parameter: `?api_key=vq_key_...`. Use only where you cannot set a header. A URL can end up in proxy and server logs, browser history and shared links, so prefer either header form, and rotate a key that has leaked.'
x-refined-from:
- vaquill-ai-india-openapi.json
- vaquill-ai-india-openapi.yml