API Overview - DeckFlow Developers

API Call Model

DeckFlow API uses an asynchronous task model for document processing operations. The workflow consists of: authentication, task creation, status polling (or real-time subscription), and downloading files.

1. General API & Authentication

Base URL

The base URL for all API requests is: https://app.deckflow.com/api

HTTP Headers

For every API request or file retrieval, include the following headers for authorization:

Header	Type	Required	Description
`Authorization`	String	Yes	API key formatted as `Bearer <YOUR_API_KEY>`.
`Content-Type`	String	Yes	Must be set to `multipart/form-data` when submitting tasks.

2. Submit Asynchronous Task

The DeckFlow API uses a single-step multipart/form-data format to submit tasks. There is no need to pre-upload files; simply pass the file binary data and parameters directly in the request body.

Endpoint

Path: POST /tools/tasks
Content-Type: multipart/form-data

Request Body Parameters (Form Data)

Parameter	Type	Required	Description
`files`	File	Yes	Source file to be processed. Multiple files are supported (e.g. for merger tasks).
`type`	String	Yes	The tool task type, such as `generation`, `translation`, `revamp`, or specific utility IDs (e.g. `convertor.ppt2pdf`).
`notifyURL`	String	No	Webhook callback URL to receive task status update notifications.
`params`	String (JSON)	No	Additional options for the tool as a JSON string. Defaults to an empty JSON string `"{}"`.

Request Examples

curl --location 'https://app.deckflow.com/api/tools/tasks' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--form 'files=@"/path/to/presentation.pptx"' \
--form 'type="convertor.ppt2pdf"' \
--form 'params="{}"'

const formData = new FormData();
formData.append('files', fileInput.files[0]);
formData.append('type', 'convertor.ppt2pdf');
formData.append('params', JSON.stringify({}));

const response = await fetch('https://app.deckflow.com/api/tools/tasks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>'
  },
  body: formData
});
const result = await response.json();

import requests

url = "https://app.deckflow.com/api/tools/tasks"
headers = {
    "Authorization": "Bearer <YOUR_API_KEY>"
}
files = [
    ("files", ("presentation.pptx", open("presentation.pptx", "rb"), "application/vnd.openxmlformats-officedocument.presentationml.presentation"))
]
data = {
    "type": "convertor.ppt2pdf",
    "params": "{}"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Response Body (JSON)

{
  "id": "task-uuid-string",
  "name": "presentation.pptx",
  "type": "convertor.ppt2pdf",
  "status": "pending",
  "preview": null,
  "createdAt": "2026-06-11T08:52:00.000Z",
  "updatedAt": "2026-06-11T08:52:00.000Z"
}

3. Task Status & Management

3.1 Get Task Status / Real-time Stream Subscription

Retrieve task details or subscribe to a real-time event stream for execution updates.

Endpoint: GET /tools/tasks/{taskId}
Standard Polling Response (JSON):

Returns the current task status. Once status reaches "completed", the result block contains the download link and asset metadata. If status is "failed", details can be inspected in the error block.

Server-Sent Events (SSE) Real-time Stream Subscription:

Include the header response-event-stream: yes to initiate a text/event-stream real-time subscription. The server will push updates in the format data: { ...taskJSON } and close the connection when the task reaches a terminal status ("completed" or "failed").

3.2 List Task History

Query a list of tasks previously submitted.

Endpoint: GET /tools/tasks?type={taskType}&_startIndex={offset}&_maxResults={limit}
Response Headers:

The x-content-record-total header indicates the total count of matching tasks.

Response Body (JSON):

Contains an array of Task objects.

3.3 Delete Task

Remove a specific task and delete its generated output files from storage.

Endpoint: DELETE /tools/tasks/{taskId}
Response Status Code: 204 No Content