thinair-co Account API

openapi: 3.2.0
info:
  title: ThinAir Geo Account API
  version: 1.0.0
  description: '## Overview


    Geocoding, autocomplete, structured search, place IDs, intersections, routing, distance matrix, isochrones, map matching, traffic, weather, and POI search — one API. REST and MCP consume the same ThinAir Geo service layer; this spec describes the REST surface.


    ## Base URL & authentication


    All endpoints live under `https://geo.thinair.co`. Authenticate with a bearer API key:


    ```bash

    curl "https://geo.thinair.co/v1/geocode?text=Pike Place Market Seattle" \

    -H "Authorization: Bearer ta_geo_…"

    ```


    ## Observability


    Every REST response carries a correlation pair (`X-Request-Id` / `X-Trace-Id`), a cache status (`X-Cache: HIT | HIT-EDGE | STALE | MISS | BYPASS`), and a per-stage timing family (`X-Auth-Ms`, `X-Quota-Ms`, `X-Upstream-Ms`, `X-Worker-Ms`, `X-Edge-Ms`, `X-Total-Ms`) — see components.headers for the full surface. Edge-cached lookups answer in single-digit milliseconds at the edge (verifiable via `X-Edge-Ms`); cold geocoding runs through the regional engine.


    ## Quota


    The daily-quota debit is write-behind on all API-key plans, so `X-Quota-Used` / `X-Quota-Remaining` are eventually consistent (typically within ~30 seconds); `GET /v1/quota` is the authoritative synchronous count.


    ## Enterprise access


    `https://geo.thinair.co` is the canonical public API and MCP surface. Azure API Management (APIM) is available as an enterprise access layer — private deployments, custom quota/SLA, VNET/private-link connectivity, subscription keys, and customer-side governance. APIM is an enterprise access layer. It does not own product behavior. All product behavior lives in the shared ThinAir Geo service layer consumed by REST, MCP, and APIM. APIM calls the same service layer (no separate business logic), preserves request/trace ids and ThinAir response shapes, and may add enterprise auth, quota, IP policy, logging, and private networking. Public documentation keeps `https://geo.thinair.co` as the canonical base URL; enterprise base URLs are issued per customer.'
servers:
- url: https://geo.thinair.co
security:
- bearerAuth: []
tags:
- name: Account
paths:
  /v1/quota:
    get:
      summary: Get caller's current quota state
      description: Returns the caller's plan, daily usage, remaining queries, and upgrade options. **Free to call** — never debits quota and never returns 429 (a quota-exhausted user must still be able to discover their state).
      tags:
      - Account
      responses:
        '200':
          description: Caller's quota snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaResponse'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-Trace-Id:
              $ref: '#/components/headers/X-Trace-Id'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
            X-Cache-Hit:
              $ref: '#/components/headers/X-Cache-Hit'
            X-Cache-Tier:
              $ref: '#/components/headers/X-Cache-Tier'
            X-Edge-Ms:
              $ref: '#/components/headers/X-Edge-Ms'
            X-Upstream-Ms:
              $ref: '#/components/headers/X-Upstream-Ms'
            X-Worker-Ms:
              $ref: '#/components/headers/X-Worker-Ms'
            X-Total-Ms:
              $ref: '#/components/headers/X-Total-Ms'
            X-Auth-Ms:
              $ref: '#/components/headers/X-Auth-Ms'
            X-Quota-Ms:
              $ref: '#/components/headers/X-Quota-Ms'
            X-Quota-Cost:
              $ref: '#/components/headers/X-Quota-Cost'
            X-Quota-Used:
              $ref: '#/components/headers/X-Quota-Used'
            X-Quota-Remaining:
              $ref: '#/components/headers/X-Quota-Remaining'
            X-Quota-Reset:
              $ref: '#/components/headers/X-Quota-Reset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-Session-Id:
              $ref: '#/components/headers/X-Session-Id'
            X-Edge-Location:
              $ref: '#/components/headers/X-Edge-Location'
            X-Data-Age-S:
              $ref: '#/components/headers/X-Data-Age-S'
        '401':
          description: Authentication required or failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getV1Quota
      x-operation-id-source: derived
