# Samplence API docs

API and MCP docs for Samplence.

## Quickstart
1. Use an existing bearer API key with the scopes you need
2. Run `GET /v1/ping` with that key
3. Run `GET /v1/billing` to inspect credits and top-up options
4. If needed, run `POST /v1/billing/top-ups` with a `billing_write` key to create a Stripe-hosted checkout session
5. Optionally run `POST /v1/api-keys` with an `api_keys_admin` key to mint a machine key
6. Run `POST /v1/chat/threads`
7. Read `GET /v1/chat/threads/:threadId` and inspect `gapAssessment.readinessStatus`
8. Only when the case is ready, run `POST /v1/chat/threads/:threadId/research-runs`

## Public API
- GET /health
- GET /v1/ping
- GET /v1/billing
- POST /v1/billing/top-ups
- GET /v1/api-keys
- POST /v1/api-keys
- POST /v1/api-keys/:apiKeyId/rotate
- POST /v1/api-keys/:apiKeyId/revoke
- GET /v1/chat/threads
- GET /v1/chat/threads/:threadId
- POST /v1/chat/threads
- POST /v1/chat/threads/:threadId/messages
- POST /v1/chat/threads/:threadId/research-runs
- POST /mcp

## Smoke test
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"

## Start a case
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."
  }'

This write endpoint returns 202 Accepted with a pending assistant placeholder and the refreshed safe case snapshot. It never auto-starts research.
$1 buys 10 credits. Chat turns cost 1 credit per successful turn. Research runs cost 30 credits upfront ($3), and failed runs are refunded automatically.

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

Read this resource to inspect the latest messages, anamnesis, gap assessment, reports, and research runs.
When `gapAssessment.readinessStatus` is `ready`, start research explicitly. In the console UI this is the button shown below the ready-state assistant reply.

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

Billing responses include the current balance, chat turn price, research run price, top-up options, and the top-up endpoint.

Create a Stripe-hosted 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"
  }'

## API keys
List or manage keys with an `api_keys_admin` bearer key:
- `GET /v1/api-keys`
- `POST /v1/api-keys`
- `POST /v1/api-keys/:apiKeyId/rotate`
- `POST /v1/api-keys/:apiKeyId/revoke`

If the workspace has no credits left, write routes return:
{
  "error": "Insufficient credits",
  "creditBalance": 0,
  "requiredCredits": 1
}

## MCP
The service also exposes a remote MCP endpoint at `POST /mcp`.

- Transport: streamable HTTP
- Auth: `Authorization: Bearer <API_KEY>`
- Tools:
  - `send_message`
  - `start_research`
- Resources:
  - `https://api.185.237.14.76.nip.io/billing`
  - `https://api.185.237.14.76.nip.io/chat/threads`
  - `https://api.185.237.14.76.nip.io/chat/threads/{threadId}`

`send_message` returns the refreshed case state immediately and never auto-starts research. `start_research` returns the accepted run metadata immediately. Read the case resource for follow-up state.
Billing resources include the current balance and top-up options.
MCP tool errors include a code and message.

## JavaScript example
const response = await fetch("https://api.185.237.14.76.nip.io/v1/chat/threads", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    message: "Idea: AI copilot for insurance brokers in Southeast Asia. It drafts proposals, compares policy options, and speeds up manual broker workflows."
  })
});

const data = await response.json();

const caseResponse = await fetch("https://api.185.237.14.76.nip.io/v1/chat/threads/" + data.thread.id, {
  headers: {
    "Authorization": "Bearer " + apiKey
  }
});

const caseState = await caseResponse.json();