Workspaces
A workspace is the top-level container for all data in Ptolemy. Every API call is scoped to a workspace, and data never crosses workspace boundaries.
What is a workspace?
A workspace is an isolated environment containing your instruments, markets, time series data, members, and settings. Think of it as a tenant — everything you create in Ptolemy lives inside a workspace.
Each workspace has a unique id (UUID) and a human-readable slug. Both can be used to identify the workspace in API URLs:
Members and roles
Each workspace has a set of members with assigned roles. Roles control what operations each member can perform.
Robot users — the service accounts used for API integrations — are limited to Viewer or Member roles. The Editor and Admin roles are reserved for human users.
Robot users and tokens
Robot users are service accounts created by an Admin specifically for programmatic access. Each robot user can have multiple API tokens, enabling zero-downtime credential rotation.
POST /memberships/robots to create the user and assign it a role in one step.POST /memberships/robots/{userId}/tokens to generate a ptk_live_ token. Store it immediately — it cannot be retrieved again.Plan limits
Each workspace is governed by a plan that sets limits on four metered dimensions: human seats, webhook endpoints, database items, and API calls. You can monitor current usage via the dashboard or the GET /plan endpoint.
The X-RateLimit-Remaining response header on every API call shows how many API calls remain in the current billing period, making it easy to monitor consumption in your integration.