ticexplorer-com Codes API

openapi: 3.2.0
info:
  title: TiC Explorer Codes 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: Codes
  description: Services in words → billing codes + code facts.
paths:
  /v1/codes:
    get:
      tags:
      - Codes
      summary: Find billing codes for a service
      operationId: find_codes
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          description: Service in plain words, or one or more codes
          examples:
          - chest x-ray
          title: Q
        description: Service in plain words, or one or more codes
      - name: zip
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: ZIP for locality-adjusted Medicare fees
          title: Zip
        description: ZIP for locality-adjusted Medicare fees
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 25
          minimum: 1
          default: 10
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodesResult'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Too Many Requests
      description: '**Workflows**


        Workflow `estimate-visit-cost`, step 3/4 `find-codes`: Estimate what a visit will cost a person before care, under their plan, at a specific place.

        - Purpose: Candidate codes for each expected service; `clarify` names details that change the code.

        - Call after: `find_providers`

        - Next: `price_claim`


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

        - Call after: `find_plan`

        - Next: `get_rates`


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

        - Purpose: Confirms the codes and returns their facts (hospital status indicator, Medicare fee).

        - Next: `get_rates_batch`


        Workflow `market-analysis`, step 1/4 `find-codes`: Aggregate rate statistics for services across insurers and all providers in an area (benchmarking, research, negotiation prep, exports).

        - Purpose: Codes for each service, from the code dictionary.

        - Next: `estimate_market_analysis`'
components:
  schemas:
    CodesResult:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Code'
          type: array
          title: Data
        next_cursor:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Cursor
        setting:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Setting
          description: 'Where care happens, when the words name it (urgent care, ER, telehealth, hospital outpatient, ASC, home, office): id, name, CMS place of service `pos` (+ `pos_options`), `note` on how that setting bills, `visit_codes`.'
        clarify:
          items:
            type: string
          type: array
          title: Clarify
          default: []
        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
      title: CodesResult
    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
    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
    CodeFacts:
      properties:
        hospital_outpatient:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Hospital Outpatient
          description: OPPS status indicator, APC, packaging rule.
        medicare_physician_fee:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Medicare Physician Fee
        medicare_clinical_lab_fee:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Medicare Clinical Lab Fee
          description: 'Lab tests: Medicare lab fee (ESTIMATED; the CMS CLFS file is behind the AMA license).'
        medicare_drug_payment_limit:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Medicare Drug Payment Limit
          description: 'Part B drugs: ASP payment limit per billing unit.'
        medicare_only_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Medicare Only Code
        timed_units:
          anyOf:
          - type: string
          - type: 'null'
          title: Timed Units
        add_on_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Add On Code
      additionalProperties: true
      type: object
      title: CodeFacts
    Code:
      properties:
        code_type:
          type: string
          title: Code Type
        code:
          type: string
          title: Code
        plain_name:
          type: string
          title: Plain Name
        official_description:
          type: string
          title: Official Description
          default: ''
        category:
          type: string
          title: Category
          default: ''
        facts:
          $ref: '#/components/schemas/CodeFacts'
      additionalProperties: true
      type: object
      required:
      - code_type
      - code
      - plain_name
      - facts
      title: Code
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: Error
  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