---
title: "Get required scopes for tools"
method: POST
path: "/api/v3.1/tools/scopes/required"
tags: ["Tools"]
---

# Get required scopes for tools

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

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.

## Request body

- object
  - `tools` 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.

## Response `200`

Successfully retrieved scopes for the specified tools

- object
  - `scopes_required` string[], required — A combined list of all unique scopes required by the specified tools
  - `per_tool_requirements` object[], required — Per-tool structured scope requirements. Null scope_requirements marks unmigrated legacy tools.
    - `tool` string, required
    - `scope_requirements` object, nullable, required
      - `all_of` union[], required
        - union
          - string
          - object
            - `any_of` union[], required
              - …
            - `when` object
            - `source` string[]
      - `source` string[]

## Other responses

- `400` — Bad request - Invalid body parameters or tools from different toolkits
- `401` — Unauthorized - Authentication credentials are missing or invalid
- `404` — Not found - One or more tools could not be resolved for the requested version
- `500` — Internal server error - Something went wrong on the server

---

[API](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1.md) · [All operations](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/composiohq/composio-platform-api-v3-1/versions/4239836857f8/schema)