bacommon.restapi package¶

Public REST APIs for Ballistica.

Submodules¶

bacommon.restapi.v1 module¶

Public schema for the Ballistica master-server REST API v1.

All endpoints require an Authorization: Bearer <key> header. Responses are JSON; any non-200 response has an ErrorResponse body regardless of which endpoint was called.

See Endpoint for the full list of available endpoints and their usage.

Example — fetch info for the authenticated account:

curl -H 'Authorization: Bearer <your-api-key>' https://www.ballistica.net/api/v1/accounts/me

The dataclasses here (e.g. AccountResponse) serve as schema documentation and can also be used directly with efro.dataclassio to parse or construct values:

from efro.dataclassio import dataclass_from_json
from bacommon.restapi.v1 import AccountResponse

account = dataclass_from_json(AccountResponse, response_json_str)

class bacommon.restapi.v1.AccountResponse(id: str, tag: str, create_time: datetime, last_active_day: date | None, total_active_days: int)[source]¶

Bases: object

Public info for a single account.

Returned by Endpoint.ACCOUNT.

create_time: datetime¶: When the account was created.

id: str¶: Unique account ID (e.g. 'a-12345').

last_active_day: date | None¶: The most recent day the account was active, or None if unknown.

tag: str¶: Globally unique display name for the account.

total_active_days: int¶: Number of distinct days the account has been active.

class bacommon.restapi.v1.Endpoint(*values)[source]¶

Bases: StrEnum

Public REST API v1 endpoint paths.

Each value is the URL path for an endpoint; see its description for the HTTP method, parameters, and response type.

Tip: use str.format() to fill in path parameters:

url = Endpoint.ACCOUNT.format(account_id='a-1')

ACCOUNT = '/api/v1/accounts/{account_id}'¶: GET — fetch public info for a single account. Returns AccountResponse. Pass 'me' as account_id to refer to the authenticated account.

WORKSPACE = '/api/v1/workspaces/{workspace_id}'¶

GET — fetch metadata for a single workspace. Returns WorkspaceResponse.

PATCH — rename the workspace. JSON body: {"name": "New Name"}. Returns WorkspaceResponse.

DELETE — delete the workspace (creates a 30-day backup internally). Returns HTTP 204.

WORKSPACES = '/api/v1/workspaces'¶

GET — list all workspaces for the authenticated account. Returns WorkspacesResponse.

POST — create a new workspace. Optional JSON body: {"name": "My Workspace"}. Returns WorkspaceResponse with HTTP 201.

WORKSPACE_FILE = '/api/v1/workspaces/{workspace_id}/files/{file_path}'¶

GET — download a file. Returns raw file bytes.

PUT — upload or replace a file. Raw body = file contents. Parent directories are created automatically. Returns HTTP 204.

DELETE — delete a file or directory. Returns HTTP 204.

POST — perform a structured file operation. JSON body: {"op": "mkdir"}, {"op": "move", "dest": "path"}, or {"op": "copy", "dest": "path"}. Returns HTTP 204.

WORKSPACE_FILES = '/api/v1/workspaces/{workspace_id}/files'¶: GET — flat listing of all files and directories in the workspace. Returns WorkspaceFilesResponse.

class bacommon.restapi.v1.ErrorResponse(error: str, message: str)[source]¶

Bases: object

Returned by all Endpoint members on any non-200 response.

The HTTP status code conveys the specific failure type.

error: str¶: Machine-readable error code (e.g. 'not_found', 'unauthorized').

message: str¶: Human-readable description of the error.

class bacommon.restapi.v1.WorkspaceEntryResponse(path: str, type: WorkspaceEntryType, size: int | None, modified_time: datetime | None)[source]¶