Skip to main content
Square Cloud Banner

squarecloud-api

The official Python SDK for the Square Cloud API.

PyPI Version License Downloads
  • Zero runtime dependencies, and one reused connection per thread.
  • Runs on Python 3.11+, with a sync SquareCloud client, an async AsyncSquareCloud client and typed responses.
  • Covers all 69 operations of the Square Cloud API, checked against the pinned OpenAPI spec on every CI run.
  • Uploads and snapshot downloads stream from and to disk, and realtime logs and status arrive through an iterator or async for.
  • One error type, SquareCloudAPIError, for every API error, network failure and failed local check.

Documentation · Releases · Migration guide

Installation

pip install squarecloud-api
uv add squarecloud-api
poetry add squarecloud-api

Requires Python 3.11 or newer.

API key

Create one at squarecloud.app/account/security. You can limit a key to scopes, such as apps:read or apps:deploy, and to specific applications or databases. A call outside those limits raises SquareCloudAPIError with 403 MISSING_SCOPE or RESOURCE_NOT_ALLOWED, and list calls return only the resources the key can see. An unknown, revoked or expired key gets 401 ACCESS_DENIED.

Quick start

import os
from squarecloud import SquareCloud

with SquareCloud(os.environ['SQUARECLOUD_API_KEY']) as client:
    me = client.account.me()
    print(me['user']['name'], [app['name'] for app in me['applications']])

    app_id = me['applications'][0]['id']
    client.apps.restart(app_id)
    print(client.apps.logs(app_id))

The same calls with await:

import asyncio
import os

from squarecloud import AsyncSquareCloud


async def main() -> None:
    async with AsyncSquareCloud(os.environ['SQUARECLOUD_API_KEY']) as client:
        statuses = await client.apps.status_all()
        print([s['id'] for s in statuses if s['running']])


asyncio.run(main())

More in examples/: apps, realtime, snapshots, databases, workspaces, async client.

Configuration

import os

from squarecloud import BASE_URL, SquareCloud, __version__

client = SquareCloud(
    os.environ['SQUARECLOUD_API_KEY'],
    base_url=BASE_URL,  # the options are keyword-only; these are the defaults
    timeout=30.0,
    max_retries=2,
    transport=None,
    user_agent=f'squarecloud-sdk-py/{__version__}',
)
Option Default Notes
api_key required Sent as is in Authorization. An empty or blank key raises ValueError.
base_url BASE_URL = https://api.squarecloud.app/v2 A trailing / is removed.
timeout 30.0 Seconds each connect, send or read may take. A value of 0 or less disables every timeout, including the 120-second minimum of slow calls. See Retries, timeouts and rate limits.
max_retries 2 A negative value counts as 0.
transport HTTPTransport(timeout) Your own HTTP transport. See Custom transport.
user_agent squarecloud-sdk-py/<version> Replaces the whole User-Agent header.

AsyncSquareCloud takes the same arguments. Both clients are safe to share between threads. Call close(), or use with or async with, to close their connections. The version is squarecloud.__version__.

Custom transport

transport= accepts any callable transport(method, url, headers, body, timeout, stream) that returns an object with status, read(), readline() and close(). An http.client.HTTPResponse already has that shape. Use it for proxies, tracing or tests.

  • body is bytes, an iterable of bytes chunks with Content-Length already in headers, or None.
  • timeout is how many seconds each connect, send or read may take, raised to 120 for the calls the API holds open. It is None for uploads, large file writes and the realtime feed, so bound their connect yourself.
  • stream means the caller reads the body bit by bit and may call close() from another thread to stop it.

The default HTTPTransport(timeout) bounds that connect for you. It asks for compressed responses on every call except the streamed ones, which are the realtime feed and snapshot downloads.

Logging

The SDK logs each request at DEBUG on the squarecloud logger, with the method, path and status but never a body or a key. It attaches only a NullHandler:

import logging

logging.basicConfig()
logging.getLogger('squarecloud').setLevel(logging.DEBUG)

API

Every application id can also be the composite '<appId>-<workspaceId>', to act on an application someone shared with you through a workspace. Optional arguments are keyword-only, except the path of apps.files.list.

