List spaces
List the spaces of the organization the caller reaches: the default space first, then personal spaces (the caller's own and, for an owner or admin, orphaned ones), then team spaces, each oldest first.
/api/spacesCookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.
In: cookie
Header Parameters
Organization ID. Required for cookie auth. Not needed for API key auth (org resolved from key).
uuidPreview the API as a lesser role ("view as"). One value, ;-separated key=value pairs; whitespace around the separators is tolerated and nothing else is:
org_role(required) —memberorguest. Previewingowner/adminis refused.space(optional) — aspc_space id. Must be paired withrole.role(optional) —preset:<admin|builder|operator|runner|viewer>orcustom:<srl_ id>. Must be paired withspace.
Example: org_role=member; space=spc_…; role=preset:viewer.
The persona is enforced server-side: permissions, the space role and every listing are the persona's, and a write the persona cannot make is refused exactly as it would be for a real holder of that role. The authenticated identity and the audit actor stay the real caller; audit rows carry the persona under after.viewAs.
Refusals — never a silent fall-back to the caller's real permissions: 400 invalid_view_as (header does not parse), 400 view_as_unsupported (the credential is not one that can carry a persona — only a cookie session and the CLI/instance token, which authenticate the user themselves, can), 403 view_as_forbidden (the real org role is not owner/admin, or the role is not one the caller could grant in that space), 404 view_as_not_found (the space is not in the org, the custom role does not exist, or the organization named alongside the persona is not one the caller belongs to). A 404 carrying view_as_not_found means the PREVIEW died and must be dropped; a plain 404 not_found under an active persona is the previewed role's own wall and leaves the preview standing.
On GET /api/orgs and GET /api/me/orgs — the two listings exempt from X-Org-Id — the X-Org-Id header names the organization the persona applies to; every other row in those listings stays the caller's real role. Sending the persona without it is 400 invalid_view_as, and naming an organization the caller is not a member of is 404 view_as_not_found: a listing that answered with real permissions while the client believed it was previewing would be the failure this feature exists to prevent.
The Server-Sent-Events routes (/api/realtime/*) take the same value as the view_as QUERY parameter instead: EventSource cannot send headers.
Every response produced under a validated persona carries X-View-As-Active: 1.
curl -X GET "https://your-instance/api/spaces"{
"object": "list",
"data": [
{
"id": "spc_0a2b4c6d-8e10-4f32-9a54-b6c8d0e2f416",
"object": "space",
"orgId": "550e8400-e29b-41d4-a716-446655440000",
"name": "Default",
"isDefault": true,
"settings": {
"allowedRedirectDomains": []
},
"visibility": "open",
"default_role": "operator",
"personal": false,
"access": "member",
"role": {
"kind": "preset",
"key": "operator",
"name": "operator"
},
"permissions": [
"agents:read",
"agents:run"
],
"created_by": null,
"createdAt": "2026-01-10T08:00:00Z",
"updatedAt": "2026-01-10T08:00:00Z"
},
{
"id": "spc_5b8c0e13-4f7a-4d92-b3c6-71e0a4d9f582",
"object": "space",
"orgId": "550e8400-e29b-41d4-a716-446655440000",
"name": "My SaaS App",
"isDefault": false,
"settings": {
"allowedRedirectDomains": [
"myapp.com"
]
},
"visibility": "closed",
"default_role": "operator",
"personal": false,
"access": "none",
"role": null,
"permissions": [
"org:read",
"spaces:read"
],
"created_by": "usr_k7x9m2p4q1",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
}
],
"hasMore": false
}{
"type": "https://docs.appstrate.dev/errors/invalid-view-as",
"title": "Invalid View-As Header",
"status": 400,
"detail": "X-View-As could not be parsed: space and role must be provided together",
"code": "invalid_view_as",
"param": "X-View-As",
"request_id": "req_abc123"
}{
"type": "https://docs.appstrate.dev/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Invalid or missing session",
"code": "unauthorized",
"request_id": "req_abc123"
}{
"type": "https://docs.appstrate.dev/errors/forbidden",
"title": "Forbidden",
"status": 403,
"detail": "Insufficient permissions",
"code": "forbidden",
"request_id": "req_abc123"
}{
"type": "https://docs.appstrate.dev/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Resource not found",
"code": "not_found",
"request_id": "req_abc123"
}