---
title: "Initiate app download"
method: POST
path: "/v1/apps/{documentId}/download"
tags: ["App downloads"]
---

# Initiate app download

`POST /v1/apps/{documentId}/download`

## Request

- Base URL: `https://blobsrus.omniapp.co/api`
- URL: `https://blobsrus.omniapp.co/api/v1/apps/{documentId}/download`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Start an asynchronous download job for a published app, rendered headlessly the same way a scheduled app delivery renders it. Every query in the app's workbook runs, including linked tabs; queries on a model the downloading user cannot query are omitted. Only the app's default view is rendered.

After starting a job, poll [Get app download status](/api/app-downloads/get-app-download-status) for completion, then retrieve the file from [Get app download file](/api/app-downloads/get-app-download-file).

Only one download per app, per user is allowed at a time. If a download is already in progress, the request returns a `409 Conflict` response with the existing job ID.

## Path parameters

- `documentId` string, required

## Query parameters

- `userId` string, uuid

## Request body

- object
  - `filename` string: Custom filename for the downloaded file, without extension. Defaults to the app name.
  - `format` 'png' | 'pdf' | 'xlsx' | 'csv', required: Specifies the output format: - `png` - A screenshot of the rendered app - `pdf` - The rendered app as one page - `xlsx` - A screenshot cover sheet plus one sheet per query - `csv` - A ZIP of one CSV per query

## Response `200`

Download job initiated successfully.

- object
  - `job_id` string, uuid, required: ID of the download job. Use this to poll for status and fetch the file.
  - `message` string, required: Status message

## Other responses

- `400`: Invalid request body, such as a missing or invalid `format`, or an unrecognized field.
- `401`: Missing or invalid authentication.
- `403`: Apps or scheduled app deliveries aren't enabled for the organization, the user can't view or download the app, or a Personal Access Token named another user.
- `404`: App not found, not published, archived, or the document has no app.
- `405`: Method Not Allowed - Invalid HTTP method for this endpoint
- `409`: A download of this app is already in progress for this user.
- `429`: Too Many Requests - Rate limit exceeded (60 requests/minute)
- `500`: The download job could not be started.

## Changes

- **2026-11-03** `43290040f88f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omni/apis/omni-api/changes/v1/apps/:documentId/download/post.md)

---

[API](https://skmtc.dev/omni/apis/omni-api.md) - [All operations](https://skmtc.dev/omni/apis/omni-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omni/apis/omni-api/revisions/43290040f88f?raw)