Group Methods
account me(), snapshots(*, scope=None)
service status(), for which the API does not check the key, although the client still needs a non-empty one
ai chat(request), OpenAI-compatible and without streaming
apps create(file), get(id), delete(id), status_all(*, workspace_id=None), status(id, *, raw=False), start(id), stop(id), restart(id), logs(id), metrics(id, *, range=None), realtime(id), domains(), load_balancers(), commit(id, file, *, path=None, filename=None)
apps.deploys set_webhook(id, access_token), link_github_app(id, repository, branch), unlink_github_app(id), list(id), current(id)
apps.envs get(id), set(id, envs), replace(id, envs), delete(id, keys)
apps.files list(id, path=None), read(id, path) → bytes, write(id, path, content), move(id, path, to), delete(id, path)
apps.snapshots list(id), create(id), restore(id, name, version_id) → {'pending': bool}, restore_state(id)
apps.network analytics(id, start, end, **filters), errors(id, start, end, *, include_4xx=False), logs(id, start, end), performance(id, start, end), dns(id), set_domain(id, domain), purge_cache(id)
databases create(name, *, type, version, memory), get(id), update(id, *, name=None, ram=None), delete(id), start(id), stop(id), status(id, *, raw=False), metrics(id, *, range=None), status_all(), certificate(id), reset_credentials(id, 'password' | 'certificate') → the new password, or ''
databases.snapshots list(id), create(id), restore(id, name, version_id) → {'pending': bool}, restore_state(id)
workspaces create(name), list(), get(id), delete(id), leave(id)
workspaces.members add(workspace_id, code, group), update(workspace_id, member_id, group), remove(workspace_id, member_id), invite_code()
workspaces.apps add(workspace_id, app_id), remove(workspace_id, app_id)
client download_snapshot(url, dest), close()

AsyncSquareCloud has the same groups and methods, and each one returns a coroutine that runs the sync call in a worker thread. The exceptions are close(), which is sync, and apps.realtime(id), which returns an AsyncRealtime for async for.

Responses are TypedDicts from squarecloud.types. They are plain dicts that keep any field the API adds later. Field names are the API's own, such as created_at, content_type and include_4xx, so the API reference applies as is. A string result is never None. It is '' when the API sends nothing.

  • start and end take an ISO 8601 string, which is sent as is, or a datetime, which is sent in UTC. A naive datetime is read as local time.
  • The analytics filters are keyword-only: country, ip, path, status, os, browser, protocol, referer, provider, content_type and bot. provider takes the 'NAME (ASN)' form that the providers buckets report, such as provider='GOOGLE (15169)'. An invalid filter is 400 INVALID_FILTER.
  • apps.network.analytics, errors and performance return None for a window with no traffic.
  • metrics() returns points newest first. By default it covers 24 hours with one point every 5 minutes, or every 10 minutes for applications below 512 MB. range='7d' gives hourly points with the hour's peaks in cpu_max and ram_max on Pro and Enterprise plans, for databases and for applications of 512 MB or more. Other plans and smaller applications get the 24-hour answer without an error, and an unknown range is 400 INVALID_PARAMETERS. disk (bytes read and written, like net) and storage are None on a point without a reading.
  • status() formats cpu and ram as strings such as '120.4MB'. With raw=True they are numbers.
  • An id that is empty, . or .. fails locally with INVALID_ID before anything is sent, because it would address a different resource.

Usage

Uploads

apps.create and apps.commit take a path, bytes or a binary file object, and stream it, so a path or a seekable file is never loaded into memory. A commit unpacks a .zip into path, the application root by default. Any other file lands at path/<filename>. The filename is filename=, else the file's own name, else app.zip on create and commit.zip on commit. A file over 100 MB fails locally with FILE_TOO_LARGE before anything is sent. Uploads have no timeout.

created = client.apps.create('bot.zip')
client.apps.commit(created['id'], 'patch.zip', path='/src')
client.apps.commit(created['id'], b'print(1)', path='/src', filename='main.py')

Files

client.apps.files.write(app_id, '/config.json', '{"debug": false}')  # str or bytes
data: bytes = client.apps.files.read(app_id, '/config.json')
client.apps.files.move(app_id, '/config.json', '/config.old.json')

