> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paradime.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Management API

> Create, list, and configure Paradime workspaces through the GraphQL API to automate workspace provisioning and management for your account.

### Overview

> [!NOTE]
>
> **Prerequisites:**
>
> * This feature is available with the [**Paradime Enterprise pack**](https://www.paradime.io/enterprise).
> * Your API keys ***must*** have either User Management Admin or User Metadata Viewer capabilities.

> [!NOTE]
>
> The examples below authenticate with an **account API key** — pass `Authorization: Bearer <token>` (the account key starts with `prdm_cmp_`). This is an account-wide endpoint, so the `X-Paradime-Workspace` header is **not** required. Legacy **workspace API keys** are still supported: send `X-API-KEY` and `X-API-SECRET` headers instead. See API Keys.

The Workspace Management API enables you to view workspace metadata for your Paradime accounts.

### List Workspaces

This endpoint will return details on the current active workspaces in your Paradime Account.

**Example Request**

> [tab] GraphQL
>
> ```python theme={"system"}
> import requests
> import os
>
> # API credentials
> api_endpoint = "<YOUR_API_ENDPOINT>"
> api_token = "<YOUR_API_TOKEN>"          # account API key (starts with prdm_cmp_)
>
> graphql_query = """
> query ListWorkspaces {
>     listWorkspaces {
>         ok
>         workspaces {
>             name
>             uid
>         }
>     }
> }
>   """
>
> response = requests.post(api_endpoint, json={"query": graphql_query}, headers={
>       "Content-Type": "application/json",
>       "Authorization": f"Bearer {api_token}",
>   })
>
> print(response.json())
> ```

> [tab] cURL
>
> ```bash theme={"system"}
> curl -X POST "<YOUR_API_ENDPOINT>" \
>      -H "Content-Type: application/json" \
>      -H "Authorization: Bearer <YOUR_API_TOKEN>" \
>      -d '{
>        "query": "query ListWorkspaces { listWorkspaces { ok workspaces { name uid } } }"
>      }'
> ```

> [accordion] Example response
>
> ```json theme={"system"}
> {
>   "data": {
>     "listWorkspaces": {
>       "ok": true,
>       "workspaces": [
>         {
>           "name": "data-platoform",
>           "uid": "r233tak125coyphm"
>         },
>         {
>           "name": "finance",
>           "uid": "vxs6x31394cqk2vd"
>         },
>         {
>           "name": "sales",
>           "uid": "fuqge1jaj1122i5k"
>         }
>       ]
>     }
>   }
> }
> ```

### Git repository connection

Read and set how a workspace connects to its Git repository: through the [GitHub App](https://docs.paradime.io/products/settings/git-repositories/connect-with-github-app.md), through a [GitLab connection](https://docs.paradime.io/integrations/gitlab), or with its SSH deploy key.

> [!NOTE]
>
> * Your API key needs the **Git repository admin** capability.
> * These operations act on one workspace, so an account API key must send the `X-Paradime-Workspace: <workspace_uid>` header.
> * The API uses only installations and connections that your company already holds. An API key has no GitHub account of its own.

#### Read the connection

`gitRepository` returns the workspace's connection:

* `connection.mode`: `SSH_DEPLOY_KEY`, `GITHUB_APP`, or `GITLAB_APP`.
* `connection.installationId`, `connection.repoId`, and `connection.repoFullName`: the GitHub App installation and the repository it is pinned to.
* `state`: `CONNECTED`, `DEGRADED`, or `DISCONNECTED`.
* `gitUri`: the repository URL.
* `hasDeployKey`: `true` when a deploy key clone exists to fall back to.
* `pendingInstallRequests`: GitHub App install requests that wait for an organization owner.

```graphql theme={"system"}
query GitRepository {
  gitRepository {
    connection {
      mode
      installationId
      repoId
      repoFullName
    }
    state
    gitUri
    hasDeployKey
  }
}
```

#### Set the connection

`setGitRepository` takes a `mode` and, for some modes, the repository to connect:

| `mode` | Arguments | Result |
| - | - | - |
| `GITHUB_APP` | `installationId` and `repoId` (the repository's numeric GitHub id) | Connects the workspace to that repository through that installation. |
| `GITHUB_APP` | None | Switches the current repository to the GitHub App, in place. |
| `GITLAB_APP` | `baseUrl` (the GitLab connection's base URL) and `projectId` (the project's numeric GitLab id) | Connects the workspace to that project through that GitLab connection. |
| `GITLAB_APP` | None | Switches the current repository to the GitLab connection, in place. |
| `SSH_DEPLOY_KEY` | None | Switches the workspace back to its deploy key. |

Pass both arguments of a pair, or neither.

```graphql theme={"system"}
mutation SetGitRepository {
  setGitRepository(mode: GITHUB_APP, installationId: "12345678", repoId: "987654321") {
    ok
    connection {
      mode
      repoFullName
    }
  }
}
```


## Related topics

- [API Reference](https://docs.paradime.io/developers/graphql-api/api-reference/index.md)
- [GraphQL API](https://docs.paradime.io/developers/graphql-api/index.md)
- [Authentication](https://docs.paradime.io/developers/graphql-api/authentication.md)
- [Connect through the GitHub App](https://docs.paradime.io/products/settings/git-repositories/connect-with-github-app.md)
- [Workspace Management](https://docs.paradime.io/developers/python-sdk/modules/workspace-management.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.