API Documentation

Reference for all available API endpoints.

Endpoints

POST/api/search POST/api/cpt GET/api/npi POST/api/admin/chat GET/api/admin/stores POST/api/admin/stores DELETE/api/admin/stores/[storeName]GET/api/admin/stores/[storeName]/files POST/api/admin/stores/[storeName]/files DELETE/api/admin/stores/[storeName]/files/[documentName]

Search

Core search endpoints for clinical documentation support.

POST

/api/search

Main search endpoint. Streams AI responses with persistent conversation tracking and database storage. Returns a clinical 'Provider Briefing' with CPT codes, prior auth status, documentation checklists, and denial red flags.

Request Body

Name	Type	Required	Description
messages	UIMessage[]	Required	Array of chat messages (role + content)
conversationId	string	Optional	Existing conversation ID for follow-up messages

Response

// Streaming response (text/event-stream)
// Chunks contain:
{
  textDelta: string,        // Streamed text content
  groundingMetadata: {...}, // Document citations
  sources: [...],           // Source documents used
  timing: {                 // Performance metrics
    firstChunkMs: number,
    totalMs: number
  },
  followUpSuggestions: string[]
}

AI Tools (within /api/search)

These tools are automatically invoked by the AI orchestrator during search conversations. They are not called directly by clients.

GET

/api/v1/ptp/{code_a}/{code_b}

NCCI PTP Edit Check — Checks if two CPT/HCPCS codes have a Procedure-to-Procedure bundling edit. Called by the AI when users ask about billing two codes together.

Path Parameters

Name	Type	Required	Description
code_a	string	Required	First CPT/HCPCS code
code_b	string	Required	Second CPT/HCPCS code

Query Parameters

Name	Type	Required	Description
claim_type	string	Optional	'practitioner' (default) or 'facility'

Response

{
  "found": true,
  "code_a": "99213",
  "code_b": "99214",
  "claim_type": "practitioner",
  "column1_code": "99214",
  "column2_code": "99213",
  "effective_date": "20201001",
  "modifier_indicator": 1,
  "modifier_allowed": true,
  "rationale": "Misuse of Column Two code with Column One code"
}

GET

/api/v1/mue/{code}

NCCI MUE Check — Gets the Medically Unlikely Edit limit (maximum reportable units per date of service) for a CPT/HCPCS code. Called by the AI when users ask about unit limits.

Path Parameters

Name	Type	Required	Description
code	string	Required	CPT/HCPCS code to check

Query Parameters

Name	Type	Required	Description
claim_type	string	Optional	'practitioner' (default) or 'facility'
units	number	Optional	Number of units to check against the MUE limit

Response

{
  "found": true,
  "code": "99213",
  "claim_type": "practitioner",
  "mue_value": 1,
  "mai_indicator": "2",
  "units_checked": 4,
  "exceeds_limit": true,
  "rationale": "MUE limit is 1 unit per date of service"
}

POST

/api/cpt

CPT code lookup. Identifies CPT codes from plain-language procedure descriptions and returns a markdown table with codes, descriptions, modifiers, and bundling notes.

Request Body

Name	Type	Required	Description
messages	UIMessage[]	Required	Messages containing procedure descriptions

Response

// Streaming response (text/event-stream)
// Returns markdown table with columns:
// | CPT Code | Description | Typical Use Case | Modifiers | Bundling Notes |

NPI Lookup

Provider identity verification via CMS registry.

GET

/api/npi

Look up providers in the National Provider Identifier (NPI) registry. Proxies requests to the CMS NPI Registry v2.1.

Query Parameters

Name	Type	Required	Description
first_name	string	Optional	Provider first name (at least one name is required)
last_name	string	Optional	Provider last name (at least one name is required)

Response

{
  "result_count": 5,
  "results": [
    {
      "number": 1234567890,
      "basic": {
        "first_name": "John",
        "last_name": "Smith",
        "credential": "MD",
        "status": "A"
      },
      "addresses": [...],
      "taxonomies": [...]
    }
  ]
}

Errors

Status	Description
400	Missing both first_name and last_name

Admin

Admin-only endpoints for chat and file search store management.

POST

/api/admin/chat

AI chat endpoint for payer policy analysis. Streams responses from Gemini using file search on a specific or default store.

Request Body

Name	Type	Required	Description
messages	UIMessage[]	Required	Array of chat messages (role + content)
storeName	string	Optional	Specific file search store name to query against

Response

// Streaming response (text/event-stream)
// Chunks contain:
{
  textDelta: string,
  groundingMetadata: {...},
  sources: [...],
  timing: { firstChunkMs, totalMs, tokenUsage }
}

File Search Stores

Manage file search stores used for RAG-based document retrieval.

GET

/api/admin/stores

List all file search stores in the project.

Response

{
  "stores": [
    {
      "name": "fileSearchStores/abc123",
      "displayName": "Policy Documents",
      "createTime": "2024-01-01T00:00:00Z",
      "updateTime": "2024-01-01T00:00:00Z"
    }
  ]
}

POST

/api/admin/stores

Create a new file search store.

Request Body

Name	Type	Required	Description
displayName	string	Required	Human-readable name (1-100 characters)

Response

{
  "store": {
    "name": "fileSearchStores/abc123",
    "displayName": "Policy Documents",
    "createTime": "2024-01-01T00:00:00Z",
    "updateTime": "2024-01-01T00:00:00Z"
  }
}

DELETE

/api/admin/stores/[storeName]

Delete a file search store and all its documents. Uses force deletion.

Path Parameters

Name	Type	Required	Description
storeName	string	Required	File search store identifier

Response

{ "success": true }

Store Documents

Manage documents within file search stores.

GET

/api/admin/stores/[storeName]/files

List documents in a specific file search store with pagination.

Path Parameters

Name	Type	Required	Description
storeName	string	Required	File search store identifier

Query Parameters

Name	Type	Required	Description
pageSize	number	Optional	Documents per page (default: 10)
pageToken	string	Optional	Pagination token for next page

Response

{
  "documents": [
    {
      "name": "fileSearchStores/.../documents/...",
      "displayName": "Policy_Document.pdf",
      "state": "STATE_ACTIVE",
      "sizeBytes": "1048576",
      "mimeType": "application/pdf",
      "publicUrl": "https://..."
    }
  ],
  "nextPageToken": "...",
  "totalCount": 42
}

POST

/api/admin/stores/[storeName]/files

Upload a document to a file search store and public S3 bucket. Accepts multipart/form-data with a max file size of 50MB.

Path Parameters

Name	Type	Required	Description
storeName	string	Required	Target file search store

Request Body (multipart/form-data)

Name	Type	Required	Description
file	File	Required	Document file to upload (max 50MB)

Response

{
  "document": {
    "name": "fileSearchStores/.../documents/...",
    "displayName": "Policy_Document_Encoded_Name"
  },
  "citation": {
    "key": "abc123",
    "s3Path": "stores/storeId/abc123.pdf",
    "publicUrl": "https://..."
  }
}

DELETE

/api/admin/stores/[storeName]/files/[documentName]

Delete a specific document from a file search store.

Path Parameters

Name	Type	Required	Description
storeName	string	Required	File search store identifier
documentName	string	Required	Document identifier to delete

Response

{ "success": true }