> Source: https://wexa.ai/docs/connectors/request-connector

# request-connector

[Can be held for approval](/docs/sdks-and-apis/how-every-tool-call-works#lifecycle-and-governance)

Request a connector with empty configuration, tagged `not_configured`, so a process flow or an agent that depends on it can be published before anyone holds the credentials. Idempotent, and it never takes credentials. Needs the `fabric:skill.write` grant.

**Request a connector**

**Wexa MCP server**

```bash
curl -sS -X POST https://fabric.wexa.ai/mcp/$FABRIC_PROJECT_ID \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "Mcp-Session-Id: $MCP_SESSION_ID" \
  -H "content-type: application/json" -H "accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"request-connector","arguments":{"category":"slack","scope":"organization"}}}'
```

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000017\",\"result\":{\"category\":\"slack\",\"scope\":\"organization\",\"connector\":{\"connectorId\":\"6b1a3d5e7f9c0b2a4d6e8f03\",\"alreadyExists\":false,\"is_configured\":false,\"name\":\"Slack\"}}}"
    }
  ],
  "isError": false
}
```

**REST API**

```bash
curl -sS https://fabric.wexa.ai/v1/request-connector \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"category":"slack","scope":"organization"}'
```

```json
{
  "lifecycle_id": "qlc_000017",
  "result": {
    "category": "slack",
    "scope": "organization",
    "connector": {
      "connectorId": "6b1a3d5e7f9c0b2a4d6e8f03",
      "alreadyExists": false,
      "is_configured": false,
      "name": "Slack"
    }
  }
}
```

**TypeScript SDK**

```ts
import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.requestConnector({
  category: 'slack',
  scope: 'organization'
})
```

```ts
// result is the payload itself, with no `.result` to read
{
  category: 'slack',
  scope: 'organization',
  connector: {
    connectorId: '6b1a3d5e7f9c0b2a4d6e8f03',
    alreadyExists: false,
    is_configured: false,
    name: 'Slack'
  }
}
```

**Python SDK**

```python
from wexa import Fabric

fabric = Fabric()
out = fabric.request_connector(category="slack", scope="organization")
```

```python
# out is the result, already unwrapped
{
    "category": "slack",
    "scope": "organization",
    "connector": {
        "connectorId": "6b1a3d5e7f9c0b2a4d6e8f03",
        "alreadyExists": False,
        "is_configured": False,
        "name": "Slack"
    }
}
```

## Parameters

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `category` | string | Required | The connector's category from [`list-connector-catalog`](/docs/connectors/list-connector-catalog), such as `slack`. Case does not matter. A category that needs no credentials is refused: use `provision-connector`. A category the platform does not know is refused (404). |
| `name` | string | Optional | Display name. Defaults to the connector's catalogue name. |
| `scope` | string | Optional | `organization`: one shared connector for the project (the default). `individual`: your own, which only you see. Anything else is refused. |

**Errors**

- `ValidationError` (400): the platform refused the request, with its own reason.

**Show full response**

- `category`: the category, in lower case.
- `scope`: `organization` or `individual`.
- `connector`: the platform's answer: `connectorId`, `alreadyExists` and `is_configured`, and for a connector this call created also its `name` and `access_scope`.
- `note`: what happened: the connector was created with empty configuration, a placeholder for it already existed and is still not configured, or a configured connector of this kind already exists and nothing was created.

An example response, for a Slack connector this call created.

**Result of request-connector**

**REST API**

```json
{
  "lifecycle_id": "qlc_000017",
  "result": {
    "category": "slack",
    "scope": "organization",
    "connector": {
      "success": true,
      "connectorId": "6b1a3d5e7f9c0b2a4d6e8f03",
      "alreadyExists": false,
      "is_configured": false,
      "name": "Slack",
      "access_scope": "organization"
    },
    "note": "created with empty configuration and tagged not_configured. It has no runnable actions until its credentials are saved in the Fabric console (Connect > Connectors)."
  }
}
```

**Wexa MCP server**

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000017\",\"result\":{\"category\":\"slack\",\"scope\":\"organization\",\"connector\":{\"success\":true,\"connectorId\":\"6b1a3d5e7f9c0b2a4d6e8f03\",\"alreadyExists\":false,\"is_configured\":false,\"name\":\"Slack\",\"access_scope\":\"organization\"},\"note\":\"created with empty configuration and tagged not_configured. It has no runnable actions until its credentials are saved in the Fabric console (Connect > Connectors).\"}}"
    }
  ],
  "isError": false
}
```

**TypeScript SDK**

```ts
// the object you get back IS the result — there is no `.result` to read
{
  "category": "slack",
  "scope": "organization",
  "connector": {
    "success": true,
    "connectorId": "6b1a3d5e7f9c0b2a4d6e8f03",
    "alreadyExists": false,
    "is_configured": false,
    "name": "Slack",
    "access_scope": "organization"
  },
  "note": "created with empty configuration and tagged not_configured. It has no runnable actions until its credentials are saved in the Fabric console (Connect > Connectors)."
}

// The TS SDK names these camelCase — lifecycleId, traceId — where Python uses
// lifecycle_id and trace_id. Both are non-enumerable: readable, but omitted by
// Object.keys() and JSON.stringify(). `result.lifecycleId` here is undefined.
result.lifecycleId // 'qlc_000017'
```

**Python SDK**

```python
# a dict subclass; `result` is already unwrapped
{
 "category": "slack",
 "scope": "organization",
 "connector": {
  "success": True,
  "connectorId": "6b1a3d5e7f9c0b2a4d6e8f03",
  "alreadyExists": False,
  "is_configured": False,
  "name": "Slack",
  "access_scope": "organization"
 },
 "note": "created with empty configuration and tagged not_configured. It has no runnable actions until its credentials are saved in the Fabric console (Connect > Connectors)."
}

out.lifecycle_id  # 'qlc_000017' — an attribute, not a key
```

**More details**

The connector appears in the project for the person responsible to configure in the console. Until then [`list-connectors`](/docs/connectors/list-connectors) lists it with no actions, and nothing on it can run.

When a matching connector already exists in the project, it is returned and nothing is created: a shared connector matches on its category, an individual one on its category and its owner. A connector that needs no credentials is provisioned with [`provision-connector`](/docs/connectors/provision-connector) instead, and one you hold the credentials for with [`configure-connector`](/docs/connectors/configure-connector).

The error code on the 422 is `S4:validate-input`, and the message on the 404 and 400 is the platform's own reason. Arguments are validated before policy runs, so a missing or unknown `category` is refused before anything is held.

Marked consequential: it is audited in full, and a policy rule may hold it for a person to approve. The project's write gate, when a project admin has turned it on (it is off by default), holds it this way when an API key or SDK session calls it.

Every tool call works the same way: [How every tool call works](/docs/sdks-and-apis/how-every-tool-call-works).