Quickstart

Create an account, choose a workspace and start your first cited research run.

Implementation guide · REST API v1

Before you begin

Choose your deployed API origin and workspace. For API writes, use an eligible plan and a live key with runs:write, runs:read and reports:read. Keep the secret on your server.

1. Create your workspace

Create a free account, confirm your email, and set up your workspace. Your workspace keeps research, agents and permissions together.

2. Ask a real question

Open Ask and describe the check. Start with a company, a supplier, or a question supported by public evidence. Add files if your research needs private context.

Try: “Research Acme Logistics’ company registration, owners and supplier risks.”

3. Choose your research effort

Select Fast, Standard or Deep. Proofline picks the model for each step, and the job shows what it cost when it finishes.

4. Review the report

Follow the live research. When it finishes, inspect the claims and their source evidence, review disputed findings, and export the report if needed.

Start a run over the API

These examples use the current REST API. Configure your API origin and workspace slug. Use a live key with runs:write and reports:read scopes; test keys support read-only requests.

// Server-side: configure your API origin, live key and workspace.
// Persist the idempotency key with this request; reuse it for retries.
const origin = process.env.PROOFLINE_API_ORIGIN;
const workspace = "your-workspace";
const headers = {
  Authorization: `Bearer ${process.env.PROOFLINE_KEY}`,
  "Content-Type": "application/json",
  "Idempotency-Key": crypto.randomUUID(),
};

const response = await fetch(
  `${origin}/v1/workspaces/${workspace}/runs`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      question: "Research Acme Logistics and its supplier risks",
      effort: "standard",
      require_plan_approval: false,
    }),
  }
);
if (!response.ok) throw new Error(await response.text());
const run = await response.json();
console.log(run.id, run.status, run.charged_micro_usd);

Use the simplest route for your integration.

The workspace examples above expose detailed controls. POST /v1/run is the compact wait-or-poll API used by the SDKs: 200 contains a finished result; 202 contains poll_url and stream_url. A subsequent result request may return 409 run_not_finished while work continues.

# Server-side: set PROOFLINE_API_ORIGIN and PROOFLINE_KEY.
# Persist REQUEST_ID and reuse it only for this same request.
curl "$PROOFLINE_API_ORIGIN/v1/run?wait=60" \
  -H "Authorization: Bearer $PROOFLINE_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Research Acme Logistics and its supplier risks",
    "effort": "standard"
  }'

# 200: completed result. 202: pending, with poll_url and stream_url.
# Follow the returned poll_url with the same authentication.

REQUEST → RESPONSE → NEXT STEPIllustrative response excerpts

Read the result and its evidence.

A completed one-call request returns a result. Inspect the run status, sources, and any unresolved findings before your application relies on the answer.

Read the relevant guide ↗

EXAMPLE / 200

{
  "status": "completed",
  "answer": "Example cited research brief…",
  "claims": []
}

Keep the report and source references together.

Inspect status and stop_reason before treating an output as complete. Retrieve the claims and sources alongside the report, and use charged_micro_usd for the actual charge.

Relevant endpoints

POST/v1/run

GET/v1/runs/{run_id}/result

Replace workspace and record placeholders with your values. See the live API reference ↗ for schemas.

Was this page helpful?