Documents

The /api/v1/documents endpoint group gives access to the Skailer document storage: folders, document metadata, and the files themselves.

Folders and document types

Every document lives in a folder, and the folder type determines who the document belongs to:

Folder type	Meaning
`organization`	Company-wide documents (policies, regulations, templates)
`employee`	Documents of a specific employee (contracts, certificates, scans)

For a document in an employee folder the employee_id field holds the employee it belongs to. For an organization document employee_id is null.

Get all folders by type

GET /api/v1/documents/folders/{folder_type}

folder_type is organization or employee.

Response fields (per folder):

Field	Type	Description
`id`	integer	Folder ID
`title`	string	Folder name
`type`	string	Folder type: `organization`, `employee`
`document_count`	integer	Number of documents in the folder

Permissions: for type=organization the response contains folders granted by the folder view/edit rules, or all of them with settings_document_folders=edit. For type=employee it requires settings_document_folders=edit.

Response example:

[
  {
    "id": 12,
    "title": "Company policies",
    "type": "organization",
    "document_count": 8
  }
]

Get all folders of an employee

GET /api/v1/documents/employees/{employee_id}/folders

Returns the employee type folders available for the given employee. The response fields are the same as above.

Permissions: settings_document_folders=edit, settings_roles_permissions=edit, or employee_folder_permissions=view on the folder.

Search documents

POST /api/v1/documents/search

Returns a paginated list of documents.

Request parameters:

Field	Type	Description
`folder_id`	integer	Search inside one specific folder
`folder_type`	string	Search across all accessible folders of the type: `organization`, `employee`
`employee_id`	integer	Filter by the employee the documents belong to
`title`	string	Filter by document title
`page_number`	integer	Page number, starts at `1`

Important: exactly one of folder_id or folder_type must be set. Passing both, or neither, returns 422.

Response fields (per document):

Field	Type	Description
`id`	integer	Document ID
`title`	string	Document title
`employee_id`	integer \| null	Employee the document belongs to; `null` for an organization document
`uploaded_by_employee_id`	integer	Employee who uploaded the document
`folder`	object	Folder: `id`, `title`, `type`
`file`	object	File: `name`, `file_type`, `size`, `mime_type`, `uuid`, `url`
`datetime_created_at`	string	Creation timestamp
`datetime_updated_at`	string	Last update timestamp

Permissions: folder type=organization requires settings_document_folders=edit or access granted by the folder view/edit rules. Folder type=employee requires employee_folder_permissions=view; searching with folder_type=employee also requires settings_document_folders=edit.

Request example:

{
  "folder_id": 12,
  "title": "contract",
  "page_number": 1
}

Response example:

{
  "items": [
    {
      "id": 4501,
      "title": "Employment contract",
      "employee_id": 123,
      "uploaded_by_employee_id": 7,
      "folder": {
        "id": 12,
        "title": "Contracts",
        "type": "employee"
      },
      "file": {
        "name": "employment_contract.pdf",
        "file_type": "employee_documents",
        "size": 148213,
        "mime_type": "application/pdf",
        "uuid": "3f1c2b90-5d1a-4c8e-9a77-0b2d61f4e8aa",
        "url": null
      },
      "datetime_created_at": "2026-05-14 09:12:00",
      "datetime_updated_at": "2026-05-14 09:12:00"
    }
  ],
  "metadata": {
    "page_number": 1,
    "total_pages": 1,
    "items": 1,
    "items_per_page": 20,
    "total_items": 1
  }
}

Upload a document

POST /api/v1/documents/upload

Uploads a file and creates a document from it in a single request. The body is multipart/form-data.

Request parameters:

Field	Type	Description
`file`	file	The file to upload (required)
`folder_id`	integer	Target folder ID (required)
`employee_id`	integer	Employee the document belongs to; omit for an organization document

The document title is taken from the file name without the extension and can be changed later via PUT /api/v1/documents/{document_id}.

Permissions: folder type=organization requires settings_document_folders=edit or access granted by the folder edit rules. Folder type=employee requires employee_folder_permissions=edit.

Request example:

curl -X POST 'https://<api-domain>/api/v1/documents/upload' \
  -H 'Authorization: Bearer <your_access_token>' \
  -F 'folder_id=12' \
  -F 'employee_id=123' \
  -F 'file=@employment_contract.pdf'

Returns the created document in the same format as search.

Get a document by id

GET /api/v1/documents/{document_id}

Returns the document metadata.

Download the document file

GET /api/v1/documents/{document_id}/download

Returns the original file as a binary response. The file name is passed in the Content-Disposition header.

Permissions: the same as for viewing the document.

Rename a document

PUT /api/v1/documents/{document_id}

Changes the document title. The file itself is not replaced.

Request parameters:

Field	Type	Description
`title`	string	New document title (required)

Permissions: folder type=organization requires settings_document_folders=edit or access granted by the folder edit rules. Folder type=employee requires employee_folder_permissions=edit.

Request example:

{
  "title": "Employment contract 2026"
}

Delete a document

DELETE /api/v1/documents/{document_id}

Deletes the document. Returns {"success": true}.

Permissions: folder type=organization requires settings_document_folders=edit or access granted by the folder edit rules. Folder type=employee requires employee_folder_permissions=edit.

Typical integration scenario

Goal: push signed contracts from an external document flow into an employee’s folder.

Find the employee’s folder (once per employee, cache the result):
```
GET /api/v1/documents/employees/{employee_id}/folders
```
Check whether the document already exists to avoid duplicates:
```
POST /api/v1/documents/search
```
Pass folder_id and title.
Upload the file:
```
POST /api/v1/documents/upload
```
Pass folder_id, employee_id, and file.
Set the final title if the file name differs from the desired title:
```
PUT /api/v1/documents/{document_id}
```

Tip: to sync in the other direction - pull documents out of Skailer - iterate over the pages of POST /api/v1/documents/search with folder_type, then fetch each file via GET /api/v1/documents/{document_id}/download.