> ## Documentation Index > Fetch the complete documentation index at: https://docs.omni.co/llms.txt > Use this file to discover all available pages before exploring further. # Initiate app download > 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. ## OpenAPI ````yaml /api/openapi.yaml post /v1/apps/{documentId}/download openapi: 3.1.0 info: title: Omni API description: > The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. version: 1.0.0 contact: name: Omni Support url: https://docs.omni.co servers: - url: https://{instance}.omniapp.co/api description: Production variables: instance: default: blobsrus description: Your production Omni instance subdomain - url: https://{instance}.playground.exploreomni.dev/api description: Playground variables: instance: default: blobsrus description: Your playground Omni instance subdomain security: - bearerAuth: [] - orgApiKey: [] tags: - name: Who Am I description: Inspect your own user permissions - name: AI description: AI-powered query generation - name: AI Credit Controls description: Manage organization-level AI credit usage - name: AI Credit Usage description: Monitor AI credit usage - name: AI Evals description: >- Manage prompt sets and runs used to score AI quality against curated prompt suites. - name: AI Model Suggestions description: Manage AI-generated suggestions for shared models - name: AI Routines description: >- Manage Routines, which are scheduled, recurring AI-powered tasks that run automatically on your data - name: Apps description: Draft and publish app documents. - name: App downloads description: Download apps as PNG, PDF, XLSX, or CSV files - name: Documents v2 description: > A draft-based workflow for creating and editing documents: create a document, patch a draft, then publish. - name: Documents description: Create, retrieve, and manage documents - name: API Tokens description: >- Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth grants) - name: IP Allowlist description: Manage the organization's IP allowlist - name: Connections description: Manage database connections - name: Connection environments description: Manage connection environments database connections - name: Color Palettes description: Manage custom chart color palettes - name: Content description: Unified content retrieval (documents and folders) - name: Content migration description: Export and import dashboards - name: Content validator description: Validate content against models and perform find/replace operations - name: Dashboard downloads description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files - name: Dashboard filters and controls description: Read and update dashboard filter and control default values - name: dbt description: Manage dbt configuration for connections - name: Document favorites description: Favorite and unfavorite documents - name: Document labels description: Apply and manage labels on documents - name: Document permissions description: Manage document-level access - name: Embed description: Manage embed sessions - name: Labels description: | Manage labels in the organization - name: Folders description: Create and organize content folders - name: Folder favorites description: Favorite and unfavorite folders - name: Folder labels description: Apply and manage labels on folders - name: Folder permissions description: Manage folder-level access - name: Jobs description: Check status of asynchronous jobs - name: Models description: Create and manage data models - name: Model branches description: Manage model branches and merge changes - name: Model git configuration description: Manage git configuration for shared models - name: Queries description: Execute workbook queries - name: Schedules description: Create and manage scheduled tasks - name: Schedule recipients description: Manage schedule recipients - name: Schema refresh schedules description: Manage automated schema refresh schedules for connections - name: Skills description: >- Manage skills, the saved slash-command instructions the Omni AI assistant runs - name: Topics description: Retrieve topic information from models - name: Uploads description: Manage file uploads - name: Users description: Manage users - name: User attributes description: Manage user attribute definitions - name: User groups description: Manage user groups - name: User model roles description: Manage model and connection role assignments for users - name: User group model roles description: Manage model and connection role assignments for user groups - name: Uploads description: Manage CSV and spreadsheet uploads paths: /v1/apps/{documentId}/download: post: tags: - App downloads summary: Initiate app download description: > 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. operationId: appsDownload parameters: - $ref: '#/components/parameters/documentId' - $ref: '#/components/parameters/userId' requestBody: required: true content: application/json: schema: type: object properties: filename: type: string minLength: 1 maxLength: 255 description: >- Custom filename for the downloaded file, without extension. Defaults to the app name. example: territory-planner format: type: string enum: - png - pdf - xlsx - csv description: | 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 example: png required: - format additionalProperties: false examples: png: summary: Download as PNG value: format: png pdfWithFilename: summary: Download as PDF with a custom filename value: format: pdf filename: territory-planner responses: '200': description: Download job initiated successfully. content: application/json: schema: type: object properties: job_id: type: string format: uuid description: >- ID of the download job. Use this to poll for status and fetch the file. example: 123e4567-e89b-12d3-a456-426614174000 message: type: string description: Status message example: Download initiated successfully required: - job_id - message example: job_id: 123e4567-e89b-12d3-a456-426614174000 message: Download initiated successfully '400': description: >- Invalid request body, such as a missing or invalid `format`, or an unrecognized field. content: application/json: schema: $ref: '#/components/schemas/ApiError400' '401': description: Missing or invalid authentication. content: application/json: schema: $ref: '#/components/schemas/ApiError401' '403': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/ApiError403' '404': description: App not found, not published, archived, or the document has no app. content: application/json: schema: $ref: '#/components/schemas/ApiError404' '405': $ref: '#/components/responses/MethodNotAllowed' '409': description: A download of this app is already in progress for this user. content: application/json: schema: type: object properties: detail: type: string description: Error message existing_job_id: type: string format: uuid description: ID of the in-progress job status: type: string description: Status of the existing job example: detail: >- A download is already in progress for this app. Please wait for it to complete or check its status. existing_job_id: 123e4567-e89b-12d3-a456-426614174000 status: RENDERING '429': $ref: '#/components/responses/TooManyRequests' '500': description: The download job could not be started. components: parameters: documentId: name: documentId in: path required: true schema: type: string example: 12db1a0a description: The document's URL slug (e.g. `abc123`) or its canonical workbook UUID. userId: name: userId schema: type: string format: uuid required: false description: > **Organization API key required.** The membership ID of the user to act as. in: query schemas: ApiError400: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. status: type: integer description: HTTP status code of the error. example: 400 required: - detail - status ApiError401: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. example: 'Unauthorized: Missing or invalid API key' status: type: integer description: HTTP status code of the error. example: 401 required: - detail - status ApiError403: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. status: type: integer description: HTTP status code of the error. example: 403 required: - detail - status ApiError404: type: object properties: detail: type: string description: Human-readable error message describing what went wrong. status: type: integer description: HTTP status code of the error. example: 404 required: - detail - status Error: type: object properties: error: type: string description: HTTP response code for the error example: message: type: string description: Detailed error description example: responses: MethodNotAllowed: description: Method Not Allowed - Invalid HTTP method for this endpoint content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Too Many Requests - Rate limit exceeded (60 requests/minute) content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#token-types). Include in the `Authorization` header as: `Bearer YOUR_TOKEN` orgApiKey: type: http scheme: bearer bearerFormat: JWT description: > Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint. Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.