Pydio 8 - REST API (v2)
Pydio Core (PHP) - Api V2
Pydio API v2 is following the standards and providing various endpoints to manage both your files & folders and all the Pydio administrative data. It exposes the internal data of Pydio using the various HTTP methods for CRUD operations: GET, POST, PATCH, DELETE.
API v2 is accessible on your pydio installation under the /api/v2/ URI. That is, if pydio installed on https://yourdomain.tld/pydio, the endpoints exposed here are available under https://yourdomain.tld/pydio/api/v2.
Please note that some actions are not (yet) available through this API, and you may have to use API V1 (wich is available by default as well on your installation).
Basic Authentication
Authentication against the API is done via HTTP Basic-Authentication. The standard users credentials (admin / password) can be used to login.
You can also use users Tokens instead as generated in the "My Api Keys" panel of My Account.
Request & Parameters
Depending on the request, most parameters are passed as GET or POST key values. Provisioning API now introduce many queries that will take JSON objects as input, see the docs below for the format.
Getting JSON responses
Historically, Pydio has been using XML extensively for requests responses format. Since Pydio 7, this API v2 will mostly support both JSON and XML format as a response format. Just pass an additional format=json to the parameters of the query.
The File API's allow you to list, create, update or delete files inside any workspace. It is split into two main endpoints:
- /fs : is used to list, create files and folders, rename them, etc.. via the various HTTP methods.
- /io : is used to manage actual files data, i.e. upload or download data via GET / PUT methods.
These endpoints generally require a {path} parameter that MUST BE composed of the target workspace identifier and the actual path of the file inside the workspace. The workspace is either its "slug" (the part you see in the url when you are browsing pydio, without the ws- prefix) or its real ID which is a 32 characters long string. Only default "Common Files" and "My Files" have an id of respectively "0" and "1".
For example, if you want to list folder /my-folder inside your personal folder, you can use : https://yourserver.tld/pydio/api/v2/fs/my-files/my-folder?children=dfz
The User Account and Workspaces API allows the listing of the configuration of the currently logged user. This means, that it will for example list the workspace accessible to the user with wich you have logged to the API.
It is not the right API to browse users information when logged in as admin.
The Provisioning API provides a full rewrite of the previous administration API in a much clearer and standard-aware approach. All endpoints start with /api/v2/admin/
- /admin/people : manage users and groups
- /admin/workspaces: manage workspaces and there "meta-features"
- /admin/roles : manage roles (either admin roles or "users" roles or "groups" roles).
See section below for more details.
Pydio Core API V1
Pydio API v1 is providing a REST access to all the actions exposed by the installed Pydio Plugins on your instance. Furthermore, it also describe a way to trigger these actions directly via Command Line.
API v1 is accessible on your pydio installation under the /api/v1/ URI. That is, if pydio installed on https://yourdomain.tld/pydio, the endpoints exposed here are available under https://yourdomain.tld/pydio/api/v1.
Since Pydio 7, you can also use the API V2, which is more compliant to the REST standards, but some actions may not be available by default and still require the use of Api V1.
Authentication
Authentication against the API is done via HTTP Basic-Authentication. The standard users credentials (admin / password) can be used to login.
You can also use users Tokens instead as generated in the "My Api Keys" panel of My Account.
Request & Responses Format
Depending on the request, most parameters are passed as GET or POST key values. Most response format are using XML.
Finding the right workspaceId
Expected workspace ID can be either the internal 32-characters long string identifing a workspace in Pydio, or the workspace "slug" which is a more human-readable identifier. You can typically guess the slug by looking at your browser URL when navigating inside a workspace : URL is built with https://yourserver.com/pydio/ws-
Reserved Workspace identifiers
Please note that default workspaces My Files and Common Files have a specific internal identifier which is "1" and "0" respectively.
For all admin related actions (that are active in Pydio only when you are logged in the "Settings" panel), you can use the settings workspace ID.
For workspace-independant actions, like listing the workspaces accessible to the currently logged user, you can use pydio as workspace ID.
Actions
Actions are defined in plugins manifest.xml files. They are "endpoints" that each plugin can contribute to the application. Typically, the FS Storage Driver (access.fs) will provide all actions like "ls", "mkdir", "mkfile", "rename", etc...
Http Access
Every request will always start with
https://yourserver.com/pydio/api/<workspaceId>/<actionName>/[optional_path_parameters]
The path parameter may depend on how the rest point is defined in the manifest. For example, to list the content of a given folder inside a workspace "marketing", you would use
https://yourserver.com/pydio/api/marketing/ls/path/to/folder
You may have to add some query string parameters, e.g.
https://yourserver.com/pydio/api/marketing/ls/path/to/folder?format=json
Command Line
By logging on your Pydio server and going inside the root of your installation, you can trigger any API command using the following syntax:
$ php cmd.php -u=user -r=workspaceId [-p=password] [-a=action] [[--param1=value1 --param2=value2]]
User/password can be any valid Pydio user credentials. If you do not provide a password parameter, you will be prompted when executing the command. In a similar manner, if you do not provide an "action" parameter, you will be prompted with an auto-completable command line to find the proper action.
The paramX/valueX couples may vary depending on the action you want to trigger. Make sure to use double-dashes before these optional parameters names, whereas the u, r, a and p options must start with a simple dash.