# Agent keys and kill switches (AI agents)

> Tickwire API reference, generated from the OpenAPI document the services export. Base URL: https://api.tickwire.io. Replace YOUR_API_KEY and YOUR_ACCOUNT_ID with your own values; use a sandbox key (twsk_…) to experiment.

Source: https://tickwire.io/docs/reference/agent-admin/

### GET /v1/agent-audit

**Agent Audit**

Auth: `X-API-Key`

The agent audit log, newest first (by `seq`). Cursor-paginated:
`{entries, has_more, next_cursor}`; `before` (a `seq`) still works.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `agent_key_id` | query | `string \| null` | no |  |
| `account_id` | query | `string \| null` | no |  |
| `before` | query | `integer \| null` | no |  |
| `limit` | query | `integer` | no | Page size, 1..500 (default 100). |
| `cursor` | query | `string \| null` | no | The next_cursor of the previous page, unchanged. |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/v1/agent-audit' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/v1/agent-audit",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/v1/agent-audit");
console.log(result);
tw.close();
```

### GET /v1/agent-keys

**List Agent Keys**

Auth: `X-API-Key`

Agent keys of this tenant (never the key values), oldest first.
Cursor-paginated: `{data, has_more, next_cursor}`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | `integer` | no | Page size, 1..500 (default 100). |
| `cursor` | query | `string \| null` | no | The next_cursor of the previous page, unchanged. |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/v1/agent-keys' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/v1/agent-keys",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/v1/agent-keys");
console.log(result);
tw.close();
```

### POST /v1/agent-keys

**Create Agent Key** · takes `Idempotency-Key`

Auth: `X-API-Key`

Create an agent key scoped to accounts. The `key` is shown once.

`Idempotency-Key` is honoured: a replay returns the same key record
without minting another key, with `key: null` and a `key_notice`
saying it was already shown.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | `string \| null` | no |  |
| `X-Actor` | header | `string \| null` | no |  |
| `X-Reason` | header | `string \| null` | no |  |

Request body: `object` (required)

Responses:

- `201` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `409` [`idempotency_conflict`](https://tickwire.io/docs/errors/idempotency_conflict/)

curl:

```bash
curl -sS -X POST 'https://api.tickwire.io/v1/agent-keys' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: my-request-1' \
  -H 'X-Reason: why you are doing this' \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent","account_ids":["YOUR_ACCOUNT_ID"],"read_only":false}'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "POST",
        "/v1/agent-keys",
        json={
            "name": "my-agent",
            "account_ids": ["YOUR_ACCOUNT_ID"],
            "read_only": False,
        },
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("POST", "/v1/agent-keys", {
  body: {"name":"my-agent","account_ids":["YOUR_ACCOUNT_ID"],"read_only":false},
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### GET /v1/agent-keys/{key_id}

**Get Agent Key**

Auth: `X-API-Key`

One agent key record.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `key_id` | path | `string` | yes |  |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/v1/agent-keys/KEY_ID' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/v1/agent-keys/KEY_ID",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/v1/agent-keys/KEY_ID");
console.log(result);
tw.close();
```

### PATCH /v1/agent-keys/{key_id}

**Patch Agent Key**

Auth: `X-API-Key`

Rename, re-scope or flip read-only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `key_id` | path | `string` | yes |  |
| `X-Actor` | header | `string \| null` | no |  |
| `X-Reason` | header | `string \| null` | no |  |

Request body: `object` (required)

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X PATCH 'https://api.tickwire.io/v1/agent-keys/KEY_ID' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-Reason: why you are doing this' \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-agent"}'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "PATCH",
        "/v1/agent-keys/KEY_ID",
        json={"name": "my-agent"},
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("PATCH", "/v1/agent-keys/KEY_ID", {
  body: {"name":"my-agent"},
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### DELETE /v1/agent-keys/{key_id}

**Revoke Agent Key**

Auth: `X-API-Key`

Revoke an agent key (irreversible).

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `key_id` | path | `string` | yes |  |
| `X-Actor` | header | `string \| null` | no |  |
| `X-Reason` | header | `string \| null` | no |  |

Responses:

- `204` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X DELETE 'https://api.tickwire.io/v1/agent-keys/KEY_ID' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-Reason: why you are doing this'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "DELETE",
        "/v1/agent-keys/KEY_ID",
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("DELETE", "/v1/agent-keys/KEY_ID", {
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### PUT /v1/agent-keys/{key_id}/kill-switch

**Set Key Kill Switch**

Auth: `X-API-Key`

Engage or release the kill switch of one agent key.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `key_id` | path | `string` | yes |  |
| `X-Actor` | header | `string \| null` | no |  |
| `X-Reason` | header | `string \| null` | no |  |

Request body: `object` (required)

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X PUT 'https://api.tickwire.io/v1/agent-keys/KEY_ID/kill-switch' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-Reason: why you are doing this' \
  -H 'Content-Type: application/json' \
  -d '{"engaged":true,"reason":"stop this agent"}'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "PUT",
        "/v1/agent-keys/KEY_ID/kill-switch",
        json={"engaged": True, "reason": "stop this agent"},
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("PUT", "/v1/agent-keys/KEY_ID/kill-switch", {
  body: {"engaged":true,"reason":"stop this agent"},
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### GET /v1/agent-kill-switches

**List Kill Switches**

Auth: `X-API-Key`

Engaged account kill switches (agent-key switches are on each key), by
account id. Cursor-paginated: `{accounts, has_more, next_cursor}`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | `integer` | no | Page size, 1..500 (default 100). |
| `cursor` | query | `string \| null` | no | The next_cursor of the previous page, unchanged. |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/v1/agent-kill-switches' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/v1/agent-kill-switches",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/v1/agent-kill-switches");
console.log(result);
tw.close();
```

### PUT /v1/agent-kill-switches/accounts/{account_id}

**Set Account Kill Switch**

Auth: `X-API-Key`

Engage or release the agent kill switch of one account.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `account_id` | path | `string` | yes |  |
| `X-Actor` | header | `string \| null` | no |  |
| `X-Reason` | header | `string \| null` | no |  |

Request body: `object` (required)

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `404` [`account_not_found`](https://tickwire.io/docs/errors/account_not_found/)

curl:

```bash
curl -sS -X PUT 'https://api.tickwire.io/v1/agent-kill-switches/accounts/YOUR_ACCOUNT_ID' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-Reason: why you are doing this' \
  -H 'Content-Type: application/json' \
  -d '{"engaged":true,"reason":"stop all agents"}'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "PUT",
        "/v1/agent-kill-switches/accounts/YOUR_ACCOUNT_ID",
        json={"engaged": True, "reason": "stop all agents"},
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("PUT", "/v1/agent-kill-switches/accounts/YOUR_ACCOUNT_ID", {
  body: {"engaged":true,"reason":"stop all agents"},
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```