# Crew how-tos

A **crew how-to** is one of the company's own procedures for its field crews: "Sealcoat mix and coats", "Mowing heights by season", "Locked gate". It has a title, the services it shows on, and steps in the order the work is done, in English and Spanish, with photos. Crews open it on the visit it fits, and when a crew member asks a question in the crew app the answer comes only from these how-tos. In the app it lives under **Crew how-to**.

The API **reads how-tos, reads what crews asked, and writes drafts**. A draft changes nothing a crew sees: a person in the office opens it in the editor, checks it and saves. Publishing, archiving, reordering and step photos stay with a person in the app. A workspace needs TruTec Bid or Build and crew scheduling; other workspaces get `403`.

## List how-tos

`GET /v1/crew-how-tos` returns the how-tos in the order crews see them, a page at a time (`limit`, `offset`).

| Filter | What it does |
|---|---|
| `q` | Words in the title, the steps or the category |
| `category` | One category, for example `Safety` |
| `service` | A service name: the how-tos a crew visit doing that service lists |
| `include_archived` | Also return archived how-tos (crews do not see those) |
| `updated_after` | Changed after this time (ISO 8601), for syncing |

```bash
curl "https://trutec.ai/api/v1/crew-how-tos?service=Sealcoating" \
  -H "X-API-Key: $TRUTEC_API_KEY"
```

Each how-to says how many steps and photos it has, whether every step is written in Spanish (`has_spanish`), how often crews opened it in the last 30 days (counted once per person per day) and how many crew questions it answered.

## Get one how-to

`GET /v1/crew-how-tos/{how_to_id}` adds the steps: `position`, `text`, `text_es` and `has_photo`.

## What crews keep asking

`GET /v1/crew-how-tos/gaps` returns the questions crews asked in the last 90 days that no how-to answered and that nobody has dealt with. Questions that ask the same thing are counted together, most asked first.

```json
{
  "question": "How long before we can stripe over fresh sealcoat?",
  "times_asked": 4,
  "people": [{"user_id": 5341, "name": "Luis Ortega"}, {"user_id": 5342, "name": "Dana Reyes"}],
  "last_asked_at": "2026-11-09T19:04:00Z",
  "also_asked_as": ["how long before striping over new sealcoat"],
  "job_ids": [80112],
  "question_ids": [9912, 9907, 9881, 9840]
}
```

## What crews asked

`GET /v1/crew-questions` returns every question crews asked and what they were told, newest first: the last 7 days unless `days` (1 to 90) or `since` says otherwise. `answered=false` returns the ones that went to a supervisor because no how-to covered them. `summary` counts the whole period: asked, answered from a how-to, sent to a supervisor, and answers the crew said did not help.

## Draft a how-to

`POST /v1/crew-how-tos/drafts` writes a draft of a new how-to, or of new words for an existing one when you send `how_to_id`.

```bash
curl -X POST "https://trutec.ai/api/v1/crew-how-tos/drafts" \
  -H "X-API-Key: $TRUTEC_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "title": "Striping after sealcoat",
    "category": "Striping",
    "services": ["Line striping"],
    "steps": [
      {"text": "Wait 24 hours after the last coat before you stripe.",
       "text_es": "Espera 24 horas después de la última capa antes de pintar."}
    ],
    "note": "Crews asked this 4 times this week."
  }'
```

The answer is the draft with `status: "waiting_for_review"` and a `review_url` that opens it in the editor. Until a person saves it there:

- crews do not see it, and no crew answer uses it;
- the how-to named by `how_to_id` is unchanged.

Steps are words only (at most 30). Photos are added in the editor, and a draft for an existing how-to keeps the photos on its steps. Write how this company does the work, from what the company told you; a how-to is not the place for general trade advice. `GET /v1/crew-how-tos/drafts` lists the drafts still waiting; at most 50 can wait at once (`409` after that).
