Introduction

The Downloads API lets you manage downloadable resources (files or external URLs) that belong to your company. Each download is always scoped to the authenticated user’s company, based on the company_id attached to the bearer token.

A download can be:

• A file you upload (stored and served by your app), or
• A URL pointing to an external resource.

The content_type field determines which one is used.

Get all company downloads

This endpoint retrieves all downloads associated with the authenticated user’s company. The company_id is taken from the user attached to the bearer token, so only downloads for that company are returned.

Parameters

• No query parameters are required.
• The company_id is inferred from the authenticated user.

{
  "data": [
    {
      "id": "413",
      "attributes": {
        "name": "Employee Handbook",
        "description": "Latest version of the employee handbook.",
        "upload_type": "file",
        "download_url": "https://my-online-offer.com/storage/downloads/handbook.pdf",
        "original_name": "employee-handbook.pdf",
        "extension": "pdf",
        "is_visible": true,
        "created_at": "2025-12-11T08:00:00.000000Z",
        "updated_at": "2025-12-11T08:00:00.000000Z"
      },
      "relationships": {
        "user": {
          "id": 42,
          "name": "Jane Doe",
          "email": "jane@example.com"
        },
        "company": {
          "id": 54,
          "name": "Example Company A/S"
        }
      }
    }
    // more downloads...
  ]
}

Get a single download

This endpoint retrieves a single download by its ID.

Before the request is processed, a security check verifies that the requested download belongs to the same company as the authenticated user. If it does not, the request is rejected with an unauthorized error.

Parameters

• download_id (string, path parameter): The id of the download you want to retrieve.

Example response

{
  "id": "413",
  "attributes": {
    "name": "Employee Handbook",
    "description": "Latest version of the employee handbook.",
    "upload_type": "file",
    "download_url": "https://your-app.test/storage/downloads/handbook.pdf",
    "original_name": "employee-handbook.pdf",
    "extension": "pdf",
    "is_visible": true,
    "created_at": "2025-12-11T08:00:00.000000Z",
    "updated_at": "2025-12-11T08:00:00.000000Z"
  },
  "relationships": {
    "user": {
      "id": 42,
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "company": {
      "id": 54,
      "name": "Example Company A/S"
    }
  }
}

Store a new download

This endpoint creates a new download for the authenticated user’s company. The behavior depends on the content_type.

• content_type = file → A file must be uploaded, it is stored, and the stored path is saved.
• content_type = url → An external URL must be provided, and no file is stored.
• content_type = base64 → An base64 must be provided, and the stored path is saved.

Request body

Use multipart/form-data when uploading a file. The request is validated with the following rules.

• name (string, required, max: 255)
• description (string, nullable)
• is_visible (boolean, required)
• content_type (string, required, one of: url, file)

Depending on content_type

• If content_type = url

  • url (string, required, valid URL)
  • file (ignored)

• If content_type = file

  • file (required, uploaded file)
  • url (ignored)

• If content_type = base64

  • base64_content (required, content of base64)
  • url (ignored)
  • file (ignored)

If the conditions have all been passed, the response body looks like the following.

{
  "id": "413",
  "attributes": {
    "name": "Employee Handbook",
    "description": "Latest employee handbook.",
    "upload_type": "file",
    "download_url": "https://your-app.test/storage/downloads/employee-handbook.pdf",
    "original_name": "employee-handbook.pdf",
    "extension": "pdf",
    "is_visible": true,
    "created_at": "2025-12-11T08:00:00.000000Z",
    "updated_at": "2025-12-11T08:00:00.000000Z"
  },
  "relationships": {
    "user": {
      "id": 42,
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "company": {
      "id": 54,
      "name": "Example Company A/S"
    }
  }
}

Update a single download

This endpoint updates an existing download. You can:

• Update only metadata (e.g. name, description, visibility), without changing the upload type.
• Change the content_type from url → file or file → url or to base64.
• Replace an existing file with a new upload.
• Replace an existing URL with a new URL.

Request body

Fields are optional but, when present, are validated as the following.

• name (required, string, max:255)
• description (nullable, string)
• is_visible (required, boolean)
• content_type (required, value is either url, file or base64)

Conditional fields.

• url

  • If present: nullable, url
  • If content_type is url (from the request), the URL is treated as required.
  • If a url is sent but content_type is not url, validation fails.

• file:

  • If present: nullable, file
  • If content_type is file (from the request), the file is treated as required.
  • If a file is sent but content_type is not file, validation fails.

• base64:

  • If present: nullable, base64
  • If content_type is base64 (from the request), the base64_content is treated as required.
  • If a base64_content is sent but content_type is not base64, validation fails.

The response uses the same structure as any other endpoint.

{
  "id": "413",
  "attributes": {
    "name": "Employee Handbook (2026 Edition)",
    "description": "Updated for 2026.",
    "upload_type": "file",
    "download_url": "https://your-app.test/storage/downloads/new-document.pdf",
    "original_name": "new-document.pdf",
    "extension": "pdf",
    "is_visible": true,
    "created_at": "2025-12-11T08:00:00.000000Z",
    "updated_at": "2025-12-11T08:10:00.000000Z"
  },
  "relationships": {
    "user": {
      "id": 42,
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "company": {
      "id": 54,
      "name": "Example Company A/S"
    }
  }
}