API Documentation

Manage your rotations programmatically with the RotaHog REST API. Available on Team Toolkit and Ops Pro plans.

Base URL: https://rotahog.com/api/v1
Authentication: Bearer token via Authorization header
Format: JSON
OpenAPI spec: https://rotahog.com/api/v1/openapi

Authentication

All API requests require a Bearer token. Create one from your API Tokens page.

curl -H "Authorization: Bearer rh_your_token_here" \
  https://rotahog.com/api/v1/rotations

Tokens come in two scopes:

read — List and view rotations and turns
read_write — All read operations plus completing, substituting, and cancelling turns

Rate Limits

All endpoints are rate-limited to 30 requests per minute per token. Exceeding this returns a 429 response.

Endpoints

Rotations

GET /api/v1/rotations

List all rotations you own or participate in.

Query parameters

Param	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 25, max: 100)

Response

{
  "rotations": [
    {
      "token": "wk_rotation_1",
      "task_name": "Weekly standup host",
      "recurrence": "weekly",
      "start_date": "2026-09-27",
      "timezone": "UTC",
      "members_count": 3,
      "created_at": "2026-09-27T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "has_more": false }
}

GET /api/v1/rotations/:token

Get rotation details including members and next upcoming turn.

Response

{
  "rotation": {
    "token": "wk_rotation_1",
    "task_name": "Weekly standup host",
    "recurrence": "weekly",
    "start_date": "2026-09-27",
    "timezone": "UTC",
    "members_count": 3,
    "created_at": "2026-09-27T10:00:00Z",
    "members": [
      { "id": 1, "name": "Alice", "email": "alice@example.com", "slack_handle": null }
    ],
    "next_turn": {
      "id": 42, "scheduled_date": "2026-10-04", "status": "upcoming", "acting_member": "Alice"
    }
  }
}

Turns

GET /api/v1/rotations/:token/turns

List turns for a rotation with optional filters.

Query parameters

Param	Type	Description
`status`	string	Filter by status: `upcoming`, `overdue`, `completed`, `cancelled`, `missed`
`from`	date	Start date filter (ISO 8601)
`to`	date	End date filter (ISO 8601)
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 25, max: 100)

GET /api/v1/rotations/:token/turns/current

Get the next upcoming turn for a rotation — who's on duty now.

Response

{
  "turn": {
    "id": 42,
    "scheduled_date": "2026-10-04",
    "status": "upcoming",
    "completable": true,
    "acting_member": { "id": 1, "name": "Alice", "email": "alice@example.com", "slack_handle": null },
    "original_member": null,
    "backup_member": null,
    "substituted_at": null,
    "backup_assigned_at": null
  }
}

Actions read_write scope

POST /api/v1/rotations/:token/turns/:id/complete

Mark a turn as completed. Only the rotation owner or acting member can complete a turn.

POST /api/v1/rotations/:token/turns/:id/substitute

Assign a substitute for a turn. Requires the "Find a substitute" plan feature.

Request body

{ "substitute_member_id": 2 }

POST /api/v1/rotations/:token/turns/:id/cancel

Cancel a turn. Only the rotation owner can cancel. Requires the "Cancel a turn" plan feature.

Errors

Status	Meaning
`401`	Missing or invalid API token
`403`	Plan doesn't include API access, insufficient scope, or not authorized
`404`	Resource not found
`422`	Validation error (e.g., turn not completable)
`429`	Rate limit exceeded

All errors return JSON:

{ "error": "Not authorized" }

Also available as an MCP server for AI assistants. View MCP documentation.