A str is sent as text. bytes are sent base64-encoded, which keeps binary content intact and takes about 1.33 times the size on the wire. Empty content ('' or b'') creates an empty file. Content over 10 MB fails locally with FILE_TOO_LARGE, and content over 1 MiB is sent without a timeout, like an upload. Content the API cannot decode is 400 INVALID_CONTENT. read always asks for base64 and returns the decoded bytes, and a file over 10 MB is 413 FILE_TOO_LARGE. list of a missing directory is 404 FILE_NOT_FOUND, and a protected path is 403 BLOCKED_PATH. Paths are at most 256 characters.

Snapshots

create returns {'pending': True} while the API is still generating the snapshot, which it signals with HTTP 202 SNAPSHOT_PROCESSING. The snapshot then appears in list on its own, usually within 2 minutes. Poll list and do not call create again, because it allows one call every 180 seconds and each call counts against your plan's daily snapshot quota. An API key without snapshots:read gets {'pending': False} with url and key set to ''.

restore returns {'pending': True} when the restore is not done after about 90 seconds, which the API signals with HTTP 202 SNAPSHOT_RESTORE_PROCESSING. The restore keeps running in the background. Follow it with restore_state and do not call restore again. restore_state reports queued or running with the current step, then success, or error with a code, for 1 hour after the restore ends, and none when there is no recent restore. It allows 30 calls per minute.

import time

snapshot = client.apps.snapshots.create(app_id)
if not snapshot['pending']:
    client.download_snapshot(snapshot['url'], 'backups/')  # -> backups/<name>.zip

latest = max(client.apps.snapshots.list(app_id), key=lambda s: s['modified'])
client.download_snapshot(latest['url'], 'backups/')

restored = client.apps.snapshots.restore(app_id, latest['name'], latest['version_id'])
if restored['pending']:
    state = client.apps.snapshots.restore_state(app_id)
    while state['state'] in ('queued', 'running'):
        time.sleep(5)
        state = client.apps.snapshots.restore_state(app_id)
    print(state['state'], state.get('code', ''))  # success, or error with a code

Each listed snapshot carries the API's version_id, which restore needs, and a signed download url, both passed through as sent. The url from list and create is valid for 1 hour. When snapshot storage cannot answer, a listing fails with 503 SNAPSHOTS_UNAVAILABLE, so try again in about 30 seconds.

A restore can fail with 400 MISSING_PARAMETERS, INVALID_SNAPSHOT_ID or INVALID_VERSION_ID, and on databases also with SNAPSHOT_DATABASE_MISMATCH. It can fail with 404 APP_NOT_FOUND, DATABASE_NOT_FOUND, SNAPSHOT_NOT_FOUND, SNAPSHOT_RESTORE_FAILED, SNAPSHOT_CORRUPT, RESTORE_INTERRUPTED or CONTAINER_NOT_FOUND, with 409 RESTORE_IN_PROGRESS or SNAPSHOT_IN_PROGRESS, with 413 PAYLOAD_TOO_LARGE, and with 503 CLUSTER_MAINTENANCE_TRY_LATER, which snapshot create can return too.

download_snapshot never sends your API key with the download. It streams to a .part file next to the target and renames it once complete, and each read waits at most timeout.

Realtime

with client.apps.realtime(app_id) as stream:
    for event in stream:
        if event['event'] == 'logs':
            print(event['stream'], event['line'])  # stdout | stderr
        elif event['event'] == 'status':
            print(event['status'].get('cpu'))  # always the full, merged state
        else:  # 'system' or 'error'
            print(event['data'])  # a code such as REALTIME_DISCONNECTED

Every event has event, data (the raw text of the event) and id. The HTTP status is checked before any event, so 429 REALTIME_MAX_CONNECTIONS raises right away. If the connection drops, or the API hands the feed over with REALTIME_RECONNECT, the feed reopens on its own up to 3 times in a row, and a logs or status event resets that count. It opens at most once every 5.5 seconds, to stay under the API's limit of one open every 5 seconds. Past 3 reopens it raises NETWORK_ERROR.

