LimAI Docs

POST/api/v1/document/{extractionSchemaId}/process-file-async/{fileId}ASYNC

Queue a document processing job asynchronously. The job runs in the background and you can poll for results using the get-file-data endpoint, or receive a webhook notification when complete.

Parameters

Name	Type	In	Required	Description
`extractionSchemaId`	string	path	Yes	The extraction schema ID to use for processing.
`fileId`	string	path	Yes	The file ID returned from the get-url endpoint after uploading.

The request body should be an empty JSON object {}.

Request

const response = await fetch(
`https://app.limai.io/api/v1/document/${SCHEMA_ID}/process-file-async/${fileId}`,
{
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({})
}
)
const { jobId, fileId: queuedFileId } = await response.json()

Response

Job Queued (200)

Response200

{
  "message": "Job queued for processing",
  "fileId": "file_abc123def456",
  "jobId": "job_789xyz012"
}

Duplicate Job (409)

If a processing job is already in progress for this file, a 409 Conflict is returned.

Response409

{
  "error": "Job already in progress",
  "message": "A processing job for this file is already in progress.",
  "fileId": "file_abc123def456",
  "existingJobId": "job_existing123"
}

Polling for Results

After queuing a job, poll the get-file-data endpoint until the status is COMPLETED or FAILED.

async function pollForResults(fileId) {
const maxAttempts = 120
let attempts = 0

while (attempts < maxAttempts) {
  const response = await fetch(
    `https://app.limai.io/api/v1/document/get-file-data?fileId=${fileId}`,
    { headers: { "Authorization": `Bearer ${API_TOKEN}` } }
  )
  const data = await response.json()

  if (data.status === "COMPLETED") return data
  if (data.status === "FAILED") throw new Error(data.errorMessage)

  attempts++
  await new Promise(r => setTimeout(r, 5000))
}
throw new Error("Polling timeout")
}

Polling Best Practices

Use 5-10 second intervals to balance responsiveness and server load
Set a maximum timeout to prevent infinite polling
Handle network errors with retry logic
Consider using webhooks for real-time notifications instead of polling
Store the jobId for debugging purposes

Process File (Async)