Quickstart

Create an API key, submit a document, and poll the run.

1. Create an API key

Open Studio, create a test key, and copy the secret while it is visible. Use a key with the parse scope for this quickstart.

2. Submit a document

POST /v1/parse accepts multipart form data with a file field. Add pipeline_id when you want to run a specific parse pipeline.

curl -X POST "https://api.parsimmon.com/v1/parse" \
  -H "Authorization: Bearer psk_test_..." \
  -F "file=@invoice.pdf"

The API returns a run immediately:

{
  "run_id": "run_01JZ9Z8M4YQ9E3J7T3N6E8P2Q1",
  "status": "queued",
  "type": "parse",
  "created_at": "2026-07-06T18:32:41.120000+00:00"
}

3. Poll the run

curl "https://api.parsimmon.com/v1/runs/run_01JZ9Z8M4YQ9E3J7T3N6E8P2Q1" \
  -H "Authorization: Bearer psk_test_..."

While processing, the response contains the current run status:

{
  "run_id": "run_01JZ9Z8M4YQ9E3J7T3N6E8P2Q1",
  "status": "processing",
  "type": "parse",
  "created_at": "2026-07-06T18:32:41.120000+00:00"
}

When the run succeeds, result contains normalized blocks with grounded citations:

{
  "run_id": "run_01JZ9Z8M4YQ9E3J7T3N6E8P2Q1",
  "status": "succeeded",
  "type": "parse",
  "created_at": "2026-07-06T18:32:41.120000+00:00",
  "result": {
    "blocks": [
      {
        "type": "paragraph",
        "text": "Invoice total: $1,240.00",
        "citation": {
          "field": "invoice_total",
          "page": 1,
          "bbox": {
            "top": 72,
            "left": 64,
            "width": 18,
            "height": 4
          }
        }
      }
    ]
  }
}

All errors use the same envelope:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this request.",
    "details": {}
  }
}