Document Summarization

Document Summarization generates a summary for each document in a batch of previously uploaded documents. A long document is split into chunks, each chunk is summarized, and the chunk summaries are combined into one final summary with a second pass.

Jobs run in the background via Nightshift, so you can queue a batch and poll for results instead of waiting on the request.

Create a Job

Upload your files first with POST /v1/files (see Upload Files), then queue summarization for them:

curl -X 'POST' \
  'https://deepfellow-server-host/v1/summarization/summarize' \
  -H "Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "document_ids": ["FILE_ID_1", "FILE_ID_2"],
  "options": {"max_length": 150, "style": "bullet_points"}
}'

import requests

response = requests.post(
    "https://deepfellow-server-host/v1/summarization/summarize",
    headers={"Authorization": "Bearer DEEPFELLOW-PROJECT-API-KEY"},
    json={
        "document_ids": ["FILE_ID_1", "FILE_ID_2"],
        "options": {"max_length": 150, "style": "bullet_points"},
    },
)

print(response.json())

const response = await fetch('https://deepfellow-server-host/v1/summarization/summarize', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer DEEPFELLOW-PROJECT-API-KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        document_ids: ['FILE_ID_1', 'FILE_ID_2'],
        options: { max_length: 150, style: 'bullet_points' }
    })
});

const data = await response.json();
console.log(data);

Response:

{
    "id": "68da445c5186deb8bca2bde9",
    "project_id": "68da445c5186deb8bca2bdea",
    "status": "pending",
    "options": {"max_length": 150, "style": "bullet_points"},
    "documents": [
        {"document_id": "FILE_ID_1", "status": "pending", "summary": null, "error": null, "attempts": 0},
        {"document_id": "FILE_ID_2", "status": "pending", "summary": null, "error": null, "attempts": 0}
    ],
    "created_at": 1735689600,
    "finished_at": null
}

options is optional. Omit it to get a neutral-style summary of up to 200 words per document.

options applies to every document in the job, and to the final combined summary of a chunked document, not to each intermediate chunk summary.

Creating a job returns 400 Bad Request if any document_ids entry doesn't exist or doesn't belong to your project, and 503 Service Unavailable if Nightshift is enabled but not currently connected to RabbitMQ.

Check Job Status

curl -X 'GET' \
  'https://deepfellow-server-host/v1/summarization/jobs/JOB_ID' \
  -H "Authorization: Bearer DEEPFELLOW-PROJECT-API-KEY"

The job's status is one of pending, processing, completed, failed, or paused. completed covers partial failures too, so check each document's own status for details; failed is only set when every document in the job failed.

Once a document completes, its summary field holds the generated text:

{
    "document_id": "FILE_ID_1",
    "status": "completed",
    "summary": "The document covers...",
    "error": null,
    "attempts": 1
}

The summary is also written back onto the file itself, so GET /v1/files/FILE_ID returns it under summary without needing the job ID. A later job for the same document overwrites its previous value.

Pause, Resume, and Retry

• POST /v1/summarization/jobs/{job_id}/pause stops a job's documents from advancing further. Pausing an already-completed or failed job returns 409 Conflict.
• POST /v1/summarization/jobs/{job_id}/resume re-queues a paused job's pending documents. Resuming a job that is not paused returns 409 Conflict.
• POST /v1/summarization/jobs/{job_id}/retry resets the job's failed documents to pending and re-queues them, each with a fresh attempt budget. A job with no failed documents returns 409 Conflict.

All three return the updated job, or 404 Not Found if job_id doesn't exist.

See Nightshift Background Jobs for how these interact with retry and dispatch when Nightshift is enabled or disabled.