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/api/downloads

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/downloads/{download_id}

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"
    }
  }
}
POST/downloads

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.

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 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"
    }
  }
}
PATCH/PUT/downloads/{download_id}

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.
  • 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 or file)

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.

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"
    }
  }
}

Was this page helpful?