API Reference

Authentication

Create an API key in Settings → API. Pass it as a Bearer token on every request. Keys are shown once — store them safely.

curl https://www.gumhop.com/api/v1/me \
  -H "Authorization: Bearer gh_live_…"

Errors & rate limits

Errors return a JSON body { "error": "message" } with an appropriate status: 401 (invalid or missing key), 400 (bad input), 404 (not found), 429 (rate limit exceeded).

The API is capped at 120 requests per 60-second window per account(shared across all of that account's keys). Requests over the cap are rejected with 429 { "error": "rate limit exceeded" } — retry once the window resets.

Workspaces & teams

Gumhop has shared team workspaces, but the v1 API is scoped to the account that owns the key — it reads and writes only the folders, lists, and tasks you created. That spans your personal space and anything you authored in a team space, but it never includes content a teammate created in a shared workspace, even though the app shows that content to you.

• GET /lists and GET /tasks return only your own rows. Filtering by a teammate's list_id yields an empty result; a teammate's task id returns 404.
• POST /tasks targets a list you own — adding a task to a teammate's list returns 404. Omitting list_id drops the task into your first owned list.
• POST /lists creates the list in your Personal workspace, unless you nest it under a folder_idyou own in another workspace — then the list inherits that folder's workspace.
• Every folder, list, and task carries a read-only workspace_id. There are no v1 endpoints for workspaces, members, invites, assignees, comments, mentions, or notifications yet.

Webhooks

Set a webhook URL in Settings → API. Gumhop POSTs task.created and task.completed events:

Webhooks are user-scoped, not workspace-scoped: each event is delivered only to the webhook URL of the task's owner — the account that created it. You receive events for tasks you created (including when a teammate completes one of yours), but never for tasks a teammate owns, even in a shared workspace.

{
  "event": "task.completed",
  "task": {
    "id": "uuid", "title": "...", "status": "done",
    "priority": 2, "pinned": false,
    "due_date": "2026-07-01", "due_time": "14:30:00",
    "notes": null, "source": "api", "ai_status": "none",
    "list_id": "uuid", "chips": [], "completed_at": "...", "created_at": "..."
  }
}

The payload is a subset of the full task object — it omits tags, original_text, and updated_at, which are present on GET responses. source is api for tasks created via this API and app for tasks created in the app.

Verifying signatures

If you set a signing secret, each delivery includes an X-Gumhop-Signature-256 header: sha256=<hmac> of the raw body.

// Node.js
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

# Python
import hmac, hashlib
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(header, expected)

Using Gumhop from an AI agent

1. Create an API key and store it as a secret in your agent runtime.
2. To capture a task, POST /tasks with {"text":"…","parse":true} and let Gumhop extract a clean title, due date/time, priority, notes, and contact/location/link/meeting chips. Subtasks the parser detects are not created via the API.
3. To check progress, GET /tasks?status=todo.
4. To complete a task, PATCH /tasks/:id with {"status":"done"} — which also fires your task.completed webhook.
5. To give the user their card pull for that completion, POST /rewards/complete with {"task_id":"…"}— idempotent, so it's always safe to call.