# API Reference: Agents

## GET `/agents`

**Summary:** Get Agents

**Description:** Get Agents

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/agents' \
  -H 'accept: application/json'
```

---

## POST `/agents/templates`

**Summary:** Create Template

**Description:** Create Template

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `AgentTemplateCreate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/agents/templates' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## POST `/agents/instances`

**Summary:** Create Instance

**Description:** Create Instance

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `AgentInstanceCreate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/agents/instances' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## PATCH `/agents/{id}/status`

**Summary:** Update Status

**Description:** Update Status

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `id` | path | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `AgentInstanceStatusUpdate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PATCH' \
  'http://localhost:8000/api/v1/agents/{id}/status' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## PATCH `/agents/{id}/config`

**Summary:** Update Config

**Description:** Update Config

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `id` | path | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `AgentConfigUpdate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PATCH' \
  'http://localhost:8000/api/v1/agents/{id}/config' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## POST `/agents/{id}/webhook`

**Summary:** Webhook Receiver

**Description:** Webhook Receiver

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `id` | path | Yes | string |  |
| `token` | query | No | string |  |
| `sync` | query | No | boolean |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/agents/{id}/webhook?token=<token>&sync=<sync>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## POST `/agents/{id}/run`

**Summary:** Manual Trigger

**Description:** Manual Trigger

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `id` | path | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`

#### Responses

| Status Code | Description |
|-------------|-------------|
| `202` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/agents/{id}/run' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## GET `/agents/{id}/triggers`

**Summary:** Get Agent Triggers

**Description:** Get Agent Triggers

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `id` | path | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/agents/{id}/triggers' \
  -H 'accept: application/json'
```

---

## POST `/agents/{id}/triggers`

**Summary:** Create Agent Trigger

**Description:** Create Agent Trigger

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `id` | path | Yes | string |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `AgentTriggerCreate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/agents/{id}/triggers' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## DELETE `/agents/triggers/{trigger_id}`

**Summary:** Delete Agent Trigger

**Description:** Delete Agent Trigger

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `trigger_id` | path | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'DELETE' \
  'http://localhost:8000/api/v1/agents/triggers/{trigger_id}' \
  -H 'accept: application/json'
```

---

## POST `/agents/{id}/metrics/reset`

**Summary:** Reset Agent Metrics

**Description:** Reset Agent Metrics

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `id` | path | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/agents/{id}/metrics/reset' \
  -H 'accept: application/json'
```

---

## GET `/agents/{id}/telemetry`

**Summary:** Get Telemetry

**Description:** Get Telemetry

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `id` | path | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/agents/{id}/telemetry' \
  -H 'accept: application/json'
```

---

## GET `/agents/{id}/dependencies`

**Summary:** Get Dependencies

**Description:** Get Dependencies

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `id` | path | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/agents/{id}/dependencies' \
  -H 'accept: application/json'
```

---

## POST `/agents/deploy`

**Summary:** Deploy Agent

**Description:** One-click agent deployment (Design Doc CUJ 1).
Atomically creates: Template → Session → Instance → Locks Session → Injects initial prompt → Starts loop.

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `DeployAgentRequest` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/agents/deploy' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## DELETE `/agents/{id}`

**Summary:** Delete Agent

**Description:** Delete Agent

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `id` | path | Yes | string |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'DELETE' \
  'http://localhost:8000/api/v1/agents/{id}' \
  -H 'accept: application/json'
```

---

