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

# GraphQL API

The GraphQL API provides mutations for environment lifecycle management and AI configuration, plus queries for listing accounts, apps, environments, and repositories. Use GraphQL when you need to pause, resume, or delete environments, or when you need complex queries with nested data.

**When to use GraphQL vs REST:** Use the GraphQL API for environment lifecycle mutations (pause, resume, delete, deploy) and for queries that benefit from selecting specific fields. Use the REST Platform API for resource CRUD operations and the AI Sandbox API for sandbox session management.

## Endpoint

<mark style="color:green;">`POST`</mark> `https://api.release.com/graphql`

## Authentication

Authenticate using headers from your `~/.release.yaml` file. To set this up, [install the Release CLI](/cli/installation.md) and run `release auth login`.

| Header       | Description                                       |
| ------------ | ------------------------------------------------- |
| X-User-Email | User email from `~/.release.yaml` (`login` field) |
| X-User-Token | User token from `~/.release.yaml` (`token` field) |

## Headers

| Header       | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |
| X-User-Email | Your user email    |
| X-User-Token | Your user token    |

## Mutations

### environmentsPause

Pause an environment.

**Input:**

| Field | Type | Required | Description                        |
| ----- | ---- | -------- | ---------------------------------- |
| id    | ID!  | Yes      | The ID of the environment to pause |

**Response:**

| Field             | Type   | Description                          |
| ----------------- | ------ | ------------------------------------ |
| environment.id    | ID     | The environment ID                   |
| environment.state | String | The current state of the environment |

**Example:**

```graphql
mutation {
  environmentsPause(input: { id: "ENV_ID" }) {
    environment {
      id
      state
    }
  }
}
```

***

### environmentsResume

Resume a paused environment.

**Input:**

| Field | Type | Required | Description                         |
| ----- | ---- | -------- | ----------------------------------- |
| id    | ID!  | Yes      | The ID of the environment to resume |

**Response:**

| Field             | Type   | Description                          |
| ----------------- | ------ | ------------------------------------ |
| environment.id    | ID     | The environment ID                   |
| environment.state | String | The current state of the environment |

**Example:**

```graphql
mutation {
  environmentsResume(input: { id: "ENV_ID" }) {
    environment {
      id
      state
    }
  }
}
```

***

### environmentsDelete

Delete an environment.

**Input:**

| Field | Type | Required | Description                         |
| ----- | ---- | -------- | ----------------------------------- |
| id    | ID!  | Yes      | The ID of the environment to delete |

**Response:**

| Field             | Type   | Description                          |
| ----------------- | ------ | ------------------------------------ |
| environment.id    | ID     | The environment ID                   |
| environment.state | String | The current state of the environment |

**Example:**

```graphql
mutation {
  environmentsDelete(input: { id: "ENV_ID" }) {
    environment {
      id
      state
    }
  }
}
```

***

### environmentsSetup

Deploy or setup an environment.

**Input:**

| Field          | Type   | Required | Description                            |
| -------------- | ------ | -------- | -------------------------------------- |
| id             | ID!    | Yes      | The ID of the environment to deploy    |
| initiationType | String | No       | The initiation type (e.g., `"manual"`) |

**Response:**

| Field             | Type   | Description                          |
| ----------------- | ------ | ------------------------------------ |
| environment.id    | ID     | The environment ID                   |
| environment.state | String | The current state of the environment |

**Example:**

```graphql
mutation {
  environmentsSetup(input: { id: "ENV_ID", initiationType: "manual" }) {
    environment {
      id
      state
    }
  }
}
```

***

### aiConfigurationsCreate

Create an AI configuration.

**Input:**

| Field | Type                         | Required | Description                     |
| ----- | ---------------------------- | -------- | ------------------------------- |
| input | AiConfigurationsCreateInput! | Yes      | The AI configuration parameters |

**Response:**

| Field         | Type   | Description                         |
| ------------- | ------ | ----------------------------------- |
| configuration | Object | The created AI configuration object |

**Example:**

```graphql
mutation {
  aiConfigurationsCreate(input: { ... }) {
    configuration {
      id
    }
  }
}
```

***

### aiConfigurationsDelete

Delete an AI configuration.

**Input:**

| Field | Type | Required | Description                              |
| ----- | ---- | -------- | ---------------------------------------- |
| id    | ID!  | Yes      | The ID of the AI configuration to delete |

**Response:**

| Field        | Type   | Description              |
| ------------ | ------ | ------------------------ |
| confirmation | Object | Confirmation of deletion |

**Example:**

```graphql
mutation {
  aiConfigurationsDelete(input: { id: "CONFIG_ID" }) {
    confirmation
  }
}
```

***

### aiSandboxesCreateSession

Create an AI sandbox session via GraphQL.

**Input:**

