# Get required scopes for tools

**Documentation:** /reference/api-reference/tools/postV3_1ToolsScopesRequired

Resolves required scopes for the specified tools at a given toolkit version. All requested tools must belong to the same toolkit. Returns the flat scope union plus per-tool structured scope requirements when available.

---

## POST `/api/v3.1/tools/scopes/required`

**Endpoint:** `https://backend.composio.dev/api/v3.1/tools/scopes/required`

**Summary:** Get required scopes for tools

Resolves required scopes for the specified tools at a given toolkit version. All requested tools must belong to the same toolkit. Returns the flat scope union plus per-tool structured scope requirements when available.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Request Body

**Schema:**

- `tools` (array<string>) *(required)*: Tool slugs to resolve scopes for. All tools must belong to the same toolkit.
- `version` (string): Toolkit version to resolve scopes against for the requested toolkit. Defaults to the pinned HTTP version when omitted.

**Example:**

```json
{
  "tools": [
    "string"
  ],
  "version": "string"
}
```

### Responses

#### 200 - Successfully retrieved scopes for the specified tools

**Response Schema:**

- `scopes_required` (array<string>) *(required)*: A combined list of all unique scopes required by the specified tools
- `per_tool_requirements` (array<object>) *(required)*: Per-tool structured scope requirements. Null scope_requirements marks unmigrated legacy tools.
  - Array items:
    - `tool` (string) *(required)*
    - `scope_requirements` (object,null) *(required)*

**Example Response:**

```json
{
  "scopes_required": [
    "string"
  ],
  "per_tool_requirements": [
    {
      "tool": "string",
      "scope_requirements": null
    }
  ]
}
```

#### 400 - Bad request - Invalid body parameters or tools from different toolkits

**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 - Authentication credentials are missing or invalid

**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 - Not found - One or more tools could not be resolved for the requested version

**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 - Something went wrong on the server

**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/tools/scopes/required" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [
      "string"
    ],
    "version": "string"
  }'
```