Onto Usage API

openapi: 3.2.0
info:
  title: Onto Read Usage API
  version: 1.0.0
  summary: Turn any URL into clean Markdown, an AIO accuracy score, and hallucination-risk flags.
  description: 'The Onto Read API takes a URL and returns clean Markdown that an LLM can consume directly,

    plus a 0–100 AIO accuracy score and hallucination-risk metadata.


    **Authentication.** All requests use bearer-token auth — pass your API key in the

    `Authorization` header. Get one at app.buildonto.dev/read/keys;

    the Free tier gives you 1,000 credits a month.


    **Endpoints.** `/v1/read`, `/v1/score`, `/v1/read-and-score` and `/v1/extract` work on one

    URL. `/v1/batch` handles up to 50 URLs in one call, `/v1/map` lists a site''s URLs, and

    `/v1/usage` shows your quota and credits. Most agent workflows want `/v1/read-and-score` —

    it returns both the cleaned Markdown and the accuracy metadata in a single round-trip.


    **Credits.** `/v1/read`, `/v1/read-and-score`, `/v1/extract` and `/v1/map` cost 1 credit per

    call; `/v1/batch` costs 1 credit per URL. `/v1/score` and `/v1/usage` are free. Failed

    requests are refunded.


    **Errors.** Every error response shares the same shape with a stable `code` field — branch

    on `code`, not on the human-readable `message`. Extra details, like `retry_after`, sit at

    the top level of the body. See

    the error codes index for the full catalog.'
  contact:
    name: Onto support
    email: founder@buildonto.dev
    url: https://buildonto.dev
  license:
    name: Proprietary
    url: https://buildonto.dev/legal/terms
servers:
- url: https://api.buildonto.dev
  description: Production
security:
- bearerAuth: []
tags:
- name: Usage
  description: Plan quota, concurrent-slot state, and credit balance.
paths:
  /v1/usage:
    get:
      tags:
      - Usage
      summary: Get your current plan quota, concurrency state, and credit balance
      operationId: getUsage
      description: 'Returns a snapshot of your account''s billing state — current tier, monthly quota

        used vs. limit, concurrent slots in flight, and credit balance. Useful for

        dashboards, low-balance alerts, or before-you-call budget checks.


        Doesn''t count against your monthly quota.'
      responses:
        '200':
          description: Usage snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
              example:
                tier: growth
                monthly_limit: 100000
                used_this_month: 12480
                remaining: 87520
                overage_allowed: true
                reset_at: '2026-10-01T00:00:00.000Z'
                concurrent_limit: 20
                in_flight: 3
                concurrent_remaining: 17
                credits:
                  balance: 2350
                  recent_transactions:
                  - id: 5b1e7c2a-9d4f-4a3b-8e6c-1f2a3b4c5d6e
                    delta: 2200
                    reason: purchase
                    ref: 0c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f
                    balance_after: 2350
                    created_at: '2026-09-15T11:08:43.000Z'
                  - id: 8f3a2b1c-4d5e-4f6a-9b7c-2d3e4f5a6b7c
                    delta: 150
                    reason: grant
                    ref: launch promo
                    balance_after: 150
                    created_at: '2026-09-02T09:21:02.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - status
      - code
      - message
      properties:
        status:
          type: string
          enum:
          - error
        code:
          type: string
          description: Stable error code — branch on this, not on `message`.
        message:
          type: string
          description: Human-readable message; wording may change without notice.
        retry_after:
          oneOf:
          - type: integer
            description: Seconds to wait before retrying (CONCURRENT_LIMIT). Always 1.
          - type: string
            format: date-time
            description: When monthly credits reset — the end of the current UTC month (RATE_LIMITED).
        plan_limit:
          type: integer
          description: Your plan's monthly credits (PAYMENT_REQUIRED).
        credits_remaining:
          type: integer
          description: Bought credits left, always 0 (PAYMENT_REQUIRED).
        in_flight:
          type: integer
          description: Requests running for your account right now (CONCURRENT_LIMIT).
        limit:
          type: integer
          description: Your plan's concurrency limit (CONCURRENT_LIMIT).
    CreditTransaction:
      type: object
      required:
      - id
      - delta
      - reason
      - ref
      - balance_after
      - created_at
      properties:
        id:
          type: string
          format: uuid
        delta:
          type: integer
          description: Positive for credits added, negative for credits used.
        reason:
          type: string
          enum:
          - purchase
          - usage
          - grant
          - refund
          - adjustment
        ref:
          type:
          - string
          - 'null'
          description: What the entry refers to, such as a payment order ID or a note.
        balance_after:
          type: integer
          description: Credit balance right after this entry.
        created_at:
          type: string
          format: date-time
    UsageResponse:
      type: object
      required:
      - tier
      - monthly_limit
      - used_this_month
      - remaining
      - overage_allowed
      - reset_at
      - concurrent_limit
      - in_flight
      - concurrent_remaining
      - credits
      properties:
        tier:
          type: string
          enum:
          - free
          - starter
          - growth
          - scale
          - enterprise
        monthly_limit:
          type: integer
          description: Plan quota for the current billing month.
        used_this_month:
          type: integer
        remaining:
          type: integer
        overage_allowed:
          type: boolean
          description: Whether the tier falls through to credit billing on plan exhaustion.
        reset_at:
          type: string
          format: date-time
          description: ISO timestamp of next billing-cycle reset (start of next UTC month).
        concurrent_limit:
          type: integer
        in_flight:
          type: integer
        concurrent_remaining:
          type: integer
        credits:
          type: object
          properties:
            balance:
              type: integer
              description: Credits available for overage billing.
            recent_transactions:
              type: array
              items:
                $ref: '#/components/schemas/CreditTransaction'
  responses:
    Unauthorized:
      description: Missing, malformed, or revoked Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: error
            code: UNAUTHORIZED
            message: Missing or invalid API key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: onto_sk_live_…
      description: 'Pass your API key as `Authorization: Bearer {your_key}`. Get a key at

        [app.buildonto.dev/read/keys](https://app.buildonto.dev/read/keys).

        '