API Reference

API Reference

The main server API is exposed through:

public/api.php

The endpoint dispatches behavior through the action query parameter.

State-changing operations require the session CSRF token and same-origin validation.

Endpoint model

/api.php?action=<action>

The API returns JSON with an ok boolean and action-specific fields.

Actions

Action	Purpose
csrf	obtain the current CSRF token
me	return authentication state
register	create an account and log in
login	authenticate an account
logout	end the session
upload-init	create a resumable upload
upload-chunk	append a chunk at an explicit offset
upload-complete	finalize the upload and create an archive job
archive-step	process one pending ZIP archive, including protected/nested archives
build	build and package a V14 encrypted package
decrypt	restore a V14 package
packages	list managed packages for the current owner
access-token	issue a package download URL/token
set-expiry	change package expiration
revoke	revoke a package and its package access tokens
delete	permanently delete package storage and catalog metadata
security-status	return current V14 security metadata and control flags

CSRF bootstrap

GET /api.php?action=csrf

Response shape:

{
  "ok": true,
  "csrf": "..."
}

Account registration

POST /api.php?action=register
X-CSRF-Token: <token>
Content-Type: application/json

Body:

{
  "username": "example",
  "password": "..."
}

A successful response returns an account ID and a refreshed CSRF token.

The password is cleared from the controller buffer after use.

Login

{
  "username": "example",
  "password": "..."
}

Failed logins are rate-limited by both username/IP context and IP context.

Upload initialization

{
  "total_bytes": 123456,
  "sha256": "optional-64-hex-digest"
}

The server returns an upload state containing the upload identifier and progress information.

Upload chunk

The upload chunk action uses headers:

X-CSRF-Token: <token>
X-Upload-ID: <upload-id>
X-Upload-Offset: <byte-offset>

The request body is the raw chunk bytes.

The configured maximum chunk size is 8 MiB.

Upload completion

Body:

{
  "upload_id": "..."
}

When complete, the upload becomes the input to an archive-processing job.

Archive step

Body:

{
  "job_id": "...",
  "archive_id": "...",
  "password": "optional-zip-password"
}

The job is owner-bound and archive password attempts are rate-limited.

Build

Body:

{
  "job_id": "...",
  "project_name": "My Project",
  "password": "...",
  "pattern": "...",
  "create_recovery": true
}

The server requires the archive job to be in the ready_to_build state.

On success, the response includes:

• package ID
• download token
• download URL
• package statistics
• recovery key, when requested
• SECURE-PKG-V14 format identifier

The recovery key is a one-time sensitive output and should be copied to a secure location immediately.

Decrypt

Body:

{
  "package_id": "...",
  "password": "...",
  "pattern": "...",
  "recovery_key": "optional"
}

When recovery_key is supplied, the server uses the recovery key slot instead of validating the password/pattern.

Package availability is checked against catalog expiration and revocation state before restore.

On success the API returns a short-lived restore download URL.

Package listing

GET /api.php?action=packages

The list is filtered by the current owner and includes:

• package ID
• creation time
• revoked state
• expiration time
• format identifier

The package name itself is not returned in plaintext by the current controller listing response.

Download access token

Body:

{
  "package_id": "..."
}

The action verifies ownership and package revocation status before issuing a short-lived download token.

Expiration

Body:

{
  "package_id": "...",
  "expires_in": 0
}

expires_in = 0 clears expiration. Nonzero values are clamped to an application-defined safe range with a minimum future lifetime and a maximum of one year.

Revoke

Body:

{
  "package_id": "..."
}

Revocation updates catalog state and removes outstanding package access tokens.

Delete

Body:

{
  "package_id": "..."
}

The controller removes:

• portable .spkg14 storage
• package directory storage, if present
• download tokens
• catalog metadata

This is a destructive operation.

Security status

The security-status action reports the active V14 format and controls, including:

• CSRF
• same-origin checks
• rate limiting
• resumable uploads
• tamper-evident audit
• package ownership
• header binding
• external key wrapping
• no-overwrite restore

Request size policy

JSON requests are bounded at 2 MiB by the request parser. Login-related bodies have a stricter application configuration ceiling of 64 KiB.

V13 API

The legacy browser compatibility path is separate:

public/api-v13.php

Its actions include csrf, descriptor, init, status, chunk, finalize, and delete-upload.

V13 upload handling must not be interpreted as the V14 package protocol.