The client's timeout applies only until the feed opens. The loop ends when the API closes the feed after its 10-minute limit, on REALTIME_DISCONNECTED, or when you call stream.close(), which is safe from any thread and also stops a wait. With AsyncSquareCloud, use async with client.apps.realtime(app_id) as stream: and async for event in stream:. Each account can have up to 5 open feeds, and each application up to 30.

GitHub deploys

# A GitHub webhook: returns its URL ('' when removed with '@')
url = client.apps.deploys.set_webhook(app_id, 'ghp_xxx')

# Or the Square Cloud GitHub App
repo = client.apps.deploys.link_github_app(app_id, 'octocat/hello-world', 'main')
print(repo['id'], repo['full_name'], repo['branch'])

current = client.apps.deploys.current(app_id)  # {} when nothing is set
client.apps.deploys.unlink_github_app(app_id)

Linking needs the apps:deploy scope and a GitHub App installation on your account, or it fails with 403 GITHUB_NOT_CONNECTED. The repository must belong to a GitHub App installation that your connected GitHub account holds, or it fails with 403 REPOSITORY_NOT_AVAILABLE. That account also needs write access to the repository, or it fails with 403 REPOSITORY_PERMISSION_REQUIRED. 502 FAILED_TO_FETCH means GitHub did not confirm the branch, and it is safe to try again.

A repository and branch can be linked to only one application across all accounts. Another link fails with 409 REPOSITORY_BRANCH_ALREADY_CONFIGURED, and the other application's id appears in message only when that application is yours. To link again, unlink first, or the call fails with 400 GIT_ALREADY_CONFIGURED. Unlinking without a link fails with 400 GIT_NOT_CONFIGURED. Link and unlink share a limit of 3 calls per minute.

Errors

Every API and network failure raises SquareCloudAPIError with status, code, message, method, path and cause. The path looks like '/v2/apps/...' and never includes the query string. Local file problems, such as a missing upload path or a download destination you cannot write to, raise OSError.

from squarecloud import SquareCloudAPIError

try:
    client.apps.start(app_id)
except SquareCloudAPIError as e:
    print(e)  # POST /v2/apps/<id>/start: HTTP 404 APP_NOT_FOUND
    if e.code == 'MISSING_SCOPE':
        ...
  • When no response arrives, status is 0 and code is NETWORK_ERROR, with the original exception in cause, or TIMEOUT.
  • When a local check stops the call before anything is sent, status is 0 and code is FILE_TOO_LARGE, or INVALID_ID for an id that is empty, . or ...
  • message is the server's explanation, or '' when it sent only a code. A body without a code, such as a proxy page or a failed snapshot download, gives UNKNOWN_ERROR with the server's message when it sent one and HTTP <status> otherwise. A successful response whose body is not JSON gives UNKNOWN_ERROR with Invalid JSON in HTTP <status> response.
  • A refused start, stop or restart is a 409 with only a code, so message is ''. The code is CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED (applications only), CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT, ACTION_FAILED or RESTORE_IN_PROGRESS. These are errors, so check e.code when a resource that is already started or stopped is fine for you.
  • 409 RESTORE_IN_PROGRESS also answers a delete, start, stop, restart or snapshot create while a restore runs. Try again when the restore ends.
  • A successful response whose body is {"status": "error"} also raises. The 202 answers SNAPSHOT_PROCESSING and SNAPSHOT_RESTORE_PROCESSING are not errors and return {'pending': True}.
  • Errors from ai.chat(), including authentication, 429 and 503, carry the lowercase code of the OpenAI format, such as access_denied, upgrade_required, rate_limit_exceeded, server_overloaded or database_unavailable, or its type when there is no code.
  • The SquareCloudAPIError docstring lists every known API code. The API can add codes, so treat an unknown code as a generic failure of its HTTP status.
  • str(e) is <METHOD> <path>: HTTP <status> <CODE>: <message>. The HTTP <status> part is left out when the status is 0, and the : <message> part when the message is empty.

