# Workspaces

Most data in Archive is scoped to a **workspace**, typically a single brand or region. You choose which workspace a request reads from by sending its UUID in the `WORKSPACE-ID` header.

```http
WORKSPACE-ID: <workspace-uuid>
```

## Finding workspace IDs

A workspace ID is the `id` returned by the `workspaces` query, which lists every workspace your token can access. You can also copy it from the Archive app. The `workspaces` query is the only operation that doesn’t require a `WORKSPACE-ID` header, because it takes your token and returns the workspaces that token can access.

```graphql
query WorkspacesDefault($first: Int, $after: String) {
  workspaces(first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

```json
{
  "first": 10
}
```

```http
Authorization: Bearer docs_demo_token_0000000000000000000000
WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a
```

```json
{
  "data": {
    "workspaces": {
      "totalCount": 1,
      "edges": [
        {
          "node": {
            "id": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "name": "Northwind Botanicals"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "Z2lkOi8vYXJjaGl2ZS9Xb3Jrc3BhY2UvOTkwMTAx"
      }
    }
  }
}
```

## Which operations are workspace-scoped

Every operation is workspace-scoped except `workspaces`. Queries like `workspace`, `items`, `creators`, and `transcriptions` all read from the workspace identified by the header, so they need it on every call. Set the header once and reuse it for the rest of the session:

```graphql
query WorkspaceDefault {
  workspace {
    id
    name
  }
}
```

```http
Authorization: Bearer docs_demo_token_0000000000000000000000
WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a
```

```json
{
  "data": {
    "workspace": {
      "id": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
      "name": "Northwind Botanicals"
    }
  }
}
```

## Missing or unknown workspaces

There are two distinct failure modes:

- Omitting the `WORKSPACE-ID` header on a workspace-scoped operation returns HTTP 400 with the body `{"errors":"WORKSPACE-ID header is required"}`.

```json
{
  "errors": "WORKSPACE-ID header is required"
}
```

- An unknown workspace, or one your token can’t access, returns HTTP 404 with the body `{"errors":"Shop not found"}`.

```json
{
  "errors": "Shop not found"
}
```

> **Workspace existence is not disclosed**
>
> A workspace your token can’t access returns the same 404 as a workspace that doesn’t exist. This prevents the API from being used to test whether a workspace exists.

## Iterating across workspaces

With an organization-wide token you can work across every workspace in the organization. List them once with `workspaces`, then set `WORKSPACE-ID` to each workspace’s `id` in turn and issue your workspace-scoped queries. You don’t need to re-authenticate between workspaces; only the header changes.

For the full error model, see the [Errors guide](/api/v2/docs/guides/errors).