Extraction workflows, not extraction prompts.

A workflow, not a prompt.

What that shape buys you over sending a prompt per document:

Create a workflow

Send a JSON body with a name and an inline extraction schema. Alternatively, pass a sourceGroupId to clone the schema, model, and prompt from a previous run instead of an inline schema.

Body

Extraction field

Fields are explicit: a name, a type of string, number, boolean, date, or list, and an optional description. A list field also needs itemFields — the scalar columns of each item.

curl https://datasnipe.app/api/v1/workflows \
  -H "Authorization: Bearer $DATASNIPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clinical trial extractor",
    "model": "claude-sonnet-5",
    "extractionSchema": [
      { "name": "title", "type": "string", "description": "Paper title" },
      { "name": "sample_size", "type": "number", "description": "Participants enrolled" },
      { "name": "double_blind", "type": "boolean" },
      {
        "name": "arms",
        "type": "list",
        "description": "Each treatment arm",
        "itemFields": [
          { "name": "label", "type": "string" },
          { "name": "dose_mg", "type": "number" }
        ]
      }
    ]
  }'

Responds 201 with { "workflow": { … } }. The workflow object includes id, name, ownerType, ownerId, extractionSchema, model, contextPrompt, fewShotExamples, createdAt, and updatedAt.

Run a workflow

Runs are multipart/form-data: attach one or more files parts. DataSnipe processes the bytes in memory, persists them for later re-processing, and returns a group id plus a job per file.

curl https://datasnipe.app/api/v1/workflows/$WORKFLOW_ID/runs \
  -H "Authorization: Bearer $DATASNIPE_API_KEY" \
  -F "files=@paper-1.pdf" \
  -F "files=@paper-2.pdf"

{
  "workflowId": "0b1c…",
  "groupId": "9f2a…",
  "jobs": [
    { "jobId": "a1…", "fileName": "paper-1.pdf" },
    { "jobId": "b2…", "fileName": "paper-2.pdf" }
  ]
}

Hold on to groupId — it's how you poll the run and download artifacts.

One-off runs

To extract without saving a workflow, post to /api/v1/runs with a JSON config part alongside the files parts. The config takes the same extractionSchema, model, contextPrompt, and fewShotExamples fields as a workflow. The response is a groupId and jobs — but no workflowId, since nothing is persisted.

curl https://datasnipe.app/api/v1/runs \
  -H "Authorization: Bearer $DATASNIPE_API_KEY" \
  -F 'config={
        "extractionSchema": [ { "name": "title", "type": "string" } ],
        "model": "claude-sonnet-5"
      };type=application/json' \
  -F "files=@paper-1.pdf"

Poll the returned groupId and download artifacts with the same job-group endpoints used for saved runs.

Duplicate run protection

Both run endpoints are billable. DataSnipe automatically protects against accidental duplicate submissions by fingerprinting the billing account, run configuration, and file metadata.

curl https://datasnipe.app/api/v1/runs \
  -H "Authorization: Bearer $DATASNIPE_API_KEY" \
  -F 'config={ ... };type=application/json' \
  -F "files=@paper-1.pdf"

• Same request body → replays the original 202 (same groupId), no second submission.
• Different body → creates a new run.
• Retry while the first request is still running → 409 idempotency_conflict; wait and retry.
• If the first attempt failed before anything was billed (400/402/429), the duplicate-protection claim is released so a corrected retry can proceed.

Duplicate-protection claims are scoped to the billing account and expire after about 10 minutes.

Models

Pass a model id as model. The default is claude-sonnet-5. The set of ids your account can use is listed in the workflow builder in your dashboard, so it always reflects what's currently available to you — pick one from there rather than against a hardcoded list that drifts as models are added or retired.

File constraints

Throughput

An account may have a fixed number of jobs in flight at once — counting every job that hasn't reached a terminal state across all runs: queued, ready, summarizing, and extracting all count; done and failed don't. The check runs on arrival against the whole batch: if the jobs you're submitting would push the account's in-flight count past the cap, the run is rejected whole — nothing is queued — with 429, a Retry-After: 30 header, and a body of { error, limit, outstanding, retryAfterSeconds }. The cap comes back as limit in that body (and is shown in your dashboard), so read it from the response rather than hardcoding a number. Wait for jobs to finish — or honour Retry-After — then resend. The limit is per owner, so a personal key and an organization key draw from separate budgets.

Polling & webhooks

Read endpoints — the job-group result and the artifact downloads — are not rate-limited. Poll GET /api/v1/job-groups/:groupId on a fixed interval until every job is done or failed; every 2–3 seconds is a good default. A run's wall-clock grows with page count, so for large batches back off to a longer interval rather than hammering — there's nothing to gain from a tight loop.

Pagination

GET /api/v1/workflows returns your full list in a single response — there are no limit, offset, or cursor parameters today. Don't build paging logic against it; expect the complete set.

Dates & value formats

Two date-shaped things are easy to conflate — they have different formats:

Resource timestamps are plain SQLite-style UTC strings, not ISO 8601 with a T/Z. An extracted date value comes back as the string the model read off the page, so normalize it downstream if you need a canonical format.