API reference

Upload a single file as multipart/form-data. The endpoint returns immediately with a document ID; classification and extraction run in the background.

Use this for one document at a time. The response is 202 Accepted, not 200, because the file has only been received and queued. The pipeline runs in the background and can take anywhere from 30 seconds for a small datasheet to several minutes for a multi-page P&ID.

Pathnovo deduplicates by content hash, scoped to the project. If you upload the same file (byte-for-byte) into the same project twice, the second response returns the original document_id with deduplicated set to true and no new job is queued. This makes uploads idempotent enough to retry safely.

Supported file types: PDF, PNG, JPG, TIFF, XLSX, DOCX. Max size per file is 100 MB.

After upload, watch progress on the SSE stream or poll the status endpoint. Don't keep the upload connection open waiting for completion.

Request body

Content-Type: multipart/form-data

Responses

{
  "document_id": "UUID",
  "status": "queued",
  "deduplicated": false
}

Upload a ZIP archive. Every file inside is unpacked and treated as a separate document. Each gets its own document_id and runs through the pipeline independently.

Use this when you have a folder of related documents (a handover package, a vendor deliverable, a turnaround set) and want to push them all in one request. Pathnovo extracts the archive on its side, then queues each file as a normal upload.

The response includes the count and an array of UploadResponse objects, one per file, in the order they appeared in the archive. Track each document_id individually after that.

Nested folders inside the ZIP are flattened. The archive must be < 1 GB. For very large sets, split into multiple ZIPs and call this endpoint per chunk.

Request body

Content-Type: multipart/form-data

Responses

{
  "total_files": 12,
  "documents": [
    { "document_id": "UUID", "status": "queued", "deduplicated": false }
  ]
}

Hand Pathnovo a URL and we'll fetch the file ourselves, then run the standard pipeline. Useful when files live in S3, SharePoint, or an internal share that's reachable over the public internet.

Pathnovo's importer follows redirects, respects standard auth on the URL (basic auth and query-string tokens), and verifies the file type before queuing the job. The download happens once; the file is then stored in our document store like any other upload.

For private files, generate a short-lived pre-signed URL on your side (e.g. an S3 presigned URL with a 15-minute TTL). The URL only needs to be valid long enough for us to fetch the file, which usually takes a few seconds.

Request body

Model: UrlImportRequest · Content-Type: application/json

{
  "url": "https://example.com/spec.pdf",
  "project_id": "UUID"
}

Responses

{
  "document_id": "UUID",
  "status": "queued",
  "deduplicated": false
}

Read the current state of a document. Use this when you want a single-point-in-time check, for example from a cron job or when refreshing a UI page.

The status field walks through these values in order: queued (uploaded, waiting for a worker), classifying (the classifier is running), extracting (the right pipeline is pulling fields), extracted (done, result available), failed (something blew up, see error_detail on the extraction job).

The response also includes the original filename, mime type, and three timestamps: when it was uploaded, when classification finished, and when extraction finished. The classification and extraction timestamps are null until those steps complete.

If you need live updates rather than snapshots, prefer the SSE progress stream on /documents/{id}/progress so you don't burn rate limit on a tight poll loop.

Path parameters

Responses

{
  "id": "UUID",
  "project_id": "UUID",
  "original_filename": "spec.pdf",
  "mime_type": "application/pdf",
  "status": "extracted",
  "uploaded_at": "2026-04-25T08: 00: 00Z",
  "classified_at": "2026-04-25T08: 00: 14Z",
  "extracted_at": "2026-04-25T08: 01: 02Z"
}

A Server-Sent Events stream that emits an event every time the document moves to a new stage or the extractor reports a percentage. The connection closes automatically when the job hits a terminal state (extracted or failed).

Each event is a JSON object with a `status` field and an optional `progress` field (0-100) for stages that report incremental progress. Browsers can subscribe with the standard EventSource API; on the server side use any HTTP client that supports streaming.

If the connection drops, reconnect with the same URL. Pathnovo will replay the latest known state immediately so you never miss the terminal event. There's no event ID; reconnection is stateless.

If the document already completed before you connected, you'll get one event with the final status, then the connection closes. This makes it safe to subscribe even after a job is done.

Path parameters

Responses

Returns the document type Pathnovo assigned to this file, the confidence score, the method (auto or manual), and the bucket the type belongs to.

Confidence is an integer from 0 to 100. In practice, anything above 90 is rock-solid, 70 to 90 is usually right but worth a glance from a human reviewer, and below 70 is worth manual confirmation. The classifier surfaces low-confidence calls in our own UI for review; you can do the same on your side.

Bucket is a coarse grouping (drawings, datasheets, registers, certificates) that lets you filter without knowing the exact doc type. Useful for dashboards.

If the classification was overridden manually, is_manual_override is true and confidence reads 100. The original auto-classification is still recorded in our system but not exposed here.

Path parameters

Responses

{
  "id": "UUID",
  "document_id": "UUID",
  "doc_type_id": "UUID",
  "doc_type_name": "P&ID",
  "bucket": "drawings",
  "confidence": 96,
  "method": "auto",
  "is_manual_override": false,
  "created_at": "2026-04-25T08: 00: 14Z"
}

Manually set the document type. This re-queues extraction with the new schema and returns the updated classification record.

Use this when the auto-classifier got it wrong and the result you got back from /extraction/documents/{id}/result is using the wrong shape. Common case: a vendor datasheet that visually looks like a P&ID, or two doc types that share the same template.

