Files and folders

The session’s folder: browse, read, search, preview and change its files; choose folders for new sessions. Paths are relative to /api/v1.

GET /projects

List the project folders a session may open (ids and names, never absolute paths).

Answers The JSON envelope.

Errors1

Code	Status	Meaning
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /workspace-browser

Browse the folders of this computer, to choose the one a session works in.

Query

path

The folder to list (once at most); without it, the starting points.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
WORKSPACE_NOT_AVAILABLE	422	The folder is not available: check that it exists and that TALOS can work in it.

Any operation can also answer the common errors.

GET /frequent-dirs

Folders used often, with their absolute paths, as suggestions for a session’s folder (from the history of sessions).

Answers The JSON envelope.

Errors1

Code	Status	Meaning
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /workspace-info

A portrait of a folder before a session opens it: how many files, whether it is a repository root, its branch, unsaved changes and nested repositories (the scan has a declared ceiling).

Query

pathrequired

the folder (up to 4096 characters).

Answers The JSON envelope.

Errors1

Code	Status	Meaning
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /workspace-launches

Hand a folder to TALOS from outside the window (the launcher), to start a session on it; answers a launch id.

Used by the TALOS launcher; it carries its token in the x-talos-launcher-token header.

Body

percorsorequired

The folder, as an absolute path.

Headers

x-talos-launcher-token

Answers The JSON envelope.

Errors1

Code	Status	Meaning
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /workspace-browser/folders

Create a folder while choosing where a session works.

Body

parentPathrequired

The folder to create it in.

namerequired

The new folder’s name.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
WORKSPACE_NOT_AVAILABLE	422	The folder is not available: check that it exists and that TALOS can work in it.

Any operation can also answer the common errors.

GET /workspace-launches/{launchId}

Read a pending launch: the folder it carries, to confirm before the session starts.

Path

launchId

The launch.

Answers The JSON envelope.

Errors1

Code	Status	Meaning
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /projects/{projectId}/tree

Preview the files of a project folder before a session opens it.

Path

projectId

The project folder.

Query

percorso

A subfolder, relative to the project (default: its root).

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/tree

The files of the session’s folder, one level at a time.

Path

sessionId

The session.

Query

percorso

A subfolder, relative to the session’s folder (default: its root).

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/tree/file

Open a file of the session’s folder, to show it in the window.

Path

sessionId

The session.

Query

percorsorequired

the file, relative to the session’s folder.

Answers The JSON envelope.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/tree/search

Search the files of the session’s folder by name; the answer says when it was cut short, and which folders were skipped.

Path

sessionId

The session.

Query

qrequired

the text to look for.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/file

Download a file of the session’s folder, as an attachment (sandboxed, never rendered by the app).

Path

sessionId

The session.

Query

percorsorequired

the file, relative to the session’s folder.

Answers The bytes themselves (a file or an image), not JSON.

POST /sessions/{sessionId}/pagine

Get an address to show an HTML page of the session’s folder, or a library item, inside the window.

The body is { percorso } or { voceId }. The server checks the file exists, is inside the session’s folder and is a page, and answers an address with a fresh pass (frames do not carry the cookie).

Path

sessionId

The session.

Body

voceId

Or a library item.

percorso

The page, relative to the session’s folder.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /pagine/{pageId}/{path}

Serve a page, and the files next to it, by the pass POST …/pagine gave (no cookie needed, never outside the page’s folder).

The type comes from the extension, with nosniff; an unknown type is application/octet-stream. The query string is ignored (pages use it for caching).

Path

pageId

The page’s pass, from POST …/pagine.

path

The file, inside the page’s folder.

Answers The bytes themselves (a file or an image), not JSON.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/file/anteprima

Preview a PDF of the session’s folder inline, sandboxed (the type is decided by the bytes: a file that does not start with %PDF- is 404).

Path

sessionId

The session.

Query

percorsorequired

the file, relative to the session’s folder.

Answers The bytes themselves (a file or an image), not JSON.

Errors1

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.

Any operation can also answer the common errors.

GET /lettore/ospite

The sandboxed guest page in which Word documents and presentations are rendered for preview (the window sends it the bytes).

Answers The bytes themselves (a file or an image), not JSON.

POST /sessions/{sessionId}/tree/rename

Rename a file or folder of the session’s folder.

Path

sessionId

The session.

Body

percorsorequired

The file or folder.

nuovoNomerequired

The new name.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/tree/delete

Delete a file or folder of the session’s folder.

Path

sessionId

The session.

Body

percorsorequired

The file or folder.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/tree/reveal

Show a file in the file manager of this computer.

Path

sessionId

The session.

Body

percorsorequired

The file.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/tree/open

Open a folder in the file manager of this computer.

Path

sessionId

The session.

Body

percorsorequired

The folder; an empty string is the session’s folder itself.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/tree/move

Move a file or folder into another folder of the session’s folder.

Path

sessionId

The session.

Body

percorsorequired

What to move.

cartellaDestinazionerequired

Where to.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/tree/copy

Duplicate a file or folder in the same place, named like a file manager does: “name (copia).ext”, then “(copia 2)” and so on.

Path

sessionId

The session.

Body

percorsorequired

What to copy.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/tree/create

Create a file or a folder.

Path

sessionId

The session.

Body

percorsoBaserequired

The folder to create it in.

nomerequired

Its name.

tiporequired

file or cartella (folder).

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.