Get a space
Get a single space by ID.
/api/spaces/{id}Cookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.
In: cookie
Path Parameters
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/string"{
"id": "string",
"object": "space",
"orgId": "string",
"name": "string",
"isDefault": true,
"settings": {
"allowedRedirectDomains": [
"string"
]
},
"visibility": "open",
"default_role": "admin",
"personal": true,
"orphaned_at": "2019-08-24T14:15:22Z",
"access": "member",
"role": {
"kind": "preset",
"key": "string",
"name": "string"
},
"permissions": [
"string"
],
"created_by": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}{
"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"
}