Crewhu API Patterns git:20260503.5be5d8cA

Immutable. This exact content is served forever at /api/v1/blob/4c79c5458ff7414c.

---
name: "Crewhu API Patterns"
when_to_use: "When working with Crewhu authentication headers, pagination, navigation tools, or error handling for the Crewhu MCP server"
description: >
  Use this skill when working with the Crewhu MCP tools — token-based
  authentication via the `X-Crewhu-Api-Token` header, the
  navigation pattern (`crewhu_navigate`, `crewhu_back`, `crewhu_status`),
  read-heavy tool surface, and error handling.
triggers:
  - crewhu api
  - crewhu authentication
  - crewhu pagination
  - crewhu mcp
  - crewhu navigate
  - crewhu token
---

# Crewhu MCP Tools & API Patterns

## Overview

The Crewhu MCP server exposes CSAT/NPS surveys, employee recognition
(badges), and prize/redemption data for MSP teams. The tool surface is
read-heavy — only `crewhu_badges_update_contest` performs writes.

## Connection & Authentication

Crewhu uses an API token passed via header:

| Header | Value |
|--------|-------|
| `X-Crewhu-Api-Token` | The raw API token |

The gateway maps the environment variable `X_CREWHU_APITOKEN` onto the
`X-Crewhu-Api-Token` header automatically.

```bash
export X_CREWHU_APITOKEN="your-crewhu-api-token"
```

## Navigation Tools

Crewhu provides three navigation/meta tools that complement the
functional surface:

| Tool | Purpose |
|------|---------|
| `crewhu_navigate` | Discover available tool domains (surveys, users, badges, prizes) |
| `crewhu_back` | Pop back to the prior navigation context |
| `crewhu_status` | Health/status check for the Crewhu connection |

When you do not yet know which tool to call, start with
`crewhu_navigate` to enumerate the available domains.

## Functional Tool Surface

Tools follow the `crewhu_<domain>_<action>` pattern. The four
functional domains are surveys, users, badges, and prizes — see the
domain skills for detail.

## Pagination

Crewhu list endpoints typically accept page/limit-style parameters.
Always check whether more pages exist before claiming a result set is
complete; for survey trend analysis, pull enough history to have a
stable denominator.

## Error Handling

| Status | Meaning | Action |
|--------|---------|--------|
| 401 | Missing or invalid token | Re-check `X_CREWHU_APITOKEN` |
| 403 | Token valid but not authorized for this resource | Check token scope |
| 404 | Unknown survey / user / badge / prize ID | Re-list to confirm |
| 429 | Rate limit | Back off and retry |

## Best Practices

- Treat almost every Crewhu tool as read-only — only
  `crewhu_badges_update_contest` mutates data; flag it explicitly
  before invoking.
- For CSAT trend analysis, pull a wide enough window
  (last 90 days minimum) to avoid sampling noise.
- For multi-team MSPs, group survey results by user/team after fetching.

## Related Skills

- [surveys](../surveys/SKILL.md) - CSAT/NPS analysis (the primary skill)