components:
  headers:
    X-Quota-Cost:
      description: Capability units this call debited.
      schema:
        type: string
    X-Worker-Ms:
      description: 'Worker-side overhead: total minus upstream (ms). Decomposes into X-Auth-Ms + X-Quota-Ms + unattributed residue (serialization, telemetry, routing).'
      schema:
        type: string
    X-Edge-Location:
      description: Edge location (IATA airport code) that served the request. Omitted when unavailable.
      schema:
        type: string
    X-RateLimit-Limit:
      description: Plan cap proxy (-1 = unlimited).
      schema:
        type: string
    X-Session-Id:
      description: Session correlation id grouping requests issued under one client session.
      schema:
        type: string
    X-Quota-Reset:
      description: ISO-8601 instant the daily counter rolls over.
      schema:
        type: string
    X-Cache-Hit:
      description: Legacy boolean cache signal (true|false). Prefer X-Cache.
      schema:
        type: string
    X-Trace-Id:
      description: Alias of X-Request-Id for tracing tooling that auto-detects the Trace-Id spelling.
      schema:
        type: string
    X-Data-Age-S:
      description: Age in seconds of the underlying data snapshot backing the response (e.g. a traffic observation). Only present on endpoints where data age is meaningful.
      schema:
        type: string
    X-Total-Ms:
      description: Equal to X-Edge-Ms; kept distinct per spec §6.
      schema:
        type: string
    X-Quota-Remaining:
      description: Daily limit minus used (-1 = unlimited). Eventually consistent (see X-Quota-Used); GET /v1/quota is authoritative.
      schema:
        type: string
    X-Quota-Ms:
      description: Synchronous quota work on the request path (ms). All API-key plans use a write-behind debit, so this reflects only the fast synchronous exhausted-flag check. The demo (Try-It) identity keeps the synchronous pre-flight peek + post-success debit (QuotaCounter round-trips).
      schema:
        type: string
    X-Edge-Ms:
      description: Total wall time the worker held the request (ms).
      schema:
        type: string
    X-Quota-Used:
      description: 'Units consumed in the current daily period. The debit is write-behind on all API-key plans: this value is eventually consistent (typically within ~30 seconds); GET /v1/quota is the authoritative synchronous count.'
      schema:
        type: string
    X-RateLimit-Remaining:
      description: Remaining headroom (-1 = unlimited).
      schema:
        type: string
    X-Auth-Ms:
      description: API-key validation time (ms). Present only on the ta_* api-key and demo-token paths; OAuth-JWT validation happens inside the auth library and is not measurable.
      schema:
        type: string
    X-Request-Id:
      description: Edge-generated request correlation id (req_*).
      schema:
        type: string
    X-Cache:
      description: 'Cache status: HIT (served from the cache without an upstream call), HIT-EDGE (served from the edge tier, no durable-store round-trip), STALE (served past its soft TTL while a background refresh runs), MISS (cacheable, went upstream), BYPASS (endpoint has no cache).'
      schema:
        type: string
        enum:
        - HIT
        - HIT-EDGE
        - STALE
        - MISS
        - BYPASS
    X-Cache-Tier:
      description: 'Serving cache tier, when reported: edge (edge tier), l0 (in-region cache), or kv (durable edge store).'
      schema:
        type: string
        enum:
        - edge
        - l0
        - kv
    X-Upstream-Ms:
      description: Wall time spent in engine round-trips (ms). Omitted on cache hits (no upstream call).
      schema:
        type: string
  schemas:
    QuotaResponse:
      type: object
      properties:
        schema_version:
          type: string
          enum:
          - v1
        mcp:
          type: object
          properties:
            plan:
              type: string
              example: free
            used_today:
              type: integer
              minimum: 0
            daily_limit:
              anyOf:
              - type: integer
                minimum: 0
              - type: string
                enum:
                - unlimited
            remaining_today:
              anyOf:
              - type: integer
                minimum: 0
              - type: string
                enum:
                - unlimited
            monthly_limit:
              anyOf:
              - type: integer
                minimum: 0
              - type: string
                enum:
                - unlimited
            price_per_month:
              type: string
              example: $0
            suggested_upgrade:
              type:
              - string
              - 'null'
            upgrade_url:
              type:
              - string
              - 'null'
            reset_at:
              type: string
              example: 00:00 UTC daily
          required:
          - plan
          - used_today
          - daily_limit
          - remaining_today
          - monthly_limit
          - price_per_month
          - suggested_upgrade
          - upgrade_url
          - reset_at
      required:
      - schema_version
      - mcp
      description: Caller's current quota — plan, daily usage, remaining, upgrade options. Mirrors the MCP `quota` tool response shape so REST and MCP stay symmetric.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
          description: Stable internal_code; see /docs/errors
        request_id:
          type: string
        instance:
          type: string
        retry_after_ms:
          type: integer
        upgrade_url:
          type: string
          description: Present on 429 (quota exceeded) and on 401 TRIAL_EXPIRED. Preselects the recommended plan and, when the caller's tenant is known, carries a short-lived token that upgrades the API key you are already using — no key swap and no config change after payment.
        suggested_upgrade:
          type:
          - string
          - 'null'
          description: Recommended next plan, or null on the top self-serve tier. 429 only.
        upgrade_cta:
          type: string
          description: One-line upgrade prompt. 429 only.
        upgrade_plans:
          type: array
          items:
            $ref: '#/components/schemas/UpgradePlan'
          description: Full self-serve plan menu. 429 only.
        next_step:
          type: string
          description: Prose instruction naming the same URL as upgrade_url. 429 only.
        usage:
          type: object
          properties:
            plan:
              type: string
            used:
              type: number
            limit:
              type: number
            period:
              type: string
            reset:
              type: string
              description: ISO 8601 instant the counter rolls over.
          required:
          - plan
          description: Where the cap stands. 429 only; counters are omitted when the denial has none.
        expired_at:
          type: string
          description: ISO 8601 instant the key stopped authenticating. TRIAL_EXPIRED only.
        plan:
          type: string
          description: Plan the expired key carried. TRIAL_EXPIRED only.
        quota:
          type: object
          properties:
            daily:
              type: number
            period:
              type: string
          required:
          - daily
          - period
          description: Daily allowance the expired key had; -1 = unlimited. TRIAL_EXPIRED only.
      required:
      - type
      - title
      - status
      - detail
      - code
      - request_id
      - instance
      description: RFC 7807 problem-details with ThinAir extensions (code, request_id, retry_after_ms). A 429 additionally carries upgrade_url, suggested_upgrade, upgrade_cta, upgrade_plans, next_step and usage; a 401 TRIAL_EXPIRED carries upgrade_url, expired_at, plan and quota.
    UpgradePlan:
      type: object
      properties:
        name:
          type: string
        price:
          type: string
          description: Display price, e.g. "$29/mo" or "custom".
        quota:
          type: string
          description: Display allowance, e.g. "10,000/day".
        note:
          type: string
        upgrade_url:
          type: string
          description: Checkout link for this specific plan. Carries the same plan preselect, in-place upgrade token and src attribution as the top-level upgrade_url.
      required:
      - name
      - price
      - quota
      - upgrade_url
      description: One self-serve plan offered on a 429.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer