Samplence logoSamplence API Docs
LLM-readyAPI base
Reference

Only the contract for the explicit chat-to-research flow.

Discovery

Agent-ready well-known endpoints

https://185.237.14.76.nip.io/.well-known/api-catalogRFC 9727 API catalog for the REST API and MCP endpoint
https://185.237.14.76.nip.io/.well-known/openapi.jsonMachine-readable OpenAPI description for the public REST API
https://185.237.14.76.nip.io/.well-known/oauth-authorization-serverRFC 8414 authorization server metadata mirroring the Clerk issuer used for workspace OAuth
https://185.237.14.76.nip.io/.well-known/openid-configurationOpenID Provider configuration mirroring the Clerk issuer used for workspace OAuth
https://185.237.14.76.nip.io/.well-known/oauth-protected-resource/api/chatRFC 9728 protected resource metadata for the Clerk-backed workspace chat API
https://185.237.14.76.nip.io/.well-known/mcp/server-card.jsonMCP server card pointing clients at the streamable HTTP MCP transport
https://185.237.14.76.nip.io/.well-known/agent-skills/index.jsonAgent skills discovery index with Samplence-specific REST and MCP skills
Workspace API

Clerk-protected chat routes

GET https://185.237.14.76.nip.io/api/chat/threadsList saved threads for the active workspace
POST https://185.237.14.76.nip.io/api/chat/threadsCreate a workspace thread and queue the first assistant turn
GET https://185.237.14.76.nip.io/api/chat/threads/:threadIdRead one workspace thread
POST https://185.237.14.76.nip.io/api/chat/threads/:threadId/messagesAppend a message to an existing workspace thread
POST https://185.237.14.76.nip.io/api/chat/threads/:threadId/research-runsStart or reuse a workspace research run

