Samplence logoSamplence API Docs
LLM-readyAPI base
Getting started

Validate an app idea for pocket change before you spend months building the wrong thing.

Samplence is a short loop: describe the idea, let the assistant tighten the case file, start research only when the case is ready, then keep pushing the same case forward with the report in context.

What you get

One cheap pass can replace a lot of expensive wandering

Before build

Find out whether the idea is even worth deeper product work before you burn engineering time and acquisition budget.

Clearer case file

The assistant turns a messy idea into a structured brief, so research runs on something coherent instead of half-formed notes.

One case

You do not leave the conversation after the report. The same case stays open for criticism, follow-up questions, and next moves.

1. Get access

Use one API key and make sure the workspace has credits

$1 buys 10 credits. Chat turns cost 1 credit per successful turn. A research run costs 30 credits upfront and failed runs are refunded automatically.

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"
cURL
curl https://api.185.237.14.76.nip.io/v1/billing \
  -H "Authorization: Bearer $API_KEY"
Billing 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"
}

If the balance is too low, top up and continue.

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"
  }'
2. Start the case

Paste the idea in plain language

The input does not need to be polished. A rough description is enough. The assistant will turn it into a usable case file and ask only for the missing facts that matter.

cURL
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."
  }'

Chat writes return 202 Accepted with a pending assistant placeholder and the updated safe case snapshot. Research does not start here.

202 JSON
{
  "assistantMessage": {
    "id": "msg_...",
    "role": "assistant",
    "status": "complete"
  },
  "creditBalance": 239,
  "gapAssessment": {
    "readinessStatus": "ready"
  },
  "latestCompletedReportId": null,
  "reportStaleness": {
    "isStale": false
  },
  "thread": {
    "id": "thread_...",
    "messageCount": 2
  },
  "userMessage": {
    "id": "msg_...",
    "role": "user",
    "status": "complete"
  }
}
3. Get to ready

Keep chatting until the case file is ready for research

Read the case state or append another message. Watch gapAssessment.readinessStatus. While it is draft, keep filling the missing facts. When it flips to ready, the console UI shows a compact Start research button below the assistant reply.

cURL
curl https://api.185.237.14.76.nip.io/v1/chat/threads/<thread_id> \
  -H "Authorization: Bearer $API_KEY"
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."
  }'
4. Start research

Launch research explicitly when the case file is ready

This is the cheap validation step: spend a small fixed amount to test the idea with a structured external run instead of spending months on product, distribution, and hypothesis work you may not need. When the system already has an exact matching completed report, the API can return that result immediately instead of starting a new paid run.

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 concierge for travel planning"
  },
  "balance": 210,
  "gapAssessment": {
    "readinessStatus": "ready"
  },
  "reportStaleness": {
    "isStale": false
  },
  "runId": "run_...",
  "thread": {
    "id": "thread_..."
  }
}
If billing blocks you

Insufficient credits returns 402

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

Wire the same flow into MCP

MCP uses the same two-step model: send_message updates the case, start_research starts the research run. No auto-start there either.

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