Retries, timeouts and rate limits

  • Timeouts. timeout, 30 seconds by default, applies to each connect, send and read. Calls the API holds open wait at least 120 seconds: start, stop and restart of applications and databases, databases.create, and snapshot create and restore. So does ai.chat(), which answers within 90 seconds or fails with 503 server_overloaded. A larger timeout wins, and a timeout of 0 or less disables every timeout, including that minimum. Uploads and files.write calls over 1 MiB have no timeout, and realtime() is timed only until it opens.
  • Retries. The SDK retries only what is safe to repeat, up to max_retries times, which is 2 by default. It retries network errors on GET, including a body cut off mid-read, realtime opens, and download_snapshot() before the download starts. It also retries 503 UPLOAD_BUSY and ANALYTICS_BUSY on any method, and 503 DATABASE_UNAVAILABLE on GET. Each wait is 500 ms × 2ⁿ, where n counts the retries from 0, capped at 8 seconds and randomly shortened by up to half.
  • Never retried. Timeouts, any 429, the AI's 503 server_overloaded (safe for you to retry), 503 SNAPSHOTS_UNAVAILABLE and CLUSTER_MAINTENANCE_TRY_LATER, and 409 RESTORE_IN_PROGRESS, SNAPSHOT_IN_PROGRESS and ENV_BUSY. ENV_BUSY means another write to the environment variables is in progress. DATABASE_UNAVAILABLE is not retried on other methods because the change may already have been applied, so retrying an idempotent call such as files.write, envs.replace or stop is up to you.
  • Rate limits. Every account has a global limit of requests per minute, set by its plan (values). Going over it, or over the limit of a single call, returns 429 RATE_LIMITED or KEEP_CALM. RATE_LIMITED can block the account, API key or IP for about 30 minutes, and it is also the limit of the apps.network calls and of account.snapshots(). RATE_LIMIT and RATE_LIMIT_EXCEEDED are its deprecated names. The API sends no Retry-After, which is why the SDK never retries a 429.

Development

uv sync
uv run ruff format --check && uv run ruff check && uv run mypy && uv run pytest   # offline
uv build

The offline suites (tests/test_transport.py, tests/test_http.py, tests/test_streams.py, tests/test_conformance.py, tests/test_surface.py) use a mock transport or a loopback server and never reach the API. The live suite runs all 69 operations against the real API:

SQUARECLOUD_API_KEY=... uv run pytest -m live -s

Warning: the live suite creates and deletes real resources on the key's account: an application, a database and a workspace named sdk-live-py-<timestamp>. It is skipped without SQUARECLOUD_API_KEY and never runs in CI. Requests are spaced 2.1 seconds apart. Run the JS, Python and Go live suites one after another, never at the same time.

Contributing

Issues and pull requests are welcome at squarecloudofc/sdk-api-py.

License

MIT, see LICENSE.

Authors

Maintained by Square Cloud.

Contributors:

Metadata

Release files for squarecloud-api 5.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for squarecloud-api 5.1.0
File Size Uploaded Provenance Actions
squarecloud_api-5.1.0.tar.gz 42.9 kB Without provenance Details for squarecloud_api-5.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for squarecloud-api 5.1.0
File Interpreter ABI Platform Actions
squarecloud_api-5.1.0-py3-none-any.whl Python 3 none any Details for squarecloud_api-5.1.0-py3-none-any.whl

Total release size: 95.3 kB

Release files / squarecloud_api-5.1.0.tar.gz

Download URL squarecloud_api-5.1.0.tar.gz
Size 42.9 kB
Tags Source
SHA-256 checksum
How to use checksums
344f1909301d1b92c91635cab60604663cab3fbc3640250ed9323c91cee97996
BLAKE2b-256 checksum
How to use checksums
4d0df53d0e456f3c3be6a86d1ce1076704a2385e590b9dce1f6f9fe952d8e23d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / squarecloud_api-5.1.0-py3-none-any.whl

Download URL squarecloud_api-5.1.0-py3-none-any.whl
Size 52.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f6a5da9934fb4e9780631b215c239e0d6a3430217e9d7827f7a298affdf0b45b
BLAKE2b-256 checksum
How to use checksums
2eb8ad93e56d47ea1f8f395c36cf390ae85fbbd26a3f5f13ed6b20986214c4dd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for squarecloud-api 5.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

5.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page