API#

spkrepo exposes a RESTful API and returns standard HTTP Status Codes in all responses. Data is returned as JSON.

Authentication#

To access the API, user must be registered, have the developer role and generated an API key from the profile page. The Authorization header is mandatory and must contain the API key as user with no password. If the authentication fails, a 401 Unauthorized is returned.

Warning

For security reasons, only one API key can be valid at a time. Should the API key be compromised, a new one can be generated from the profile page.

Errors#

In case of an ambiguous error, a detailed explanation is returned in JSON as message:

HTTP/1.1 422 UNPROCESSABLE ENTITY
Content-Length: 43
Content-Type: application/json

{
    "message": "Unknown architecture: myarch"
}

Endpoints#

POST /api/packages#

Post a SPK to the repository.

First a Package is created if not existing already, based on the name. Only users with package_admin role can create new packages, other users must be defined as maintainers to be able to continue.

Then a Version is created with its appropriate relationships if not existing already, based on the package and the version.

Lastly, a Build is created with its appropriate relationships and files saved on the filesystem.

Note

The created Build is not active by default

Example response:

HTTP/1.1 201 CREATED
Content-Length: 97

{
    "architectures": ["88f628x"],
    "firmware": "3.1-1594",
    "package": "btsync",
    "version": "1.4.103-10"
}
Status Codes:
POST /nas/#

Return the package catalog for a DSM/SRM device.

This is the endpoint DSM/SRM devices poll to discover packages available for their architecture, firmware, and language. The response shape depends on the build firmware number: builds below 5004 get a bare list, builds from 5004 up to (but not including) 40000 (DSM 6) additionally get a keyrings entry, and DSM 7+ builds (40000 and above) get packages only.

Query Parameters:

  • build – the device’s firmware build number (required)

  • arch – the device’s CPU architecture code, as reported by DSM/SRM (required)

  • language – the device’s language code, e.g. enu (required)

  • major – the DSM/SRM major version; inferred from build against known firmware if omitted

  • package_update_channel – set to beta to include beta packages (DSM < 7 only; ignored otherwise)

Example response (DSM 7+):

HTTP/1.1 200 OK
Content-Type: application/json

{
    "packages": [
        {
            "package": "git",
            "version": "2.1.2-4",
            "dname": "Git",
            "desc": "Distributed version control system.",
            "link": "https://example.com/.../git.v4.f64570%5Bx86_64%5D.spk",
            "thumbnail": ["https://example.com/nas/git/4/icon_72.png"],
            "qinst": true,
            "qupgrade": true,
            "qstart": false,
            "download_count": 1024,
            "recent_download_count": 87
        }
    ]
}
Status Codes:

  • 200 OK – catalog returned

  • 400 Bad Request – a required parameter is missing and the client did not request an HTML response (browsers are redirected instead)

  • 422 Unprocessable Entity – language, arch, or build is invalid

GET /nas/#

Return the package catalog for a DSM/SRM device.

This is the endpoint DSM/SRM devices poll to discover packages available for their architecture, firmware, and language. The response shape depends on the build firmware number: builds below 5004 get a bare list, builds from 5004 up to (but not including) 40000 (DSM 6) additionally get a keyrings entry, and DSM 7+ builds (40000 and above) get packages only.

Query Parameters:

  • build – the device’s firmware build number (required)

  • arch – the device’s CPU architecture code, as reported by DSM/SRM (required)

  • language – the device’s language code, e.g. enu (required)

  • major – the DSM/SRM major version; inferred from build against known firmware if omitted

  • package_update_channel – set to beta to include beta packages (DSM < 7 only; ignored otherwise)

Example response (DSM 7+):

HTTP/1.1 200 OK
Content-Type: application/json

{
    "packages": [
        {
            "package": "git",
            "version": "2.1.2-4",
            "dname": "Git",
            "desc": "Distributed version control system.",
            "link": "https://example.com/.../git.v4.f64570%5Bx86_64%5D.spk",
            "thumbnail": ["https://example.com/nas/git/4/icon_72.png"],
            "qinst": true,
            "qupgrade": true,
            "qstart": false,
            "download_count": 1024,
            "recent_download_count": 87
        }
    ]
}
Status Codes:

  • 200 OK – catalog returned

  • 400 Bad Request – a required parameter is missing and the client did not request an HTML response (browsers are redirected instead)

  • 422 Unprocessable Entity – language, arch, or build is invalid

GET /nas/(path: path)#

Serve a file (SPK, icon, or screenshot) from local storage.

Parameters:

  • path – relative file path under DATA_PATH, as returned by the catalog’s link/thumbnail/snapshot URLs

Status Codes: