API Reference

Authentication

Create an API key in Settings → API. Pass it as a Bearer token on every request. Keys are shown once, so 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_id you own in another workspace, in which case the list inherits that folder's workspace.
• Dependencies (“blocked by” links) follow the same rule: both tasks must be ones you created, in the same workspace, and you must still be a member who can edit it. Links to a teammate's task are left out of blocked_by and GET /dependencies, though open_blocker_count still counts every open blocker.
• 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.

Recurring series

A series is a blueprint plus a schedule. The next copy doesn't exist until its time arrives: between cycles there is no task, only the series. Each copy is an ordinary task with series_id set, so it fires task.created, rewards once, and behaves like any other task. Series are workspace-scoped: anyone who can edit the workspace can read and manage them.

The repeat object

{
  "mode": "fixed",              // "fixed" | "after_completion"  (default "fixed")
  "unit": "week",               // "day" | "week" | "month" | "year"  (required)
  "every": 2,                   // default 1
  "weekdays": ["mon","thu"],    // week only
  "month_day": 31,              // 1..31 | -1 (last day); month/year
  "nth": -1, "nth_weekday": "fri",  // month/year, instead of month_day
  "month": 3,                   // year only
  "starts_on": "2026-09-22",    // fixed only; default: the task's due date, else today
  "appears": "08:00",           // "HH:MM" | "exact"  (default "08:00")
  "due": "appear_day",          // "none" | "appear_day" | "offset"
  "due_offset_days": 0,
  "if_open": "skip",            // "skip" | "shift" | "stack"  (fixed only)
  "ends_on": null,              // at most one of ends_on / ends_after
  "ends_after": null,
  "push": true                  // push when a copy appears
}

An invalid rule returns 400 with {"error":"invalid repeat: …"}. Month-end days clamp (Jan 31 → Feb 28); after_completion rules are interval-only, so they take no weekdays, month day, nth or month.

curl -X POST https://www.gumhop.com/api/v1/series \
  -H "Authorization: Bearer gh_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"Team sync","list_id":"<id>","due_time":"09:00",
       "repeat":{"unit":"week","every":2,"weekdays":["tue"],"appears":"09:00"}}'

Repeats on tasks

POST /tasks and PATCH /tasks/:id both accept a repeat object: on a task without one it creates the series (that task becomes the current copy), and on a task that already has one it updates the schedule. {"repeat":null} turns repeating off: the series ends and the task stays as a plain one, with series_id cleared. Responses include series alongside task.

start_date (on tasks) hides a task from Today and the Board until that day; it waits in its list's "Later" section. Every new copy of a series fires a task.created webhook.

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, plus shortcut, email, slack, discord and automation for the other doors. You may send {"source":"shortcut"} on a create; any other value is ignored (an API key can't label a task as an automation or an email).

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. Give the agent this reference as Markdown: www.gumhop.com/docs/api.md, also served at GET /docs under the base URL. One fetch, no key needed.
3. 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. Steps the parser detects become subtasks.
4. To make it repeat, say "every month" in text with {"parse":true}, or send an explicit repeat object.
5. To check progress, GET /tasks?status=todo.
6. To complete a task, PATCH /tasks/:id with {"status":"done"}, which also fires your task.completed webhook.
7. To give the user their card pull for that completion, POST /rewards/complete with {"task_id":"…"}. It's idempotent, so it's always safe to call.