When you call this endpoint, Pathnovo deletes the previous extraction result, looks up the schema for the new doc_type_name, and queues a fresh extraction job. The original document file is reused, no upload needed. Watch the new job through the standard progress endpoints.

The reason field is stored on our side for your audit trail. We don't use it to retrain anything automatically; if you want classifier improvements based on overrides, talk to your integration engineer.

Path parameters

Request body

Model: ManualOverrideRequest · Content-Type: application/json

{
  "doc_type_name": "P&ID",
  "reason": "auto-classified as isometric, but it is a P&ID"
}

Responses

{
  "id": "UUID",
  "document_id": "UUID",
  "doc_type_id": "UUID",
  "doc_type_name": "P&ID",
  "bucket": "drawings",
  "confidence": 96,
  "method": "auto",
  "is_manual_override": false,
  "created_at": "2026-04-25T08: 00: 14Z"
}

Returns the lightweight status record for one extraction job. Use this when you already hold a job_id and only need to know if it's done.

The status field can be queued, running, completed, or failed. resolved_scope tells you which config layer was used to extract this document (default, org, or project) so you can debug surprising results during a rollout of new prompts.

Compared to GET /extraction/documents/{id}/jobs (which returns all jobs for the document including the full result), this endpoint is cheap and small. Reach for it inside tight loops.

Path parameters

Responses

{
  "id": "UUID",
  "status": "completed",
  "resolved_scope": "project",
  "started_at": "2026-04-25T08: 00: 14Z",
  "completed_at": "2026-04-25T08: 01: 02Z"
}

Returns every extraction job that has run for this document, newest first, including the full result and any error detail.

A document can have more than one job in two cases: classification was overridden (so we re-extracted with the new schema), or the first extraction failed and was retried. This endpoint shows the full history, so you can compare results across attempts.

Each job record includes the resolved_scope (default / org / project) used at the time. If you change project-level config and re-extract, you'll see the new scope on the latest job.

Path parameters

Responses

[
  {
    "id": "UUID",
    "document_id": "UUID",
    "status": "completed",
    "resolved_scope": "project",
    "result": { "title_block": { "...": "..." } },
    "error_detail": null,
    "started_at": "2026-04-25T08: 00: 14Z",
    "completed_at": "2026-04-25T08: 01: 02Z",
    "created_at": "2026-04-25T08: 00: 00Z"
  }
]

Returns the latest completed extraction as typed JSON. The shape depends on the document type; look up the schema for that type if you need to know the exact fields.

This is the endpoint you'll call most often. After a document reaches the extracted status, hit this to pull the structured data and load it into your downstream system.

Every result includes the embedded title_block header (28 fields shared across every doc type) plus a body that depends on the doc type. For example, a P&ID returns lines, instruments, equipment, valves; a mill certificate returns chemical composition, mechanical tests, dimensions.

If the document hasn't finished extracting yet, the response is 202 Accepted with an empty body. Don't treat that as a result; wait for the job to complete.

Path parameters

Responses

Compact status flags for the latest extraction attempt on this document, without the full result payload.

Use this when you need a quick yes/no on whether the latest extraction is ready, and you don't want to pull the full result. Common pattern: poll this from a worker that's deciding whether to fan out the result-fetch job.

Path parameters

Responses

List every document type Pathnovo can extract, with the schema version and field count.

Responses

[
  {
    "doc_type_id": "UUID",
    "doc_type_name": "P&ID",
    "bucket": "drawings",
    "version": "1.4.0",
    "field_count": 78
  }
]

Get the JSON schema for a specific document type, including the embedded title_block header.

Path parameters

Responses

{
  "doc_type_id": "UUID",
  "doc_type_name": "P&ID",
  "version": "1.4.0",
  "schema": {
    "title_block": "<common>",
    "lines": [
      { "tag": "string", "size_in": "number", "service": "string" }
    ]
  }
}

List the raw document type records used by the classifier. Use this to map document type names to IDs.

Responses

[
  {
    "id": "UUID",
    "name": "P&ID",
    "bucket": "drawings",
    "description": "Piping and instrumentation diagram"
  }
]

Summary counts for a project. Documents uploaded, classified, extracted, failed, plus pages processed for billing.

Path parameters

Responses

{
  "project_id": "UUID",
  "documents_uploaded": 1284,
  "documents_classified": 1280,
  "documents_extracted": 1271,
  "documents_failed": 9,
  "by_status": {
    "queued": 0,
    "classifying": 4,
    "extracting": 13,
    "extracted": 1271,
    "failed": 9
  },
  "pages_processed": 8420,
  "billable_pages": 8420
}

Accuracy and method breakdown for a project. Shows the auto vs manual split, average confidence, and counts by document type.

Path parameters

Responses

{
  "total_classified": 1280,
  "auto_classified": 1267,
  "manual_overrides": 13,
  "avg_confidence": 94.6,
  "by_method": { "auto": 1267, "manual": 13 },
  "by_bucket": { "drawings": 612, "datasheets": 318, "registers": 350 },
  "by_doc_type": { "P&ID": 184, "Isometric": 230, "Pressure Vessel Datasheet": 88 }
}

Daily document and page counts for a project. Use the from and to query params to set a range. Defaults to the last 30 days.

Path parameters

Query parameters

Responses

{
  "from": "2026-04-01",
  "to": "2026-04-25",
  "buckets": [
    { "date": "2026-04-01", "uploaded": 42, "extracted": 41, "pages": 268 },
    { "date": "2026-04-02", "uploaded": 60, "extracted": 60, "pages": 401 }
  ],
  "totals": { "uploaded": 1284, "extracted": 1271, "pages": 8420 }
}