Skip to main content

​
Overview

Upload one or more files to a Plangrep job using multipart form data. This is the default upload path for most use cases. Files are attached to the job but processing does not start automatically — you must call Complete Uploads after all files have been sent.
This endpoint stores files on the job but does not start processing. After all uploads are done, call POST /api/open/v1/jobs/{jobId}/uploads/complete to close the upload window and begin ingestion.

​
Endpoint

POST https://plangrep.com/api/open/v1/jobs/{jobId}/files

​
Authentication

All requests must include a Bearer token in the Authorization header. 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
jobId
string
required
The unique identifier of the job to upload files to.

​
Request

Content-Type: multipart/form-data The request body is a multipart form with a required metadata part and one or more binary file parts.

​
metadata Part

​
metadata
string
required
A JSON string describing the files being uploaded. Supports the following top-level fields:
  • clientUploadFlowId (string, optional): A client-defined identifier for this upload flow, useful for correlating uploads across retries.
  • files (array, optional): Metadata for each file part. Each entry may include:
​
partName
string
The name of the corresponding form part (e.g. file0, file1). Used to associate metadata with its binary part.
​
fileName
string
The original filename (e.g. drawings.pdf).
​
contentType
string
MIME type of the file (e.g. application/pdf).
​
classification
string
Document classification hint. One of: plans, specifications, documents, addenda, mixed, other. Omit to allow Plangrep to auto-classify.
​
sha256
string
Optional SHA-256 integrity checksum of the file bytes — a 64-character lowercase hex string. When provided, the server verifies the digest after upload.

​
File Parts

​
file0
binary
required
The binary content of the first file. Name this part file0.
​
file1, file2, ...
binary
Additional files. Name subsequent parts file1, file2, and so on. Reference each part name in the metadata.files array via partName.

​
Example metadata JSON

{
  "clientUploadFlowId": "flow-abc-123",
  "files": [
    {
      "partName": "file0",
      "fileName": "drawings.pdf",
      "contentType": "application/pdf",
      "classification": "plans"
    },
    {
      "partName": "file1",
      "fileName": "specs.pdf",
      "contentType": "application/pdf",
      "classification": "specifications"
    }
  ]
}

​
Response

Status: 200 OK
​
job
object
The updated Job object reflecting the current state of the job after upload.
​
status
string
Overall upload batch status. One of:
  • uploaded — files were accepted and stored successfully.
  • skipped — files were not stored (e.g. duplicates detected via SHA-256).
​
ingestionStatus
string
Current ingestion pipeline status for the job.
​
preflightStatus
string
Current preflight validation status for the job.
​
uploads
array
One entry per uploaded file.
​
uploads[].documentId
string
Unique identifier for the stored document.
​
uploads[].fileName
string
Stored filename as recorded by the server.
​
uploads[].contentType
string
Detected or declared MIME type.
​
uploads[].fileSize
integer
File size in bytes.
​
uploads[].classification
string
Document classification applied to this file.
​
uploads[].status
string
Per-file upload status: uploaded or skipped.
​
uploads[].skippedReason
string
If status is skipped, a human-readable reason explaining why the file was not stored.
​
documents
array
Additional document metadata objects associated with this upload batch.

​
Example Request

curl -X POST https://plangrep.com/api/open/v1/jobs/JOB_ID/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'metadata={"files":[{"partName":"file0","fileName":"drawings.pdf","contentType":"application/pdf","classification":"plans"}]}' \
  -F '[email protected]'

​
Example Response

{
  "job": {
    "id": "job_01abc123",
    "status": "uploading"
  },
  "status": "uploaded",
  "ingestionStatus": "pending",
  "preflightStatus": "pending",
  "uploads": [
    {
      "documentId": "doc_01xyz789",
      "fileName": "drawings.pdf",
      "contentType": "application/pdf",
      "fileSize": 2048576,
      "classification": "plans",
      "status": "uploaded",
      "skippedReason": null
    }
  ],
  "documents": []
}

​
Next Step

Once all files have been uploaded, close the upload window and start processing: 
curl -X POST https://plangrep.com/api/open/v1/jobs/JOB_ID/uploads/complete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
See Complete Uploads for full details.