DeepFellow DOCS
DeepFellow API ReferenceMetadata expansion

Create a metadata expansion job

POST
/v1/metadata/expand

Queue metadata extraction for a batch of documents; each document is processed independently.

Authorization

headerAuthorizationBearer <token>

Header Parameters

OpenAI-Organization?|

Organization Id from OpenAi compatible endpoint. Required to organization access or project access (with OpenAI-Project header) when logged as User or Admin User.

OpenAI-Project?|

Project Id from OpenAi compatible endpoint. Required to project access for organization api key or User / Admin User access with OpenAI-Organization

Request Body

application/json
  1. body

Request body for creating a metadata expansion job.

document_ids*array<>

File IDs of the documents to process.

Items1 <= items <= 1000
fields*array<>

Metadata fields to extract from each document. Descriptions are limited to 500 characters.

Items1 <= items <= 50
image_processing_mode?ImageProcessingMode

How images are handled when a document needs fallback conversion. Applies to every document in the job.

Default"ignore"
Value in"ignore""description"

Response Body

Successful Response

application/json
  1. response

A metadata expansion job — extracts the requested fields from each of its documents.

id*string

The job identifier, which can be referenced in the API endpoints.

Match^[0-9a-fA-F]{24}$
project_id*string

The project identifier this job belongs to.

Match^[0-9a-fA-F]{24}$
status*MetadataExpansionJobStatus

Aggregate status across all documents in the job. 'completed' covers partial failures too — check each document's own status for details; 'failed' is only set when every document in the job failed; 'cancelled' is a terminal state set by the caller and is never resumed.

Value in"pending""processing""completed""failed""paused""cancelled"
fields*array<>

Metadata fields requested for this job.

documents*array<>

Per-document status and extracted metadata.

describe_images?boolean

Whether image descriptions were requested at job creation; applies to every document in the job.

Defaultfalse
created_at?integer

The Unix timestamp (in seconds) for when the job was created.

finished_at?|

The Unix timestamp (in seconds) for when every document reached a terminal state.

Example Request
curl -X POST 'https://deepfellow-server-host/v1/metadata/expand' \  -H 'Content-Type: application/json' \  -d '{  "document_ids": [    "5eb7cf5a86d9755df3a6c593"  ],  "fields": [    {      "name": "string"    }  ]}'
Example Response
{  "id": "5eb7cf5a86d9755df3a6c593",  "project_id": "5eb7cf5a86d9755df3a6c593",  "status": "pending",  "fields": [    {      "name": "string",      "description": "string"    }  ],  "documents": [    {      "document_id": "5eb7cf5a86d9755df3a6c593",      "status": "pending",      "extracted": {        "property1": "string",        "property2": "string"      },      "error": "string",      "attempts": 0    }  ],  "describe_images": false,  "created_at": 0,  "finished_at": 0}

We use cookies on our website. We use them to ensure proper functioning of the site and, if you agree, for purposes such as analytics, marketing, and targeting ads.