squarecloud-api
The official Python SDK for the Square Cloud API.
- Zero runtime dependencies, and one reused connection per thread.
- Runs on Python 3.11+, with a sync
SquareCloudclient, an asyncAsyncSquareCloudclient 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.
bodyisbytes, an iterable ofbyteschunks withContent-Lengthalready inheaders, orNone.timeoutis how many seconds each connect, send or read may take, raised to 120 for the calls the API holds open. It isNonefor uploads, large file writes and the realtime feed, so bound their connect yourself.streammeans the caller reads the body bit by bit and may callclose()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.
startandendtake an ISO 8601 string, which is sent as is, or adatetime, which is sent in UTC. A naivedatetimeis read as local time.- The
analyticsfilters are keyword-only:country,ip,path,status,os,browser,protocol,referer,provider,content_typeandbot.providertakes the'NAME (ASN)'form that theprovidersbuckets report, such asprovider='GOOGLE (15169)'. An invalid filter is 400INVALID_FILTER. apps.network.analytics,errorsandperformancereturnNonefor 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 incpu_maxandram_maxon 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 unknownrangeis 400INVALID_PARAMETERS.disk(bytes read and written, likenet) andstorageareNoneon a point without a reading.status()formatscpuandramas strings such as'120.4MB'. Withraw=Truethey are numbers.- An id that is empty,
.or..fails locally withINVALID_IDbefore 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,
statusis0andcodeisNETWORK_ERROR, with the original exception incause, orTIMEOUT. - When a local check stops the call before anything is sent,
statusis0andcodeisFILE_TOO_LARGE, orINVALID_IDfor an id that is empty,.or... messageis 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, givesUNKNOWN_ERRORwith the server's message when it sent one andHTTP <status>otherwise. A successful response whose body is not JSON givesUNKNOWN_ERRORwithInvalid JSON in HTTP <status> response.- A refused start, stop or restart is a 409 with only a code, so
messageis''. The code isCONTAINER_ALREADY_STARTED,CONTAINER_ALREADY_STOPPED,CONTAINER_TEMPORARILY_SUSPENDED(applications only),CONTAINER_NOT_FOUND,CONTAINER_INSUFFICIENT_DISK_SPACE,CONTAINER_NETWORK_CONFLICT,ACTION_FAILEDorRESTORE_IN_PROGRESS. These are errors, so checke.codewhen a resource that is already started or stopped is fine for you. - 409
RESTORE_IN_PROGRESSalso answers a delete, start, stop, restart or snapshotcreatewhile a restore runs. Try again when the restore ends. - A successful response whose body is
{"status": "error"}also raises. The 202 answersSNAPSHOT_PROCESSINGandSNAPSHOT_RESTORE_PROCESSINGare not errors and return{'pending': True}. - Errors from
ai.chat(), including authentication, 429 and 503, carry the lowercasecodeof the OpenAI format, such asaccess_denied,upgrade_required,rate_limit_exceeded,server_overloadedordatabase_unavailable, or itstypewhen there is no code. - The
SquareCloudAPIErrordocstring 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>. TheHTTP <status>part is left out when the status is0, 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,stopandrestartof applications and databases,databases.create, and snapshotcreateandrestore. So doesai.chat(), which answers within 90 seconds or fails with 503server_overloaded. A largertimeoutwins, and atimeoutof 0 or less disables every timeout, including that minimum. Uploads andfiles.writecalls over 1 MiB have no timeout, andrealtime()is timed only until it opens. - Retries. The SDK retries only what is safe to repeat, up to
max_retriestimes, which is 2 by default. It retries network errors onGET, including a body cut off mid-read, realtime opens, anddownload_snapshot()before the download starts. It also retries 503UPLOAD_BUSYandANALYTICS_BUSYon any method, and 503DATABASE_UNAVAILABLEonGET. 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), 503SNAPSHOTS_UNAVAILABLEandCLUSTER_MAINTENANCE_TRY_LATER, and 409RESTORE_IN_PROGRESS,SNAPSHOT_IN_PROGRESSandENV_BUSY.ENV_BUSYmeans another write to the environment variables is in progress.DATABASE_UNAVAILABLEis not retried on other methods because the change may already have been applied, so retrying an idempotent call such asfiles.write,envs.replaceorstopis 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_LIMITEDorKEEP_CALM.RATE_LIMITEDcan block the account, API key or IP for about 30 minutes, and it is also the limit of theapps.networkcalls and ofaccount.snapshots().RATE_LIMITandRATE_LIMIT_EXCEEDEDare its deprecated names. The API sends noRetry-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 withoutSQUARECLOUD_API_KEYand 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:
- Robert Nogueira (@robert-nogueira)
- Jhonatan Jeferson (@Jhonatan-Jeferson)
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.