The API

The Magic Folder Daemon provides an HTTP-based API. Most other magic-folder sub-commands interact with the Daemon by using this API. Other kinds of UIs or local programs can use the HTTP API directly or the Python command-line as they see fit.

Authentication

Users must be able to prove that they have read access to a local file stored in the Magic Folder Daemon configuration. This file is api_token at the root of a Magic Folder Daemon configuration.

A client wishing to communicate to the Magic Folder Daemon encodes the token in an Authorization: ` header sent to the Web server. This header’s value is `Bearer <token>. The api_token file is already encoded correctly for inclusion directly in this header.

Endpoints

In general, endpoints accept and return JSON data. The GET HTTP verb is used for retieving information and POST is used when modifying information. Details are shown in particular endpoints. Everything is rooted at /v1/.

GET /v1/magic-folder

List all magic-folders currently configured. An optional query-argument (?include_secret_information=1) may be included to request the secret capabilities to be included as well. Returns JSON like:

{
    "folders: [
        {
            "name": "funny-pictures",
            "author": {
                "name": "alice",
                "verify_key": "base32-encoded key",
            },
            "stash_path": "local/filesystem/path",
            "magic_path": "local/magic/folder/path",
            "poll_interval": 60,
            "is_admin": true
        }
    ]
}

If ?include_secret_information=1 is included then each magic-folder will also include author[“signing_key”], collective_dircap and upload_dircap keys.

GET /v1/snapshot

Lits all snapshots in all configured magic-folders. Returns JSON like:

{
    "folder-name": {
        "cat.jpeg": [
            {
                "parents": [],
                "identifier": "...",
                "type": "local",
                "author": {
                    "name": "bob",
                    "verify_key": "..."
                },
                "content-path": ".../bob-magic/funny-pictures/cat.jpeg"
            }
        ]
    }
}

GET /v1/snapshot/<folder-name>

Lits all snapshots in a particular magic-folders. Returns JSON like:

{
    "cat.jpeg": [
        {
            "parents": [],
            "identifier": "...",
            "type": "local",
            "author": {
                "name": "bob",
                "verify_key": "..."
            },
            "content-path": ".../bob-magic/funny-pictures/cat.jpeg"
        }
    ]
}

POST /v1/snapshot/<folder-name>?path=<file-name>

Creates a new snapshot for a particular file inside a particluar magic-folder. The POST body should be empty in this version of the API. The ?path= query argument is required. ?path= must point to a file inside the directory of the referenced magic-folder.