| Field | Type                           | Required | Description                    |
| ----- | ------------------------------ | -------- | ------------------------------ |
| input | AiSandboxesCreateSessionInput! | Yes      | The sandbox session parameters |

The `AiSandboxesCreateSessionInput` accepts resources using the `AiSandboxResourceInput` type:

```graphql
input AiSandboxResourceInput {
  type: String!
  mountPath: String
  repoUrl: String
  repositoryId: ID
  branch: String
  repoName: String
  authMode: String
  token: String
  checkoutType: String
  checkoutValue: String
  s3Uri: String
  filename: String
  contentType: String
  sizeBytes: Int
  checksum: String
}
```

**Response:**

| Field                             | Type      | Description                        |
| --------------------------------- | --------- | ---------------------------------- |
| session.id                        | ID        | The session ID                     |
| session.title                     | String    | The session title                  |
| session.state                     | String    | The current state of the session   |
| session.sandboxClaimName          | String    | The sandbox claim name             |
| session.startedAt                 | String    | Timestamp when the session started |
| session.environment.id            | ID        | The associated environment ID      |
| session.environment.handle        | String    | The environment handle             |
| session.environment.name          | String    | The environment name               |
| session.resources                 | \[Object] | List of session resources          |
| session.resources\[].id           | ID        | The resource ID                    |
| session.resources\[].resourceType | String    | The type of resource               |
| session.resources\[].state        | String    | The resource state                 |
| session.resources\[].mountPath    | String    | The mount path for the resource    |
| session.resources\[].config       | Object    | Resource configuration             |
| session.resources\[].status       | Object    | Resource status                    |
| userErrors                        | \[Object] | List of validation errors          |
| userErrors\[].field               | String    | The field that caused the error    |
| userErrors\[].message             | String    | The error message                  |

**Example:**

```graphql
mutation {
  aiSandboxesCreateSession(input: {
    resources: [
      {
        type: "git_repo"
        repoUrl: "https://github.com/org/repo"
        branch: "main"
        mountPath: "/workspace/repo"
      }
    ]
  }) {
    session {
      id
      title
      state
      sandboxClaimName
      startedAt
      environment {
        id
        handle
        name
      }
      resources {
        id
        resourceType
        state
        mountPath
        config
        status
      }
    }
    userErrors {
      field
      message
    }
  }
}
```

## Queries

### workspaces

List accounts and workspaces.

**Arguments:**

No required arguments.

**Response:**

| Field      | Type      | Description                |
| ---------- | --------- | -------------------------- |
| workspaces | \[Object] | Array of workspace objects |

**Example:**

```graphql
query {
  workspaces {
    id
    name
  }
}
```

***

### apps

List applications.

**Arguments:**

| Field     | Type   | Required | Description                        |
| --------- | ------ | -------- | ---------------------------------- |
| accountId | ID!    | Yes      | The account ID to list apps for    |
| filters   | Object | No       | Optional filters to narrow results |

**Response:**

| Field | Type      | Description                  |
| ----- | --------- | ---------------------------- |
| apps  | \[Object] | Array of application objects |

**Example:**

```graphql
query {
  apps(accountId: "ACCOUNT_ID") {
    id
    name
  }
}
```

***

### environments

List environments with details.

**Arguments:**

| Field   | Type   | Required | Description                                 |
| ------- | ------ | -------- | ------------------------------------------- |
| appId   | ID!    | Yes      | The application ID to list environments for |
| filters | Object | No       | Optional filters to narrow results          |

**Response:**

| Field        | Type      | Description                                    |
| ------------ | --------- | ---------------------------------------------- |
| environments | \[Object] | Array of environment objects with full details |

**Example:**

```graphql
query {
  environments(appId: "APP_ID") {
    id
    name
    state
    handle
  }
}
```

***

### repositories

List available repositories.

**Arguments:**

| Field     | Type | Required | Description                             |
| --------- | ---- | -------- | --------------------------------------- |
| accountId | ID!  | Yes      | The account ID to list repositories for |

**Response:**

| Field        | Type      | Description                 |
| ------------ | --------- | --------------------------- |
| repositories | \[Object] | Array of repository objects |

**Example:**

```graphql
query {
  repositories(accountId: "ACCOUNT_ID") {
    id
    name
  }
}
```

***

### repository

Get repository details with branches.

**Arguments:**

| Field | Type | Required | Description       |
| ----- | ---- | -------- | ----------------- |
| id    | ID!  | Yes      | The repository ID |

**Response:**

| Field      | Type   | Description                               |
| ---------- | ------ | ----------------------------------------- |
| repository | Object | Repository object with branches and paths |

**Example:**

```graphql
query {
  repository(id: "REPO_ID") {
    id
    name
    branches {
      name
    }
    paths
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.release.com/reference-documentation/release-api/graphql-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.