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.

Each summary is written in the document's own language unless you set language. The model that writes it is the summarization_model dynamic setting. An existing install keeps the model stored in its configuration. See Document Summarization Settings for every summarization setting and its default.

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", "language": "English"}
}'

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", "language": "English"},
    },
)

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', language: 'English' }
    })
});

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

Response:

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

options is optional. Omit it to get a neutral-style summary of up to 200 words per document, in each document's own language.

options applies to every document in the job, and to the final combined summary of a chunked document. Each intermediate chunk summary is neutral prose of about 150 words (at most 600 tokens) in the document's own language. It keeps what the requested style needs: decisions, outcomes, action items, owners, and deadlines for executive, and every distinct key point for bullet_points.

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 the server is 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,
    "model": "gemma4:12b",
    "truncated": false
}

model is the model that wrote the summary, and stays null until the document completes. truncated is true when the document was too long to summarize in full. In that case, the text passed to the final summarization call was cut off, so the summary covers only part of the document. The document still reaches completed.

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. The file also carries summary_provenance, which records how that summary was produced:

{
    "summary": "The document covers...",
    "summary_provenance": {
        "model": "gemma4:12b",
        "options": {"max_length": 150, "style": "bullet_points", "language": null},
        "job_id": "68da445c5186deb8bca2bde9",
        "created_at": 1735689700,
        "truncated": false
    }
}

A later job for the same document overwrites both fields. summary_provenance is null for a summary written before DeepFellow Server recorded provenance.

In the Web UI, the Document Summarization page has a Language field next to the length and style options. The job results table shows the model for each document, and a Partial badge on a truncated summary.

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.