Skip to content

Generate File Download Links Examples

The following examples provide JSON data which may be used with the jobs endpoints as described in Usage. These examples are specific to the generate file download links API, to be used with the /jobs/generate-file-download-links endpoint which is fully described in the OpenAPI Specification.

A Basic Request

Submit a batch of file UUIDs to resolve into presigned download URLs. File UUIDs are returned by feed endpoints such as the RFI Responses feed (document_file_uuids on responses, attachment_file_uuids on questions).

A maximum of 50 file UUIDs may be submitted per request.

{
  "file_uuids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ]
}

Completed Job

Once the job reaches COMPLETED status, the detail field contains the resolved download URLs in data and any failures in errors.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "GENERATE_FILE_DOWNLOAD_LINKS",
  "status": "COMPLETED",
  "created": "2026-04-23T12:00:00.000001Z",
  "detail": {
    "data": [
      {
        "file_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "file_name": "ISO_Certificate.pdf",
        "download_url": "https://files.keelvar.app/a1b2c3d4-e5f6-7890-abcd-ef1234567890?...snip..."
      },
      {
        "file_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "file_name": "Supplier_Questionnaire.xlsx",
        "download_url": "https://files.keelvar.app/b2c3d4e5-f6a7-8901-bcde-f12345678901?...snip..."
      }
    ],
    "errors": []
  }
}

Partial Failure

If some file UUIDs cannot be resolved (e.g. the file does not exist or belongs to a different organisation), the job still completes. Successfully resolved files appear in data and failures appear in errors.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "GENERATE_FILE_DOWNLOAD_LINKS",
  "status": "COMPLETED",
  "created": "2026-04-23T12:00:00.000001Z",
  "detail": {
    "data": [
      {
        "file_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "file_name": "ISO_Certificate.pdf",
        "download_url": "https://files.keelvar.app/a1b2c3d4-e5f6-7890-abcd-ef1234567890?...snip..."
      }
    ],
    "errors": [
      {
        "file_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "error": "not_found"
      }
    ]
  }
}

Note on download_url

The download_url populated in the job detail field is a pre-signed URL that expires after 60 seconds. Downloads must begin promptly once the job completes. Any attempt to use the URL after expiry will result in an HTTP 403 error. If the URLs have expired, submit a new job to generate fresh links.

Typical Consumer Workflow

  1. Fetch file UUIDs from a feed endpoint (e.g. GET /api/feeds/rfi-responses?include=questions)
  2. Submit a generate-file-download-links job: POST /api/jobs/generate-file-download-links
  3. Poll GET /api/jobs/{id} until the job reaches COMPLETED status
  4. Download files using the URLs in the detail.data array