grabbit-live Account API

openapi: 3.2.0
info:
  title: Grabbit Live Account API
  version: 1.0.0
  contact:
    name: Grabbit support
    email: support@grabbit.live
    url: https://www.grabbit.live/contact
  termsOfService: https://www.grabbit.live/terms
  description: 'Operations tagged Account across 2 of this provider''s published API definitions: grabbit-live-openapi.json, www.grabbit.live_openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.grabbit.live/v1
  description: Production
- url: https://www.grabbit.live/api/v1
  description: Production (same API on the web origin)
security:
- bearerAuth: []
- oauth2:
  - grabs
tags:
- name: Account
  description: Credits, usage, and pricing.
paths:
  /usage:
    get:
      operationId: getUsage
      summary: Get credit balance and usage
      description: Returns remaining credits (subscription + prepaid), the plan, and 30-day grab counts. Check this before a large batch so you can top up first.
      tags:
      - Account
      security:
      - bearerAuth: []
      - oauth2:
        - grabs
      x-codeSamples:
      - lang: Shell
        label: curl
        source: 'curl https://api.grabbit.live/v1/usage -H "Authorization: Bearer sk_live_..."'
      responses:
        '200':
          description: Credits and usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '401':
          description: Missing or invalid Bearer token (`unauthorized`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.grabbit.live/v1
      description: Production
    - url: https://www.grabbit.live/api/v1
      description: Production (same API on the web origin)
  /pricing:
    get:
      operationId: getPricing
      summary: Get pricing and competitor comparison
      description: Public, no auth. Flat per-grab price, prepaid packages, and a dated comparison against other screenshot APIs.
      tags:
      - Account
      parameters:
      - name: provider
        in: query
        required: false
        description: Optional competitor filter for a smaller comparison response.
        schema:
          type: string
          enum:
          - urlbox
          - screenshotone
          - apiflash
      - name: detail
        in: query
        required: false
        description: Use summary for a smaller packet. REST returns full detail by default; MCP get_pricing returns summary by default.
        schema:
          type: string
          enum:
          - summary
          - full
      security: []
      x-codeSamples:
      - lang: Shell
        label: curl
        source: curl "https://api.grabbit.live/v1/pricing?provider=apiflash&detail=full"
      responses:
        '200':
          description: Pricing packet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pricing'
        '400':
          description: Unknown provider or detail value (`bad_request`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.grabbit.live/v1
      description: Production
    - url: https://www.grabbit.live/api/v1
      description: Production (same API on the web origin)
components:
  schemas:
    Pricing:
      type: object
      properties:
        pricing:
          type: object
          properties:
            per_grab_usd:
              type: number
            currency:
              type: string
            billing_model:
              type: string
            free_tier:
              type: boolean
            test_mode:
              type: string
            annual:
              type: object
              properties:
                price_usd:
                  type: number
                credits_per_year:
                  type: integer
                reset_policy:
                  type: string
              required:
              - price_usd
              - credits_per_year
              - reset_policy
              additionalProperties: {}
            prepaid_packages:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  credits:
                    type: integer
                  price_usd:
                    type: number
                  reset_policy:
                    type: string
                required:
                - name
                - credits
                - price_usd
                - reset_policy
                additionalProperties: {}
          required:
          - per_grab_usd
          - currency
          - billing_model
          - free_tier
          - test_mode
          - annual
          - prepaid_packages
          additionalProperties: {}
        comparison:
          type: object
          properties:
            schema_version:
              type: string
            detail:
              type: string
            detail_hint:
              type: string
            last_verified:
              type: string
            features:
              type: array
              items:
                type: string
            providers:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  plan:
                    type: string
                  per_grab:
                    type: string
                  billing:
                    type: string
                  billing_unit:
                    type: string
                  quota_note:
                    type: string
                  included:
                    type: string
                  unused_credits:
                    type: string
                  features_supported:
                    type: array
                    items:
                      type: string
                  agent_install:
                    type: string
                  source_url:
                    type: string
                  verified_on:
                    type: string
                  evidence_status:
                    type: string
                  pricing_evidence:
                    type: object
                    properties:
                      source_url:
                        type: string
                      locator:
                        type: string
                      note:
                        type: string
                      status:
                        type: string
                    required:
                    - source_url
                    - locator
                    - note
                    - status
                    additionalProperties: {}
                  quota_evidence:
                    anyOf:
                    - type: object
                      properties:
                        source_url:
                          type: string
                        locator:
                          type: string
                        note:
                          type: string
                        status:
                          type: string
                      required:
                      - source_url
                      - locator
                      - note
                      - status
                      additionalProperties: {}
                    - type: 'null'
                  capture_evidence:
                    type: object
                    properties:
                      source_url:
                        type: string
                      locator:
                        type: string
                      note:
                        type: string
                      status:
                        type: string
                    required:
                    - source_url
                    - locator
                    - note
                    - status
                    additionalProperties: {}
                  agent_evidence:
                    type: object
                    properties:
                      source_url:
                        type: string
                      locator:
                        type: string
                      note:
                        type: string
                      status:
                        type: string
                    required:
                    - source_url
                    - locator
                    - note
                    - status
                    additionalProperties: {}
                  is_grabbit:
                    type: boolean
                required:
                - name
                - plan
                - per_grab
                - billing
                - billing_unit
                - quota_note
                - included
                - unused_credits
                - features_supported
                - agent_install
                - source_url
                - verified_on
                - evidence_status
                - pricing_evidence
                - quota_evidence
                - capture_evidence
                - agent_evidence
                - is_grabbit
                additionalProperties: {}
            decision_pages:
              type: array
              items:
                type: object
                properties:
                  competitor:
                    type: string
                  url:
                    type: string
                  verdict:
                    type: string
                  pricing_tiers:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                      required:
                      - name
                      additionalProperties: {}
                  capture_capabilities:
                    type: array
                    items:
                      type: string
                  best_fit:
                    type: array
                    items:
                      type: string
                required:
                - competitor
                - url
                - verdict
                - pricing_tiers
                - capture_capabilities
                - best_fit
                additionalProperties: {}
            agent_surfaces:
              type: array
              items:
                type: object
                properties:
                  provider:
                    type: string
                  comparison_url:
                    type: string
                  surfaces:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        availability:
                          type: string
                        grabbit_availability:
                          type: string
                        source_url:
                          type: string
                        verified_on:
                          type: string
                      required:
                      - name
                      - availability
                      - grabbit_availability
                      - source_url
                      - verified_on
                      additionalProperties: {}
                required:
                - provider
                - comparison_url
                - surfaces
                additionalProperties: {}
            sources:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                  url:
                    type: string
                  locator:
                    type: string
                  claim_group:
                    type: string
                  verified_on:
                    type: string
                  note:
                    type: string
                  evidence_status:
                    type: string
                required:
                - label
                - url
                - locator
                - claim_group
                - verified_on
                - note
                - evidence_status
                additionalProperties: {}
            notes:
              type: string
          required:
          - schema_version
          - last_verified
          - features
          - providers
          - decision_pages
          - agent_surfaces
          - notes
          additionalProperties: {}
        links:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
      required:
      - pricing
      - comparison
      - links
      additionalProperties: {}
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - bad_request
              - invalid_viewport
              - ssrf_detected
              - credits_exhausted
              - not_found
              - idempotency_conflict
              - idempotency_mismatch
              - rate_limit_exceeded
              - queue_limit_exceeded
              - render_blocked
              - render_failed
              - internal_error
              description: Stable machine-readable code. Branch on this, not the message.
            message:
              type: string
              description: Human-readable explanation.
    Usage:
      type: object
      properties:
        credits:
          type: object
          properties:
            subscription:
              type: integer
            prepaid:
              type: integer
            total:
              type: integer
          required:
          - subscription
          - prepaid
          - total
          additionalProperties: {}
        plan:
          type: object
          properties:
            name:
              type: string
            status:
              type: string
            expires_at:
              anyOf:
              - type: string
              - type: 'null'
          required:
          - name
          - status
          - expires_at
          additionalProperties: {}
        usage:
          type: object
          properties:
            grabs_last_30d:
              description: All grabs, both environments.
              type: integer
            live_grabs_last_30d:
              type: integer
          required:
          - grabs_last_30d
          - live_grabs_last_30d
          additionalProperties: {}
        environment:
          type: string
          enum:
          - live
          - test
        top_up:
          description: Where to buy more credits.
          type: string
      required:
      - credits
      - plan
      - usage
      - environment
      - top_up
      additionalProperties: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from https://grabbit.live/app/api-keys. sk_live_ keys render real screenshots and spend credits; sk_test_ keys return free placeholders.
    oauth2:
      type: oauth2
      description: OAuth 2.1 authorization code + PKCE with dynamic client registration (RFC 7591). Used by MCP clients such as claude.ai.
      flows:
        authorizationCode:
          authorizationUrl: https://www.grabbit.live/oauth/authorize
          tokenUrl: https://www.grabbit.live/api/v1/oauth/token
          refreshUrl: https://www.grabbit.live/api/v1/oauth/token
          scopes:
            grabs: Create, list, and read screenshots and read the team's credit balance.
externalDocs:
  description: API reference
  url: https://www.grabbit.live/docs
x-refined-from:
- grabbit-live-openapi.json
- www.grabbit.live_openapi.json