---
canonical_url: "https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes"
markdown_url: "https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopes.md"
product: "platform"
version: "3.1"
last_updated: null
---

# Get required scopes

**Documentation:** /reference/api-reference/toolkits/recommendToolkitScopes

> **API version:** This page documents Composio REST API v3.1, the current version, at `https://backend.composio.dev/api/v3.1`. `https://backend.composio.dev/api/v3` is the previous version and remains supported.

Experimental: this endpoint is in beta and its contract may change.

Recommends the required scopes to use the given set of tools.

---

## POST `/api/v3.1/toolkits/{toolkit_slug}/scopes/recommended`

**Endpoint:** `https://backend.composio.dev/api/v3.1/toolkits/{toolkit_slug}/scopes/recommended`

**Summary:** Get required scopes

Experimental: this endpoint is in beta and its contract may change.

Recommends the required scopes to use the given set of tools.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key`

### Path Parameters

- `toolkit_slug` (string) *(required)*: Toolkit to recommend scopes for.

### Request Body

**Schema:**

- `tools` (array<string>) *(required)*: Tool slugs to recommend scopes for; an empty list computes the recommendation across all of the toolkit’s tools.
- `auth_scheme` (enum: "OAUTH2" | "OAUTH1" | "API_KEY" | ...): Auth scheme the connection will use. Defaults to OAUTH2.
- `toolkit_version` (string): Toolkit version to compute from; defaults to the latest published version. Pass a concrete version to pin.
- `grant_context` (object): Context in which you want to grant scopes to your user. Pass a dimension and its selected value, for example {"account_type": "Google Workspace"}. Use the [List grant contexts](https://docs.composio.dev/reference/api-reference/toolkits/recommendToolkitScopesGrantContext) endpoint to discover available dimensions and values.
  - `[key: string]` (string)
- `include` (array<string>): Scopes the recommendation must include, irrespective of usage.
- `exclude` (array<string>): Scopes the recommendation must not include; the solver picks documented alternatives and fails when none exist.
- `available_scopes` (array<string>): Scopes your OAuth app can request. The recommendation never names a scope outside this list and fails with scope_not_available when a tool cannot be covered inside it. Omit for an unbounded recommendation.

**Example:**

```json
{
  "tools": [
    "string"
  ],
  "auth_scheme": "OAUTH2",
  "toolkit_version": "latest",
  "grant_context": {
    "key": "string"
  },
  "include": [
    "string"
  ],
  "exclude": [
    "string"
  ],
  "available_scopes": [
    "string"
  ]
}
```

### Responses

#### 200 - Successfully recommended scopes for the requested tools

**Response Schema:**

- `auth_scheme` (string) *(required)*: Auth scheme the recommendation was computed under.
- `toolkit_version` (string) *(required)*: Concrete toolkit version the answer was computed from; pass it back as toolkit_version to pin.
- `grant_context` (object) *(required)*: The effective grant_context the recommendation was computed with - the toolkit default overlaid with your overrides; {} when none applies.
  - `[key: string]` (string)
- `scopes` (object) *(required)*
  - `least_privilege` (array<string>) *(required)*: Narrowest documented option per requirement.
  - `fewest` (array<string>) *(required)*: Smallest scope set covering all requirements.
  - `conditional` (array<object>) *(required)*: Scopes needed only for particular call-time inputs; the lists above already include them worst-case, so a caller that knows its inputs may subtract the rest. Empty when none apply.
    - Array items:
      - `scope` (string) *(required)*: The scope needed only under the `when` guard.
      - `when` (object) *(required)*: Condition for when this scope is needed: input field name to qualifying values (any value matches within a field; all fields must match).
        - `[key: string]` (array<string>)
      - `for` (array<string>) *(required)*: Tool slugs that need this scope under the guard.

**Example Response:**

```json
{
  "auth_scheme": "string",
  "toolkit_version": "string",
  "grant_context": {
    "key": "string"
  },
  "scopes": {
    "least_privilege": [
      "string"
    ],
    "fewest": [
      "string"
    ],
    "conditional": [
      {
        "scope": "...",
        "when": "...",
        "for": "..."
      }
    ]
  }
}
```

#### 400 - Bad request (validation_error, action_not_available, grant_context_required, not_available_in_grant_context)

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Toolkit or toolkit_version not found

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 422 - Exclusions or the available_scopes ceiling leave a requested tool with no grantable scope (exclude_conflict, scope_not_available)

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 501 - Some requested tools are not supported by scope resolution yet (not_supported)

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X POST "https://backend.composio.dev/api/v3.1/toolkits/string/scopes/recommended" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [
      "string"
    ],
    "auth_scheme": "OAUTH2",
    "toolkit_version": "latest",
    "grant_context": {
      "key": "string"
    },
    "include": [
      "string"
    ],
    "exclude": [
      "string"
    ],
    "available_scopes": [
      "string"
    ]
  }'
```

---

## REST API version

The current REST API version is **v3.1**, served at `https://backend.composio.dev/api/v3.1`. Prefer it for new code and new examples.

`https://backend.composio.dev/api/v3` is the previous version. It is frozen with pinned tool-version defaults and remains supported — existing v3 integrations keep working and do not need to migrate.