> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/workrooms.md).

# Workrooms

Workrooms partition an account — typically one per location or brand. Every write lands in exactly one workroom. Narrow any request to a workroom with `?workroom=<name-or-id>`, the `Gleantap-Workroom` header, or a `workroom` body field. If a name is ambiguous, use the `wrm_...` ID.

## List workrooms for the account.

> Returns every workroom the authenticated account can see, with \`is\_default\` marking which one writes land in when no workroom hint is present on the request. Pass \`?include\_counts=true\` to include per-workroom contact counts (adds a \`COUNT()\` per workroom — skip for large accounts unless needed).<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Workrooms","description":"Sub-account partitions (called \"apps\" in the legacy `appdetails` collection). Every write in v3 lands in exactly one workroom. Callers narrow both reads and writes to a specific workroom via `?workroom=<name-or-id>`, the `Gleantap-Workroom` header, or a `workroom` body field. Names ambiguous within an account return 400 — use the prefixed `wrm_<hex>` ID to disambiguate."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Workroom":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/WorkroomId"},"object":{"type":"string","enum":["workroom"]},"name":{"type":"string","nullable":true},"is_default":{"type":"boolean","description":"True on the workroom the account writes to when the caller doesn't specify one. Phase 1 picks the first workroom by natural (creation) order. A per-API-key default is a Phase 1.5 add.\n"},"contact_count":{"type":"integer","nullable":true,"description":"Only present on retrieve, and on list when `?include_counts=true`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/workrooms":{"get":{"tags":["Workrooms"],"operationId":"listWorkrooms","summary":"List workrooms for the account.","description":"Returns every workroom the authenticated account can see, with `is_default` marking which one writes land in when no workroom hint is present on the request. Pass `?include_counts=true` to include per-workroom contact counts (adds a `COUNT()` per workroom — skip for large accounts unless needed).\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"name":"include_counts","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"A list of workrooms.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Workroom"}}}}]}}}}}}}}}
```

## GET /workrooms/{id\_or\_name}

> Retrieve a workroom by ID or name.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Workrooms","description":"Sub-account partitions (called \"apps\" in the legacy `appdetails` collection). Every write in v3 lands in exactly one workroom. Callers narrow both reads and writes to a specific workroom via `?workroom=<name-or-id>`, the `Gleantap-Workroom` header, or a `workroom` body field. Names ambiguous within an account return 400 — use the prefixed `wrm_<hex>` ID to disambiguate."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"Workroom":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/WorkroomId"},"object":{"type":"string","enum":["workroom"]},"name":{"type":"string","nullable":true},"is_default":{"type":"boolean","description":"True on the workroom the account writes to when the caller doesn't specify one. Phase 1 picks the first workroom by natural (creation) order. A per-API-key default is a Phase 1.5 add.\n"},"contact_count":{"type":"integer","nullable":true,"description":"Only present on retrieve, and on list when `?include_counts=true`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/workrooms/{id_or_name}":{"get":{"tags":["Workrooms"],"operationId":"retrieveWorkroom","summary":"Retrieve a workroom by ID or name.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"}],"responses":{"200":{"description":"The workroom.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workroom"}}}},"400":{"description":"Name resolves to more than one workroom.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
