# Create connections — POST /v1/ai/connections

URL: https://docs.hanzo.ai/docs/openapi/ai/post-ai-connections

> Connects (or reconnects) a third-party AI account for the org by sealing the supplied key into KMS and upserting the org's provider row.

`POST /v1/ai/connections`

> [AI →](https://docs.hanzo.ai/docs/openapi/ai) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                          |
| ------------- | ---------------------------------------- |
| **Address**   | `https://api.hanzo.ai/v1/ai/connections` |
| **Method**    | `POST`                                   |
| **Operation** | `post_ai_connections`                    |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`   |

Connects (or reconnects) a third-party AI account for the org by
sealing the supplied key into KMS and upserting the org's provider row. The raw
key is sealed BEFORE the row is built and is never persisted or echoed.

## Request

The document declares no body for `POST /v1/ai/connections`. The handler is typed in cloud but its shape is not yet emitted, so the fields are not listed here — ask MCP's `describe` for `post_ai_connections`, which answers from the running route.

## Response

| Status | Body | Meaning                                             |
| ------ | ---- | --------------------------------------------------- |
| `200`  |      | Success.                                            |
| `401`  | —    | No credential, or one this service does not accept. |
| `403`  | —    | A valid credential that may not do this.            |

`200` body — 8 fields.

| Field                | In   | Type    | Always | Description                                             |
| -------------------- | ---- | ------- | ------ | ------------------------------------------------------- |
| `data`               | body | any     | —      | The operation's own result.                             |
| `data2`              | body | any     | —      | A second result the operation defines, when it has one. |
| `msg`                | body | string  | yes    | Empty on success, the reason on failure.                |
| `status`             | body | string  | yes    | One of `ok`, `error`.                                   |
| `data.account_label` | body | string  | —      |                                                         |
| `data.connected`     | body | boolean | —      |                                                         |
| `data.provider`      | body | string  | —      |                                                         |
| `data.updated_at`    | body | string  | —      |                                                         |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo ai connections create
```

**SDK**

**.ts**

```ts
import { Configuration, AiApi } from 'hanzoai';

const api = new AiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postAiConnections();
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AiApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AiApi(client).post_ai_connections()
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.AiAPI.PostAiConnections(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, ai_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = ai_api::post_ai_connections(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AiApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new AiApi(client).postAiConnections();
```

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/ai/connections \
  -H "Authorization: Bearer $HANZO_API_KEY"
```

**MCP**

MCP declares no tool for **ai** — `tools/list` on `https://api.hanzo.ai/v1/mcp` names the products it does reach. Use HTTP or an SDK.

---

[AI API](https://docs.hanzo.ai/docs/openapi/ai) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)