ticexplorer-com Rates API

openapi: 3.2.0
info:
  title: TiC Explorer Rates API
  description: '**TiC Explorer** — negotiated health-care prices from **Transparency in Coverage** files (every in-network rate a plan pays each

    billing entity), Original Medicare fee schedules and, as a secondary source, hospitals'' own price files (each hospital''s

    posted rate per payer/plan as it wrote them, mostly facility charges, and its discounted cash price) — with the billing

    semantics needed to use them correctly: allowed vs billed vs patient share, global vs 26/TC, office vs facility rates, hospital outpatient APC

    case rates and packaging, placeholders and percent-of-charges contracts, and per-row provenance.


    **Start with** `GET /v1/guide` (billing mechanics, field dictionary, worked examples) and `GET /v1/workflows`.


    **Auth:** `Authorization: Bearer `. Get a key in the console at https://ticexplorer.com/dashboard/keys (self-hosted:

    `python -m api keys create` or `POST /v1/admin/keys`). The MCP endpoint `https://api.ticexplorer.com/mcp` accepts the same API keys

    or OAuth 2.1 access tokens, e.g. `claude mcp add --transport http ticexplorer https://api.ticexplorer.com/mcp`.


    **Conventions:** list responses are `{"data": [...], "next_cursor": ...}` (pass `cursor`); errors are

    `{"error": {"code", "message", "hint"}}`; every response has `X-Request-Id`, `X-RateLimit-Limit`,

    `X-RateLimit-Remaining`, `X-RateLimit-Reset`. Responses carry `needs` (missing inputs that change the answer) and

    `next_steps`.'
  version: 0.3.0
servers:
- url: /
tags:
- name: Rates
  description: Self-describing negotiated rate rows.
paths:
  /v1/rates:
    post:
      tags:
      - Rates
      summary: Negotiated rates for codes near a place
      description: 'Coverage × codes × providers-or-area → self-describing rate rows + summary. First use of a plan''s rate files

        indexes them just in time (up to `wait_seconds`); later calls are fast.


        **Workflows**


        Workflow `compare-places`, step 3/3 `rates`: Compare what the plan pays different nearby providers for the same service.

        - Purpose: Rows are comparable within the same billing component and place of service; a global rate already includes 26 + TC.

        - Call after: `find_codes`'
      operationId: get_rates
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RatesRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - HTTPBearer: []
  /v1/rates/batch:
    post:
      tags:
      - Rates
      summary: Several rate queries in one call
      description: 'Up to 10 `get_rates` requests (different coverages, areas, entities or code sets) in one call.


        **Workflows**


        Workflow `compare-coverage-routes`, step 2/2 `rates-by-route`: Compare the same services under the person''s plan, Original Medicare and hospital cash prices in one call.

        - Purpose: One request per coverage route (plan, medicare, hospital cash), each with a label.

        - Call after: `find_codes`'
      operationId: get_rates_batch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RatesBatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesBatchResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - HTTPBearer: []
