# List one connection's tools

Returns the tools reachable through one connection, each with the effect policy resolves it to and the rule behind that effect.

## GET `/v1/connectors/connections/{connectionId}/tools`

### Authorization

`Authorization` Bearer token · header required

`Authorization: Bearer <token>` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

or

`Authorization` OAuth2 access token · header required

OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

#### Scopes: `connectors:read`

### Path parameters

- `connectionId` string required  
  min length 1

### Query parameters

- `limit` integer required  
  min 1 · max 100 · default: 20
- `cursor` string  
  min length 1 · max length 4096
- `query` string  
  min length 1 · max length 200
- `effect` string  
  Allowed: `approve`, `require_approval`, `block`
- `team` string  
  min length 1 · max length 255

### Responses

#### 200 Response for status 200

- `$schema` string <uri>  
  Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
- `data` object[] required  
  Array of `object`
  - `address` string required  
    `<connectionId>/<tool>` — the one address grammar. Pass this straight to a connector run.
  - `name` string required  
    Tool name within its connector.
  - `summary` string required  
    One line on what the tool does, from the source spec.
  - `safety` string required  
    What the tool does to the far side, read from the source spec. Not configurable.  
    Allowed: `read_only`, `write`, `destructive`
  - `effect` string required  
    What actually happens when an agent calls this, after policy resolution.  
    Allowed: `approve`, `require_approval`, `block`
  - `decidedBy` object | any required  
    The rule behind `effect`; null when nothing matched and the spec's own default applied.
    - `ruleId` string required  
      Policy rule that decided it.
    - `pattern` string required  
      The pattern that matched.
    - `owner` string required  
      Whose rule it is. Team rules are a floor members cannot loosen.  
      Allowed: `team`, `personal`
  - `inputSchema` object required  
    JSON Schema for the tool's arguments.
- `pagination` object required  
  - `nextCursor` string | any required  
    Opaque cursor for the next page; null when there are no more results.
  - `hasMore` boolean required  
    Whether another page exists after this one.

#### default Problem details (RFC 9457)
Any 4xx/5xx response is one `application/problem+json` document.
- `$schema` string <uri>  
  Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
- `type` string required  
  URL of the documentation page for this error. Derived from `code`.
- `title` string required  
  Human-readable name of the error type. Derived from `code`.
- `status` integer required  
  HTTP status of the response, repeated in the body.
- `detail` string required  
  What went wrong in this request.
- `code` string required  
  Stable snake_case error code. Match on this, not on `detail`.
- `pointer` string  
  RFC 6901 JSON Pointer to the request field or batch entry that failed, for example `/files/37/path`. Present on validation failures.
- `details` object
  Machine-readable context keyed by the error code.
- `suggestions` string[]  
  Recovery steps safe to show to a person.
- `next` string[]  
  Commands or API requests to run next, usable as written.
- `requestId` string required  
  ID of this request, from the `X-Request-Id` header or generated. Quote it when contacting support.

### Try it

#### Server

Base URL: `https://api.spacefast.com`

#### Authorization

Bearer token  
Remember on this device  
Include my values in samples

### Parameters

- `connectionId` path*  
- `limit` query*  
- `cursor` query  
- `query` query  
- `effect` query — `approve`, `require_approval`, `block`  
- `team` query

### Send

#### Request

##### cURL

```bash
curl -X GET "https://api.spacefast.com/v1/connectors/connections/string/tools?limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

##### JavaScript

```javascript
const response = await fetch("https://api.spacefast.com/v1/connectors/connections/string/tools?limit=20", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});
```

##### Python

```python
import requests

response = requests.get(
    "https://api.spacefast.com/v1/connectors/connections/string/tools?limit=20",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)
```

### Response

#### 200 default

```json
{
  "$schema": "http://example.com",
  "data": [
    {
      "address": "string",
      "name": "string",
      "summary": "string",
      "safety": "read_only",
      "effect": "approve",
      "decidedBy": {
        "ruleId": "string",
        "pattern": "string",
        "owner": "team"
      },
      "inputSchema": {
        "property1": null,
        "property2": null
      }
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "hasMore": true
  }
}
```

#### Error Response

```json
{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}
```