Skip to main content
POST
/
api
/
v1
/
storage
/
sandboxes
Create Sandbox
curl --request POST \
  --url https://api.copass.id/api/v1/storage/sandboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "owner_id": "<string>",
  "tier": "free",
  "metadata": {}
}
'
{
  "sandbox_id": "<string>",
  "user_id": "<string>",
  "owner_id": "<string>",
  "name": "<string>",
  "tier": "<string>",
  "status": "<string>",
  "storage_provider_type": "<string>",
  "limits": {},
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "access": "<string>",
  "is_external": false
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
authorization
string | null

Body

application/json
​
name
string
required

Sandbox name

Required string length: 1 - 255
​
owner_id
string
required

Opaque UUID you supply to identify which end-user in your own system owns this sandbox. Copass does not interpret this value — it's your mapping key back to your database (e.g., your users.id, customers.id, or organizations.id). Store it on your side next to the returned sandbox_id so you can resolve 'which of my users does this Copass sandbox belong to?'. Combined with name, (owner_id, name) is unique per Copass account — so the same owner can have multiple named sandboxes, and you can pass owner_id as a query filter on GET /sandboxes to list everything belonging to one of your users.

​
tier
string
default:free

Sandbox tier: free, pro, enterprise

​
metadata
Metadata · object

Flexible metadata

Response

Successful Response

​
sandbox_id
string
required
​
user_id
string
required

The Copass platform account that holds this sandbox (derived from the authenticated API key / JWT). This is the Copass-side tenant ID and is also the Vitess shard-routing key — it is NOT the identifier of your end-user. Use owner_id for that.

​
owner_id
string
required

The same opaque identifier you passed on create — echoed back so you can map this sandbox to the end-user in your system (e.g., your users.id). Copass stores but never interprets it. Two common patterns: (1) set owner_id to your internal user UUID so one Copass account can host many of your users, each with isolated sandboxes; (2) call GET /sandboxes?owner_id=... to list every sandbox that belongs to a given user on your side.

​
name
string
required
​
tier
string
required
​
status
string
required
​
storage_provider_type
string
required

platform_s3 or custom_s3

​
limits
Limits · object
required

Tier-derived quotas

​
metadata
Metadata · object
​
created_at
string<date-time> | null
​
access
string | null

Caller's access level on this sandbox: 'owner', 'editor', or 'viewer'. Omitted in legacy owner-only listings; populated by GET /sandboxes once connection-union is wired.

​
is_external
boolean
default:false

True if the authenticated caller accesses this sandbox via a sandbox_connections grant rather than direct ownership.