components:
  schemas:
    Area:
      properties:
        zip:
          type: string
          title: Zip
          description: 5-digit ZIP the person is near.
          examples:
          - '98052'
        miles:
          type: number
          maximum: 100.0
          minimum: 1.0
          title: Miles
          description: Search radius in miles.
          default: 15
      type: object
      required:
      - zip
      title: Area
    ErrorBody:
      properties:
        code:
          type: string
          title: Code
          description: Stable machine-readable error code, e.g. plan_not_found, invalid_zip, unauthorized.
        message:
          type: string
          title: Message
        hint:
          type: string
          title: Hint
          default: ''
      type: object
      required:
      - code
      - message
      title: ErrorBody
    Price:
      properties:
        kind:
          type: string
          title: Kind
          description: negotiated | fee_schedule | derived | per_diem | percent_of_charges | placeholder | algorithm ...
        amount:
          anyOf:
          - type: number
          - type: 'null'
          title: Amount
          description: Allowed dollars per unit; null when not a dollar price.
        percent:
          anyOf:
          - type: number
          - type: 'null'
          title: Percent
        unit:
          type: string
          title: Unit
          description: per_service | per_day | per_apc_case | percent_of_billed_charges | none
        is_dollar_price:
          type: boolean
          title: Is Dollar Price
      additionalProperties: true
      type: object
      required:
      - kind
      - unit
      - is_dollar_price
      title: Price
    RatesRequest:
      properties:
        coverage:
          $ref: '#/components/schemas/Coverage'
        codes:
          items:
            type: string
          type: array
          maxItems: 10
          minItems: 1
          title: Codes
          description: Billing codes from find_codes (CPT/HCPCS, or an APC number for hospital case rates).
        providers:
          anyOf:
          - $ref: '#/components/schemas/Providers'
          - type: 'null'
          description: Restrict to these billing entities / locations.
        area:
          $ref: '#/components/schemas/Area'
        limit:
          type: integer
          maximum: 500.0
          minimum: 1.0
          title: Limit
          default: 50
        cursor:
          type: integer
          minimum: 0.0
          title: Cursor
          description: Pagination cursor from next_cursor.
          default: 0
        wait_seconds:
          type: integer
          maximum: 240.0
          minimum: 5.0
          title: Wait Seconds
          description: How long to wait for rate files being indexed for the first time.
          default: 60
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
          description: Echoed back in batch results.
      type: object
      required:
      - coverage
      - codes
      - area
      title: RatesRequest
    RatesBatchItem:
      properties:
        index:
          type: integer
          title: Index
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        ok:
          type: boolean
          title: Ok
        data:
          anyOf:
          - items:
              $ref: '#/components/schemas/RateRow'
            type: array
          - type: 'null'
          title: Data
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorBody'
          - type: 'null'
      additionalProperties: true
      type: object
      required:
      - index
      - ok
      title: RatesBatchItem
    Need:
      properties:
        field:
          type: string
          title: Field
          description: The missing input or condition, e.g. which_insurer, place_of_service, wait.
        why:
          type: string
          title: Why
          description: Why it changes the answer and what to do.
      additionalProperties: true
      type: object
      required:
      - field
      - why
      title: Need
    RatesResult:
      properties:
        data:
          items:
            $ref: '#/components/schemas/RateRow'
          type: array
          title: Data
        next_cursor:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Cursor
        total_rows:
          type: integer
          title: Total Rows
        summary:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Summary
          default: []
        cheapest_sites:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Cheapest Sites
          description: 'Per code x component: the cheapest real places to go (site, address, miles to the site, TIN, amount, quality).'
          default: []
        hospital_file_check:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Hospital File Check
          description: How many hospital rows were compared with the hospitals' own price files, and how many agree.
        medicare_reference:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Medicare Reference
          description: 'coverage medicare: per code OPPS wage-adjusted APC, estimated lab fee, ASP drug limit.'
        coverage:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Coverage
        needs:
          items:
            $ref: '#/components/schemas/Need'
          type: array
          title: Needs
          default: []
        next_steps:
          items:
            type: string
          type: array
          title: Next Steps
          default: []
      additionalProperties: true
      type: object
      required:
      - data
      - total_rows
      title: RatesResult
    RatesBatchRequest:
      properties:
        requests:
          items:
            $ref: '#/components/schemas/RatesRequest'
          type: array
          maxItems: 10
          minItems: 1
          title: Requests
      type: object
      required:
      - requests
      title: RatesBatchRequest
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: Error
    RatesBatchResult:
      properties:
        data:
          items:
            $ref: '#/components/schemas/RatesBatchItem'
          type: array
          title: Data
        next_cursor:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Cursor
        next_steps:
          items:
            type: string
          type: array
          title: Next Steps
          default: []
      additionalProperties: true
      type: object
      required:
      - data
      title: RatesBatchResult
    Coverage:
      properties:
        type:
          type: string
          enum:
          - plan
          - medicare
          - hospital
          title: Type
          description: 'plan = a plan from find_plan (insurer rate files); medicare = Original Medicare fee schedule; hospital = hospitals'' own price files (Medicare Advantage, Medicaid, cash/self-pay): each hospital''s posted rate per payer/plan as the hospital wrote it (not necessarily the person''s plan), mostly facility charges; cash = its discounted cash price, not the gross charge. price_claim does not accept hospital.'
          default: plan
        plan_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Id
          description: Required when type = plan; from find_plan.
        hospital_coverage:
          anyOf:
          - type: string
          - type: 'null'
          title: Hospital Coverage
          description: 'For type = hospital: medicare_advantage | medicaid | cash | a payer name.'
      type: object
      title: Coverage
    Billing:
      properties:
        billing_class:
          anyOf:
          - type: string
          - type: 'null'
          title: Billing Class
          description: professional (clinician claim) | institutional (facility claim)
        setting:
          anyOf:
          - type: string
          - type: 'null'
          title: Setting
        modifiers:
          items:
            type: string
          type: array
          title: Modifiers
          default: []
        component:
          type: string
          title: Component
          description: global | professional_component | technical_component | professional | facility | drug
        applies_when:
          type: string
          title: Applies When
        place_of_service:
          type: string
          title: Place Of Service
          description: non_facility | facility | mixed | unspecified
      additionalProperties: true
      type: object
      required:
      - component
      - applies_when
      - place_of_service
      title: Billing
    Providers:
      properties:
        tins:
          items:
            type: string
          type: array
          title: Tins
          description: Billing entity tax IDs (from find_providers), e.g. 84-1179794.
        npis:
          items:
            type: string
          type: array
          title: Npis
          description: NPIs of locations or clinicians.
        names:
          items:
            type: string
          type: array
          title: Names
          description: Substring match on billing entity / location names.
      type: object
      title: Providers
    RateRow:
      properties:
        code:
          type: string
          title: Code
        code_type:
          type: string
          title: Code Type
        billing_entity:
          additionalProperties: true
          type: object
          title: Billing Entity
          description: '{tin, name, is_hospital}: prices belong to billing entities.'
        location:
          additionalProperties: true
          type: object
          title: Location
        price:
          $ref: '#/components/schemas/Price'
        billing:
          $ref: '#/components/schemas/Billing'
        hospital_outpatient:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Hospital Outpatient
          description: APC, status indicator, packaging (institutional rows).
        benchmark:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Benchmark
          description: Medicare amount for the same service/setting + percent_of_medicare.
        flags:
          items:
            type: string
          type: array
          title: Flags
          default: []
        quality:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Quality
          description: '{score 1-5, reason}: 5 corroborated by the hospital''s own file, 4 consistent with Medicare band, 3 unchecked / not corroborated, 2 unusual, 1 not a usable dollar price (guide://fields).'
        hospital_file_rate:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Hospital File Rate
          description: 'Hospital rows: the same hospital''s own price file for this payer and code (amount, plan_as_written, agreement, difference_percent).'
        evidence:
          additionalProperties: true
          type: object
          title: Evidence
        provenance:
          additionalProperties: true
          type: object
          title: Provenance
          description: payer, plan, files, insurer_date_label vs retrieved_at, future_dated_label.
      additionalProperties: true
      type: object
      required:
      - code
      - code_type
      - billing_entity
      - location
      - price
      - billing
      - evidence
      - provenance
      title: RateRow
  securitySchemes:
    HTTPBearer:
      type: http
      description: API key (tic_live_...) or OAuth access token.
      scheme: bearer
    oauth2:
      type: oauth2
      description: OAuth 2.1 (authorization code + PKCE) for MCP clients; see /.well-known/oauth-authorization-server
      flows:
        authorizationCode:
          authorizationUrl: /authorize
          tokenUrl: /token
          scopes:
            read: Query prices
x-workflow-renderer: builtin