Upload Sources

Upload PDF source files using a three-step process: initialize an upload, PUT the file to a signed URL, then confirm creation and start processing.

PDF uploads use a three-step process. This is the recommended way to add PDFs through the API.

Initialize the upload with POST /v1/source/init-pdf. This creates a pending source and returns a signed uploadUrl.
Upload the PDF with PUT to that uploadUrl. Do not send your API key on this request.
Confirm the upload with POST /v1/source/create-pdf. This starts OCR and, optionally, a workflow of AI models.

Complete all three steps before the pending source expiresAt time. Creating sources requires an API key with "Write" permissions.

1. Initialize PDF upload

POST https://api.annolab.ai/v1/source/init-pdf

Create a pending PDF source and receive a signed URL to upload the file.

Headers

Name

Type

Description

Authorization

string

Where you put your api key. Initializing an upload requires a key with "Write" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name

Type

Description

projectIdentifier

string|integer

Id or unique name of the project that will contain the source

sourceName

string

Name of the source to create

directoryIdentifier

string|integer

Optional. Id or name of the directory. If omitted, the project's default Uploads directory is used. If a name is passed and the directory does not exist, it is created.

groupName

string

Optional. Group that owns the project. When provided, the project is resolved as that group's project named or identified by projectIdentifier.

2. Upload the PDF

PUT {uploadUrl}

Upload the PDF bytes to the signed URL returned by init-pdf. This request goes to object storage, not to api.annolab.ai.

Do not include the Authorization API key header. Send the raw file contents as the request body.

pdf_path = '/path/to/deed.pdf'

with open(pdf_path, 'rb') as pdf_file:
  upload_response = requests.put(upload_url, data=pdf_file)

upload_response.raise_for_status()

A successful upload typically returns 200. After the file is in place, confirm the source in step 3.

3. Create the PDF source

POST https://api.annolab.ai/v1/source/create-pdf

Confirm that the PDF has been uploaded and start processing. This creates the source from the pending upload and can run OCR and a workflow of AI models.

You must have permission to create sources in the project. sourceIdentifier must match the pending source from step 1, either by name (sourceName) or by pendingSourceId.

Headers

Name

Type

Description

Authorization

string

Where you put your api key. Creating a source requires a key with "Write" permissions. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}

Request Body

Name

Type

Description

projectIdentifier

string|integer

Id or unique name of the project that contains the pending source

sourceIdentifier

string|integer

Pending source name from init-pdf, or the pendingSourceId

directoryIdentifier

string|integer

Optional. Id or name of the directory used in init-pdf. If omitted, the project's default Uploads directory is used.

groupName

string

Optional. Group that owns the project. When provided, the project is resolved as that group's project named or identified by projectIdentifier.

ocr

boolean

Optional. Defaults to running OCR. Set to false to extract existing PDF text instead of OCR.

ocrProvider

string

Optional. OCR engine when OCR is enabled. One of textract, textract_plus, or gcv. textract_plus is recommended for highest quality.

preprocessor

string

Optional. Document preprocessor. One of faa or none.

workflow

string

Optional. Name of the workflow (blueprint) to run after upload. The returned executionId can be queried with Get Workflow Execution.

abstractId

integer

Optional. Abstract to associate with this source

{
    "projectName": "Example Land Project",
    "projectId": 22,
    "directoryName": "Uploads",
    "directoryId": 12,
    "sourceName": "deed.pdf",
    "executionId": 1842,
    "uploadUrl": "https://s3.amazonaws.com/example-bucket/path/to/deed.pdf?X-Amz-Signature=...",
    "pendingSource": {
        "pendingSourceId": 501,
        "name": "deed.pdf",
        "sourceType": "pdf",
        "uploadUrl": "https://s3.amazonaws.com/example-bucket/path/to/deed.pdf?X-Amz-Signature=...",
        "createdAt": "2026-08-20T18:00:00.000Z",
        "expiresAt": "2026-08-20T19:00:00.000Z",
        "confirmedAt": "2026-08-20T19:00:00.000Z",
        "metadata": null,
        "status": "Waiting",
        "finalSourceId": null
    }
}

{
    "message": "You are not permitted to create sources for this project"
}

{
    "message": "There is no pending pdf with that name, did you initialize pdf source creation with POST source/init-pdf?"
}

{
    "message": "A pdf source has already been created. If you feel this message is inaccurate, make sure to initialize pdf source creation with source/init-pdf. "
}

create-pdf returns a pending source. Processing continues asynchronously. If a workflow was requested, executionId is the id of that workflow execution. pendingSource.finalSourceId is populated once processing finishes; use that id with the Source Files API.

create_body = {
  'projectIdentifier': 'Example Land Project',
  'directoryIdentifier': 'Uploads',
  'sourceIdentifier': source_name,
  'ocr': True,
  'ocrProvider': 'textract_plus',
  'workflow': 'land_title'
}

create_response = requests.post(
  'https://api.annolab.ai/v1/source/create-pdf',
  headers=headers,
  json=create_body
)

print(create_response.json())

Full example

import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'
pdf_path = '/path/to/deed.pdf'

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

# 1. Initialize the pending source and get a signed upload URL
init_response = requests.post(
  'https://api.annolab.ai/v1/source/init-pdf',
  headers=headers,
  json={
    'projectIdentifier': 'Example Land Project',
    'directoryIdentifier': 'Uploads',
    'sourceName': 'deed.pdf'
  }
)
init_json = init_response.json()
upload_url = init_json['uploadUrl']
source_name = init_json['sourceName']

# 2. PUT the PDF to the signed URL (no API key)
with open(pdf_path, 'rb') as pdf_file:
  upload_response = requests.put(upload_url, data=pdf_file)
upload_response.raise_for_status()

# 3. Confirm the upload and start OCR / workflow
create_response = requests.post(
  'https://api.annolab.ai/v1/source/create-pdf',
  headers=headers,
  json={
    'projectIdentifier': 'Example Land Project',
    'directoryIdentifier': 'Uploads',
    'sourceIdentifier': source_name,
    'ocr': True,
    'ocrProvider': 'textract_plus',
    'workflow': 'land_title'
  }
)

print(create_response.json())

PreviousSource Files

NextAnnotation Types

Last updated 18 days ago

Was this helpful?