ticexplorer-com Guide API

openapi: 3.2.0
info:
  title: TiC Explorer Guide 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: guide
  description: Domain guide and Arazzo workflows (no auth).
paths:
  /v1/guide:
    get:
      tags:
      - guide
      summary: Guide topics
      operationId: guide_index
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/guide/{topic}:
    get:
      tags:
      - guide
      summary: One guide topic (markdown)
      operationId: guide_topic
      parameters:
      - name: topic
        in: path
        required: true
        schema:
          type: string
          title: Topic
      responses:
        '200':
          description: Successful Response
          content:
            text/plain:
              schema:
                type: string
        '404':
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/workflows:
    get:
      tags:
      - guide
      summary: Arazzo 1.0 workflows (JSON)
      operationId: list_workflows
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/workflows/{workflow_id}:
    get:
      tags:
      - guide
      summary: One workflow as agent-readable markdown
      operationId: get_workflow
      parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          title: Workflow Id
      responses:
        '200':
          description: Successful Response
          content:
            text/plain:
              schema:
                type: string
        '404':
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Error'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: Error
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  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