Hook API v1.0.0

Read your organizations, phishing simulation results and training progress. Every count equals what Native Reports shows for the same scope. How v1 changes over time: https://api.hooksecurity.co/v1/docs#versioning

Getting started

An admin creates a key in Hook under Settings › API keys and copies it once. Send it on every request:

curl https://api.hooksecurity.co/v1/organizations \
  -H "Authorization: Bearer hook_live_…"

Keys never go in a URL; a key in a query string is refused. Revoking a key in Settings stops it on its next request. To try every route in the browser, open the API explorer. Counts and rates equal what Native Reports shows for the same organization and period.

What a key can read

• All clients: an MSP's key reads the MSP and every client in its tree, including clients added later.
• This organization: an organization's own key reads only that organization.

Coverage is checked on every request against the current organization tree. Anything outside it returns the same 404 not_found as an ID that never existed. A key whose organization is suspended gets 403 organization_suspended.

Only Hook-native data is served. The native flags show whether an organization is on Hook-native simulations and training today; campaigns and enrollments it ran natively before switching off are still returned.

Paging

Lists return { "data": [...], "next_cursor": "..." }. Pass next_cursor back as cursor until it is null. Page size is limit, up to 500 (100 for campaigns and enrollment batches). Cursors are opaque, expire after 24 hours and only work with the same key and filters.

Per-person results have no change feed yet: re-read campaigns active in the last 30 days to pick up new clicks and reports.

Errors

Errors are application/problem+json (RFC 9457) with a stable code and a request_id to quote to support.

Rate limits

Each key has a per-minute limit, enforced at Hook's edge in front of the API. Over it, requests get 429 rate_limited with a Retry-After header in seconds; wait that long before retrying.

AI assistants (MCP)

The API is also a Model Context Protocol server at /mcp (Streamable HTTP, stateless, JSON responses), with the same key and coverage. There is nothing to install: an AI client needs the URL and a key. The 10 read-only tools below return exactly what the matching REST endpoints return, and the AI model always runs on the client's side, never Hook's.

Supported protocol versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07. Discovery: the server card (/mcp/server-card) and /.well-known/ai-catalog.json.

Connect

Claude Code, including the Code tab of the Claude desktop app. Run it once in a terminal, replacing the key; it is saved for every folder and survives restarts, and sessions started afterwards see it:

claude mcp add --scope user --transport http hook https://api.hooksecurity.co/mcp \
  --header "Authorization: Bearer hook_live_…"

Any other client (Cursor, VS Code, your own agent): URL https://api.hooksecurity.co/mcp, header Authorization: Bearer hook_live_…. To try the tools by hand, run the official MCP Inspector (npx @modelcontextprotocol/inspector) and connect with the same URL and header.

Names of organizations, campaigns, courses and people are customer-controlled text and are returned only as data. A tool error returns { "code", "title" } with the same codes as the REST errors below.

Tools

hook_whoami

Who am I. What this API key can read: its coverage and how many organizations it covers. Call first to orient.

No arguments.

hook_list_organizations

List organizations. Organizations this key covers, with type, state, active user count and whether they use Hook-native simulations and training.

hook_get_organization

Get organization. One organization by ID.

hook_list_campaigns

List phishing campaigns. Phishing simulation campaigns with status, recipient counts, outcome counts and click and engagement rates, optionally for one organization.

hook_get_campaign

Get phishing campaign. One campaign's status and counts.

hook_list_campaign_results

List campaign results per person. Who received a campaign and what they did: opened, clicked, landed, engaged, reported, with times. Filter by outcome, for example clicked, to list who clicked.

hook_list_enrollment_batches

List training assignments. Training enrollment batches with course, due date and assigned, completed, outstanding and overdue counts.

hook_get_enrollment_batch

Get training assignment. One enrollment batch's course, due date and assigned, completed, outstanding and overdue counts.

hook_list_enrollments

List training progress per learner. One row per learner per assignment, with status, due date and whether it is overdue. Filter by organization, batch or status (overdue is a status filter).

hook_list_billing_seats

List billable users per month. How many users to bill each client for in a month: the highest daily count of active people while the organization was active. Native Accounts only; organizations still on the legacy platform are not listed. days_inactive counts days the organization was suspended or expired, which are never billed. The current month is a figure so far (month_complete false).

Versioning and changes

This is version 1 of the API. Everything under /v1 and every MCP tool keeps working as documented here: v1 only grows.

What we add without notice

• New endpoints and MCP tools.
• New optional query parameters and tool arguments.
• New fields in responses and tool results.
• New values in fields listed as extensible (x-extensible-enum in the OpenAPI document), such as a new campaign status.
• New error codes.

Build your client to ignore fields it does not know and to handle a value it does not recognise, for example by showing it as it is. A client generated from /v1/openapi.json does this by default: response objects are open, and extensible values are typed as strings.

What counts as breaking

• Removing or renaming an endpoint, tool, field or value.
• Changing a field's type or meaning.
• Making an optional parameter required, or refusing input we accept today.

Breaking changes come only in a new major version (/v2), which would run alongside v1. The one exception is a fix for a security or privacy defect, which we make in v1 and announce in the changelog.

Deprecation

Before anything is removed, it is marked deprecated in this reference and in the changelog, and responses that use it carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) with the removal date. Removal comes at least 12 months after deprecation. An MCP tool name never changes meaning: a replacement tool gets a new name, and the old one keeps working until its sunset date.

Changelog

The version in this page's title and in /v1/openapi.json rises with every change: a minor version for additions, a patch for wording.

Support and request IDs

Every response carries an x-request-id header, and every error body a request_id. Quote it to Hook support: it finds the exact request in our logs. Hook logs which key, route or tool, outcome and timing for every call, never key secrets, people's names or emails, or tool arguments.

Reference

Generated from /v1/openapi.json (OpenAPI 3.1).