API Reference

A small REST API to read and write your Gumhop tasks — built for scripts, integrations, and AI agents. Base URL: https://www.gumhop.com/api/v1

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 key), 400 (bad input), 404 (not found). Be polite — keep requests under roughly 120/minute per key.

Endpoints

GET/me

Returns the account the key belongs to.

{ "id": "uuid", "email": "you@example.com" }

GET/lists

All folders and lists for the account.

{ "lists": [{ "id": "uuid", "name": "Work", "is_inbox": false }] }

POST/lists

Create a list.

curl -X POST https://www.gumhop.com/api/v1/lists \
  -H "Authorization: Bearer gh_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Work"}'

GET/tasks?list_id=&status=todo

List tasks. Optional query params: list_id, status (todo/done).

GET/tasks/:id

Fetch a single task by id.

POST/tasks

Create a task two ways. Mode A — natural language with AI parsing:

curl -X POST https://www.gumhop.com/api/v1/tasks \
  -H "Authorization: Bearer gh_live_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"email the deck to sara@acme.com friday","parse":true}'

Mode B — explicit structured fields:

-d '{"title":"Renew passport","due_date":"2026-07-01","priority":3}'

PATCH/tasks/:id

Update fields. Setting {"status":"done"} completes a task; {"status":"todo"} reopens it and clears completed_at.

curl -X PATCH https://www.gumhop.com/api/v1/tasks/<id> \
  -H "Authorization: Bearer gh_live_…" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'

DELETE/tasks/:id

Permanently delete a task.

Webhooks

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

{
  "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": "app", "ai_status": "done",
    "list_id": "uuid", "chips": [], "completed_at": "...", "created_at": "..."
  }
}

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

Create an API key and store it as a secret in your agent runtime.
To capture a task, POST /tasks with {"text":"…","parse":true} and let Gumhop extract dates, contacts, and priority.
To check progress, GET /tasks?status=todo.
To complete a task, PATCH /tasks/:id with {"status":"done"} — which also fires your task.completed webhook.