> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Automate 1:1 Coaching Workflows with the Shilo API

> Learn how Shilo's 1:1 Coaching feature works, how to retrieve settings and periods, and how to surface coaching agendas for agents.

Shilo's 1:1 Coaching feature automatically generates structured coaching periods and per-agent agendas by analyzing the calls your team submits. The Coaching API gives you read-only access to your integration's coaching settings, the periods that have been generated, and the individual agent agendas within each period—so you can surface coaching prompts, track completion, and build custom reporting workflows.

## How 1:1 Coaching Works

At the cadence you configure (weekly, semimonthly, or monthly), Shilo generates a new coaching period covering a window of historical call data. Within each period, Shilo creates an agenda for every eligible agent. Each agenda is a personalized coaching document the agent completes before their 1:1 meeting. After agents submit their agendas, Shilo compiles a team digest the manager can use to prepare.

## Coaching Settings

Retrieve your integration's coaching configuration at any time:

```bash theme={null}
curl https://api.shilo.ai/api/v1/coaching/settings \
  -H "x-api-key: YOUR_API_KEY"
```

**Example response:**

```json theme={null}
{
  "integration_id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "enabled": true,
  "cadence": "weekly",
  "customization": {
    "focus": "Improve discovery and objection handling",
    "questions": [
      {
        "id": "question-1",
        "order": 0,
        "text": "What should we practice in our next session?"
      }
    ]
  },
  "usage_limits": {
    "integration_limit_seconds": 36000,
    "per_user_limit_seconds": 3600
  }
}
```

### Key Settings Fields

| Field                     | Description                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| `enabled`                 | Whether the 1:1 Coaching feature is toggled on for this integration, independent of usage limits |
| `cadence`                 | How often coaching periods are generated: `weekly`, `semimonthly`, or `monthly`                  |
| `customization.focus`     | Optional text describing the current coaching focus area                                         |
| `customization.questions` | Custom questions added to every agent agenda                                                     |

### Usage Limits

`integration_limit_seconds` controls the total coaching budget for the entire organization per period, and `per_user_limit_seconds` controls the budget for each individual agent. Both fields follow the same value convention:

| Value                  | Meaning                             |
| ---------------------- | ----------------------------------- |
| `number` (e.g. `3600`) | Maximum coaching seconds allowed    |
| `null`                 | No limit — coaching is unrestricted |
| `0`                    | Coaching is blocked entirely        |

For example, `integration_limit_seconds: 36000` allows up to 10 hours of coaching across all agents per period, while `per_user_limit_seconds: 0` blocks coaching for every individual agent regardless of the organization-wide limit.

## Coaching Periods

A coaching period represents the time window whose call data was used to generate agendas. Each period has both a data range (`period_start` to `period_end`) and a review window (`review_period_end`) during which agents can submit their agendas.

### List Coaching Periods

```bash theme={null}
curl "https://api.shilo.ai/api/v1/coaching/periods?sort=desc&limit=10" \
  -H "x-api-key: YOUR_API_KEY"
```

Add the optional `cadence` filter to narrow results:

```bash theme={null}
curl "https://api.shilo.ai/api/v1/coaching/periods?cadence=weekly&sort=desc" \
  -H "x-api-key: YOUR_API_KEY"
```

### Period Status Fields

| Field           | Values                  | Description                                                                                                   |
| --------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| `review_status` | `open` / `closed`       | `open` while agents can still submit agendas (through `review_period_end`); `closed` once the deadline passes |
| `digest_status` | `pending` / `completed` | `pending` while the team digest is being compiled; `completed` when it is ready                               |

### Retrieve a Single Period

```bash theme={null}
curl https://api.shilo.ai/api/v1/coaching/periods/PERIOD_ID \
  -H "x-api-key: YOUR_API_KEY"
```

The response includes the team digest once `digest_status` is `completed`. Use this to surface the manager-facing summary of the period.

**Example period object:**

```json theme={null}
{
  "id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
  "cadence": "weekly",
  "period_start": "2026-06-01",
  "period_end": "2026-06-07",
  "review_period_end": "2026-06-14",
  "review_status": "open",
  "digest_status": "pending",
  "created_date": "2026-06-08T12:34:56Z",
  "updated_date": "2026-06-08T12:34:56Z"
}
```

## Agent Agendas

Each agent eligible for a coaching period receives a personalized agenda. The Coaching API returns agenda metadata, generation and completion state, and an authenticated Shilo web deep link when available, so you can direct agents into their coaching session. The endpoints do not return the generated agenda's questions or body content.

### List Agendas for a Period

```bash theme={null}
curl "https://api.shilo.ai/api/v1/coaching/periods/PERIOD_ID/agendas" \
  -H "x-api-key: YOUR_API_KEY"
```

Filter by a specific user using any supported user identifier:

```bash theme={null}
curl "https://api.shilo.ai/api/v1/coaching/periods/PERIOD_ID/agendas?user_id=external_user_id:agent-123" \
  -H "x-api-key: YOUR_API_KEY"
```

### Retrieve a Single Agenda

```bash theme={null}
curl https://api.shilo.ai/api/v1/coaching/agendas/AGENDA_ID \
  -H "x-api-key: YOUR_API_KEY"
```

### Key Agenda Fields

| Field               | Description                                                                                                                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agenda_url`        | Authenticated Shilo web deep link to the agent's coaching session. Present only for `ready` agendas with exactly one active user mapping. Requires normal Shilo web authentication; contains no API key or login token |
| `generation_status` | One of `queued`, `processing`, `ready`, `failed`, or `not_eligible`                                                                                                                                                    |
| `is_completed`      | Whether the agent has completed the agenda                                                                                                                                                                             |
| `completed_at`      | ISO-8601 timestamp of completion, or `null`                                                                                                                                                                            |
| `completed_on_time` | Whether the agenda was completed before `review_period_end`, or `null`                                                                                                                                                 |
| `analysis_ready`    | Whether post-submission analysis has produced a stored summary                                                                                                                                                         |
| `external_user_id`  | Your system's user ID for the agent                                                                                                                                                                                    |
| `user_id`           | Shilo's internal user UUID                                                                                                                                                                                             |

## Common Workflows

### Check if Coaching is Enabled

```bash theme={null}
curl https://api.shilo.ai/api/v1/coaching/settings \
  -H "x-api-key: YOUR_API_KEY"
# Check: enabled == true AND per_user_limit_seconds != 0 AND integration_limit_seconds != 0
```

### List Open Periods (Agents Can Still Submit)

```bash theme={null}
curl "https://api.shilo.ai/api/v1/coaching/periods?sort=desc&limit=50" \
  -H "x-api-key: YOUR_API_KEY"
# Filter client-side: review_status == "open"
```

### Get All Agendas for an Agent Across a Period

```bash theme={null}
curl "https://api.shilo.ai/api/v1/coaching/periods/PERIOD_ID/agendas?user_id=external_user_id:agent-123" \
  -H "x-api-key: YOUR_API_KEY"
```

### Direct an Agent to Their Agenda

Retrieve the agent's agenda and send them the `agenda_url` field when it is present:

```bash theme={null}
curl https://api.shilo.ai/api/v1/coaching/agendas/AGENDA_ID \
  -H "x-api-key: YOUR_API_KEY"
# Use response.agenda_url to link the agent directly to their coaching agenda
```

<Note>
  The Coaching API is read-only. You cannot create, update, or delete coaching periods or agendas through the API—these are managed automatically by Shilo based on your configured cadence and the calls submitted to your integration.
</Note>