gribstream-com Account API

openapi: 3.2.0
info:
  title: GribStream Account API
  version: '2026-10-15'
  description: 'Public OpenAPI description for GribStream''s customer-facing forecast query and catalog APIs.


    This published contract documents:

    - `/api/v2/quota` for free token-scoped credit quota and status inspection

    - public catalog discovery endpoints under `/api/v2/catalog/...`

    - `/api/v2/{dataset}/timeseries`

    - `/api/v2/{dataset}/runs`

    - `/api/v2/{dataset}/native-coordinates` for datasets with verified fixed-grid geometry

    - their legacy aliases `/history` and `/forecasts`


    Query responses support:

    - `text/csv` by default

    - `application/json` for a streamed JSON array

    - `application/ndjson` or `application/x-ndjson` for newline-delimited JSON

    - `application/vnd.apache.parquet` for typed, compressed binary results


    POST query endpoints can also return a short-lived signed URL for a CSV, JSON, NDJSON, or

    Parquet artifact by using `?delivery=url&format={format}` with `Accept: application/json`.

    The request body is unchanged.


    Timestamp conventions:

    - all request timestamps are UTC ISO 8601 datetimes

    - all response timestamps are UTC ISO 8601 datetimes


    Current handler behavior documented here:

    - `minLeadTime` / `maxLeadTime` override deprecated integer `minHorizon` / `maxHorizon`

    - on ensemble datasets, omitting `members` returns only the first member

    - deterministic datasets reject explicit `members` filters with `400 Bad Request`'
servers:
- url: https://gribstream.com
  description: Current deployment base URL
security:
- bearerAuth: []
tags:
- name: Account
  description: Token-scoped quota and access status.
paths:
  /api/v2/quota:
    get:
      tags:
      - Account
      summary: Inspect the API token's daily credit quota and status
      operationId: getQuota
      description: 'Requires an API token in the Authorization header. Returns only that token''s

        recorded usage for the current UTC day, configured plan limit, effective limit,

        remaining credits and locally enforced access status. No credits are consumed.

        There is no session or anonymous/demo fallback and no billing-provider call.


        Recognized expired, unpaid or inactive tokens and exhausted quotas return 200

        so customers can inspect their status. Invalid, unknown, deleted or rotated-out

        credentials return 401. Token status and quota exhaustion are independent;

        a future quota reset does not reactivate an expired or inactive token.


        Usage is committed in batches during running requests, so recorded usage can

        lag consumption. Remaining credits are a snapshot, not reserved capacity.

        They are clamped to zero; credits_used may exceed the effective limit due to

        concurrent requests or metering overshoot. quota_exhausted means no positive

        recorded allowance remains; it does not change data-endpoint admission rules.


        The effective limit is ceil(plan_daily_limit * overage_multiplier). The combined

        multiplier is the product of global, plan and token settings, clamped to at least 1.

        Unlimited tokens retain their plan limit and multiplier for reference but return

        null effective_daily_limit and credits_remaining, with quota_exhausted=false.


        Quota resets at 00:00 UTC. When exhausted, recommended_retry_at includes the

        same stable per-token delay of 0–3599 seconds after reset as data-endpoint

        Retry-After guidance. Otherwise recommended_retry_at is null.

        Subscription expiration and renewal dates are not included.


        Example:

        ```bash

        curl -sS "https://gribstream.com/api/v2/quota" \

        -H ''Authorization: Bearer YOUR_TOKEN''

        ```'
      responses:
        '200':
          description: Token quota snapshot, including exhausted or inactive tokens.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaSnapshot'
              example:
                as_of: '2026-10-15T12:00:00Z'
                usage_day_start_at: '2026-10-15T00:00:00Z'
                quota_resets_at: '2026-10-16T00:00:00Z'
                plan_id: 2
                plan_name: Pro Plan
                token_status: active
                credits_used: 12000
                plan_daily_limit: 48000
                overage_multiplier: 1.5
                effective_daily_limit: 72000
                credits_remaining: 60000
                unlimited: false
                quota_exhausted: false
                recommended_retry_at: null
        '401':
          description: Missing, invalid, unknown, deleted or rotated-out API credential.
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/WWWAuthenticateBearer'
        '500':
          $ref: '#/components/responses/ServerErrorNoBody'
components:
  schemas:
    QuotaSnapshot:
      type: object
      required:
      - as_of
      - usage_day_start_at
      - quota_resets_at
      - plan_id
      - plan_name
      - token_status
      - credits_used
      - plan_daily_limit
      - overage_multiplier
      - effective_daily_limit
      - credits_remaining
      - unlimited
      - quota_exhausted
      - recommended_retry_at
      properties:
        as_of:
          type: string
          format: date-time
          description: UTC timestamp identifying the snapshot's accounting day.
        usage_day_start_at:
          type: string
          format: date-time
          description: Start of the current usage day at 00:00 UTC.
        quota_resets_at:
          type: string
          format: date-time
          description: Next daily reset at 00:00 UTC, before retry jitter.
        plan_id:
          type: integer
          description: Token's plan identifier.
        plan_name:
          type: string
        token_status:
          type: string
          enum:
          - active
          - expired
          - unpaid
          - inactive
          description: Locally enforced access status, independent of remaining quota. Cancelled and past_due subscriptions can still be active under existing access rules.
        credits_used:
          type: integer
          format: int64
          description: Recorded credits used by this token in the current UTC day; in-flight usage may not yet be committed.
        plan_daily_limit:
          type: integer
          format: int64
          description: Configured plan limit, including any dynamic plan override.
        overage_multiplier:
          type: number
          format: double
          minimum: 1
          description: Combined global, plan and token multiplier after clamping.
        effective_daily_limit:
          type:
          - integer
          - 'null'
          format: int64
          description: Plan limit multiplied by the overage multiplier and rounded up; null when unlimited.
        credits_remaining:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 0
          description: Effective limit minus recorded usage, clamped to zero; null when unlimited.
        unlimited:
          type: boolean
          description: Whether daily quota enforcement is disabled for this token.
        quota_exhausted:
          type: boolean
          description: True when the limited token has no positive recorded allowance left; false when unlimited.
        recommended_retry_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Stable per-token suggested retry time after reset when exhausted; otherwise null. Does not guarantee token activation.
  responses:
    ServerErrorNoBody:
      description: Internal server error.
  headers:
    WWWAuthenticateBearer:
      description: Bearer challenge describing why auth failed.
      schema:
        type: string
        example: Bearer realm="gribstream", error="invalid_token", error_description="invalid API token"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API token
      description: 'Send your GribStream API token as:


        `Authorization: Bearer YOUR_TOKEN`

        '