Unauthenticated /api/chat/* responses advertise protected-resource discovery with a WWW-Authenticate header that points clients to path-derived metadata under https://185.237.14.76.nip.io/.well-known/oauth-protected-resource/.... The root workspace chat surface is published at https://185.237.14.76.nip.io/.well-known/oauth-protected-resource/api/chat. The site also mirrors the Clerk issuer metadata at https://185.237.14.76.nip.io/.well-known/oauth-authorization-server and https://185.237.14.76.nip.io/.well-known/openid-configuration for clients that start from generic authorization-server or OIDC discovery. This workspace OAuth path is intended for delegated or manually provisioned integrations, not self-serve public agent onboarding.

Endpoints

Startup research API

GET /healthHealth check
GET /v1/pingAuth check
GET /v1/billingCurrent prepaid credit balance and write pricing
POST /v1/billing/top-upsCreate a Stripe-hosted top-up checkout session
GET /v1/api-keysList API keys for the current workspace
POST /v1/api-keysCreate a new API key
POST /v1/api-keys/:apiKeyId/rotateRotate an existing API key and return the new secret once
POST /v1/api-keys/:apiKeyId/revokeRevoke an API key
GET /v1/chat/threadsList saved case summaries for the current workspace
GET /v1/chat/threads/:threadIdRead one case, including messages, reports, and research runs
POST /v1/chat/threadsCreate a new case and return the first assistant reply. Never auto-starts research.
POST /v1/chat/threads/:threadId/messagesContinue an existing case. Never auto-starts research.
POST /v1/chat/threads/:threadId/research-runsExplicitly queue a research run for the current anamnesis snapshot
POST /mcpRemote streamable HTTP MCP endpoint
Access

API key scopes

threads_readRead safe case summaries and safe case detail over REST and MCP
threads_writeCreate new cases and append user messages. Chat writes still never auto-start research.
research_writeExplicitly queue research runs for an existing case
billing_readRead current credit balance, pricing, and top-up options
billing_writeCreate Stripe-hosted top-up sessions
api_keys_adminCreate, rotate, revoke, and list API keys
Billing

GET /v1/billing

Pricing is prepaid: $1 buys 10 credits. Chat turns cost 1 credit per successful turn by default, and research runs cost 30 credits upfront. Failed research runs are refunded automatically.

JSON
{
  "chatTurnBillingMode": "fixed",
  "chatTurnMaxReserveCredits": 1,
  "creditBalance": 240,
  "currency": "usd",
  "pricePer100CreditsUsd": 10,
  "researchRunBillingMode": "fixed",
  "researchRunPriceCredits": 30,
  "topUpEndpoint": "https://api.185.237.14.76.nip.io/v1/billing/top-ups",
  "topUpOptions": [
    {
      "creditQuantity": 50,
      "usdQuantity": 5
    },
    {
      "creditQuantity": 100,
      "usdQuantity": 10
    },
    {
      "creditQuantity": 150,
      "usdQuantity": 15
    }
  ],
  "topUpScope": "billing_write"
}
Create top-up session
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

/v1/api-keys

Use an api_keys_admin key to mint, rotate, and revoke machine credentials without using the console UI. New keys must declare an explicit scopes array and should be limited to the minimum access the agent needs.

Create key
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": ["threads_read", "threads_write", "research_write", "billing_read"]
  }'
Smoke response

GET /v1/ping

JSON
{
  "grantedScopes": [
    "threads_read",
    "threads_write",
    "research_write",
    "billing_read"
  ],
  "ok": true,
  "supportedRouteGroups": ["mcp", "billing", "threads"]
}
Start

POST /v1/chat/threads

Returns 202 Accepted with a pending assistant placeholder, the updated safe case snapshot, and the latest anamnesis and gap assessment. This route never auto-starts research, even if the case is already ready.

cURL
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."
  }'
202 JSON
{
  "assistantMessage": {
    "content": "Thinking...",
    "createdAt": "2026-04-19T10:00:01.000Z",
    "id": "msg_...",
    "role": "assistant",
    "status": "pending"
  },
  "anamnesis": {
    "ideaSummary": "AI copilot for insurance brokers"
  },
  "gapAssessment": {
    "readinessStatus": "ready"
  },
  "reportStaleness": {
    "isStale": false
  },
  "thread": {
    "id": "thread_...",
    "latestCompletedReportId": null,
    "messageCount": 2,
    "reports": []
  },
  "userMessage": {
    "content": "Idea: AI copilot for insurance brokers",
    "createdAt": "2026-04-19T10:00:00.000Z",
    "id": "msg_...",
    "role": "user",
    "status": "complete"
  }
}

If the workspace has no credits left, the same route returns 402 Payment Required.

402 JSON
{
  "error": "Insufficient credits",
  "creditBalance": 0,
  "requiredCredits": 1
}
Continue

POST /v1/chat/threads/:threadId/messages

Also returns 202 Accepted with the pending assistant placeholder and the refreshed safe case snapshot. Use the refreshed case state to decide whether to start research explicitly.

cURL
curl https://api.185.237.14.76.nip.io/v1/chat/threads/<thread_id>/messages \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Now compare it against manual broker workflow and legacy SaaS competitors."
  }'
Read

GET /v1/chat/threads/:threadId

Read the canonical safe case state, including anamnesis, gap assessment, safe message content, report summaries, and research run status.

cURL
curl https://api.185.237.14.76.nip.io/v1/chat/threads/<thread_id> \
  -H "Authorization: Bearer $API_KEY"

Public case reads intentionally exclude raw report JSON, full report bodies, provider/model metadata, token accounting, request IDs, and other internal execution data. Report entries expose only safe summary fields such as id, runId, timestamps, and summaryText.

Research

POST /v1/chat/threads/:threadId/research-runs

Starts research for the current anamnesis snapshot. New work returns 202 Accepted; exact matching completed reports can return 200 OK with the reused result immediately instead of queueing a new paid run. In the console UI, this is the same explicit action exposed as the Start research button under the ready-state assistant reply.

cURL
curl https://api.185.237.14.76.nip.io/v1/chat/threads/<thread_id>/research-runs \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "force": false
  }'
202 JSON
{
  "anamnesisSnapshot": {
    "ideaSummary": "AI copilot for insurance brokers"
  },
  "gapAssessment": {
    "readinessStatus": "ready"
  },
  "reportStaleness": {
    "isStale": false
  },
  "runId": "run_...",
  "thread": {
    "id": "thread_..."
  }
}
MCP

/mcp

Remote MCP over streamable HTTP with the same bearer API keys. The current server exposes two tools and three read resources. Public deployments should expose this endpoint over HTTPS.

send_messageCreate a case when threadId is omitted, otherwise append to an existing case and return the updated snapshot. Never auto-starts research.
start_researchExplicitly start research for an existing case and either queue a new run or return an exact matching completed report immediately
https://api.185.237.14.76.nip.io/billingResource with the current balance, pricing, and top-up options
https://api.185.237.14.76.nip.io/chat/threadsResource listing safe case summaries for the current workspace
https://api.185.237.14.76.nip.io/chat/threads/{threadId}Resource template for one safe case snapshot with messages, report summaries, anamnesis, and research runs
Generic config
{
  "mcpServers": {
    "startup-research": {
      "type": "streamable-http",
      "url": "https://api.185.237.14.76.nip.io/mcp",
      "headers": {
        "Authorization": "Bearer $API_KEY"
      }
    }
  }
}
TOML config
[mcp_servers.startup-research]
url = "https://api.185.237.14.76.nip.io/mcp"
http_headers = { Authorization = "Bearer sk_live_or_test_api_key" }

MCP does not return synthetic pending handles. send_message returns the updated safe case state immediately and leaves research idle. start_research returns the accepted run metadata plus the refreshed safe case snapshot.

send_message result
{
  "assistantMessage": {
    "content": "Thinking...",
    "id": "msg_...",
    "role": "assistant",
    "status": "pending"
  },
  "gapAssessment": {
    "readinessStatus": "ready"
  },
  "thread": {
    "id": "thread_..."
  },
  "userMessage": {
    "id": "msg_...",
    "role": "user",
    "status": "complete"
  }
}
start_research result
{
  "anamnesisSnapshot": {
    "ideaSummary": "AI copilot for insurance brokers"
  },
  "gapAssessment": {
    "readinessStatus": "ready"
  },
  "runId": "run_...",
  "thread": {
    "id": "thread_..."
  }
}
Tool error
{
  "code": "insufficient_credits",
  "message": "Insufficient credits. Read https://api.185.237.14.76.nip.io/billing for the current balance before retrying."
}