Samplence API Docs
LLM-readyAPI base
Overview

Authenticate, build the case file, then start research explicitly.

QuickstartReference
Flow

Chat first, research second

A case starts as anamnesis capture. The assistant closes critical gaps first, then marks the case ready. Research never auto-starts from chat writes.

Auth

Use a bearer API key

Every REST and MCP request uses the same bearer API key.

Ping

Check the key

cURL
export API_KEY="sk_live_or_test_api_key"

curl https://api.185.237.14.76.nip.io/v1/ping \
  -H "Authorization: Bearer $API_KEY"
Billing

Check credits before you write

$1 buys 10 credits. Chat turns cost 1 credit per successful turn. New research runs cost 30 credits upfront ($3) and failed runs are refunded automatically. Exact matching completed reports can return an existing result immediately without charging again. Research is always explicit: use the console button or call /research-runs yourself.

cURL
curl https://api.185.237.14.76.nip.io/v1/billing \
  -H "Authorization: Bearer $API_KEY"
Top-up

Create a hosted checkout session

Admin keys can request a Stripe-hosted top-up URL directly over REST.

cURL
curl https://api.185.237.14.76.nip.io/v1/billing/top-ups \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "usdQuantity": 5,
    "successUrl": "https://client.example.com/billing/success",
    "cancelUrl": "https://client.example.com/billing/cancel"
  }'
Keys

Create or rotate machine keys over REST

After initial bootstrap, external users do not need the console UI to issue automation keys.

cURL
curl https://api.185.237.14.76.nip.io/v1/api-keys \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Automation key",
    "scopes": ["read", "write"]
  }'
Cases

Start a case, then read the canonical case state

Use case reads to inspect gapAssessment.readinessStatus. When it flips to ready, start research explicitly from the console button, REST, or MCP.

Create case
export API_KEY="sk_live_or_test_api_key"

curl https://api.185.237.14.76.nip.io/v1/chat/threads \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Idea: AI copilot for insurance brokers in Southeast Asia. It drafts proposals, compares policy options, and speeds up manual broker workflows."
  }'
Read case
curl https://api.185.237.14.76.nip.io/v1/chat/threads/<thread_id> \
  -H "Authorization: Bearer $API_KEY"
MCP

Connect an MCP client

The same API key also works on /mcp. MCP exposes the send_message and start_research tools plus the /billing, /chat/threads, and /chat/threads/{threadId} resources.

send_message updates the case only. It never auto-starts research; call start_research when the case is ready.

Config
{
  "mcpServers": {
    "startup-research": {
      "type": "streamable-http",
      "url": "https://api.185.237.14.76.nip.io/mcp",
      "headers": {
        "Authorization": "Bearer $API_KEY"
      }
    }
  }
}