Goalpen API — Developer Docs

Quick Start

1

Get an API key

Log in to Goalpen → Settings → API Keys → click New Key. Choose read for read-only access or read + write to allow the AI to create and update items.

2

Point your AI at the discovery URL

Any MCP-compatible client (Claude, Cursor, ChatGPT plugin, custom agent) can read the tool manifest at:
GET https://api.goalpen.com/mcp/tools

3

Authenticate with your key

Include the key in every request as a Bearer token:
Authorization: Bearer gp_live_<your-key>

4

Execute a tool

POST to /mcp/execute with { "tool": "list_tasks", "args": {} } — see full reference below.

Base URL

Test / development

https://api.goalpen.com/mcp

Production (coming soon)

https://api.goalpen.com/mcp

Endpoints

GET /tools no auth

Returns the full MCP tool manifest — list of all tools with their input schemas. Use this URL in your AI client's MCP configuration.

POST /execute API key required

Executes a single tool. Body: { "tool": "<name>", "args": { ... } }

POST /keys/generate Firebase ID token

Generate a new API key. Called internally by the Goalpen Settings UI. Body: { "name": "My Agent", "scopes": ["read","write"] }

GET /keys/list Firebase ID token

List all API keys for the authenticated user.

POST /keys/revoke Firebase ID token

Revoke an API key. Body: { "keyId": "..." }

Example — Execute a tool

Request

// List all overdue tasks
POST https://api.goalpen.com/mcp/execute
Authorization: Bearer gp_live_abc123...
Content-Type: application/json

{
  "tool": "list_tasks",
  "args": {
    "status": "In Progress",
    "dueBefore": "2026-04-03",
    "limit": 20
  }
}

Response

{
  "success": true,
  "tool": "list_tasks",
  "result": {
    "tasks": [
      {
        "id": "abc123",
        "taskName": "Review Q2 report",
        "status": "In Progress",
        "dueOn": "2026-04-01",
        "assignee": ["userId1"]
      }
    ],
    "count": 1
  }
}

Available Tools (15)

All tools are scoped to the authenticated user's organisation. Read tools require the read scope; write tools require write.

list_tasks

read

Filter tasks/goals by status, assignee, due date, or module. Returns up to 200 results.

search_items

read

Full-text fuzzy search across tasks, goals, notes, and channels.

get_task

read

Get full details for a single task or goal by Firestore ID or name.

list_channels

read

List channels, optionally filtered by linked task or goal.

list_notes

read

List notes, optionally filtered by linked task or goal.

get_user

read

Resolve a display name to a user ID — useful before assigning tasks.

create_task

write

Create a task or goal with optional parent, assignee, due date, and description.

update_task

write

Update fields on an existing task — name, status, assignee, due date, importance.

link_task

write

Re-parent a task to a new goal. Recursively updates all descendant levels.

bulk_update_status

write

Mark a goal and every nested task as a new status in one call.

send_message

write

Post a message to a channel (matched by name or linked task/goal).

create_channel

write

Create a channel, optionally linked to a task or goal.

create_note

write

Create a plain-text note, optionally linked to a task or goal.

update_note

write

Update a note — content, title, pin state, or mark as done.

create_blog

write

Create a blog post (draft or published), optionally linked to a task or goal.

Webhooks LIVE

Goalpen pushes a signed JSON payload to your URL whenever a task event occurs — regardless of whether the change came from the UI, SuperAgent, or an MCP agent call. Configure webhooks in Settings → AI Connect → Webhooks.

Payload signing: Every POST includes an X-Goalpen-Signature header (sha256=HMAC(secret, body)). Verify it against your webhook's signing secret to confirm the payload is genuine.

Event	Fired when
`task.created`	A new task or goal is created
`task.updated`	Any field on a task is changed
`task.status_changed`	Status changes to any value
`task.completed`	Status changes to Completed

Authentication

API keys are generated in Goalpen → Settings → AI Connect → API Keys. Keys are prefixed gp_live_ and stored as SHA-256 hashes — the plaintext is shown only once at creation.

Pass the key in every request:

Authorization: Bearer gp_live_<your-key>

Each key is scoped to a single user and organisation. Read keys can only call read tools; write keys can call all tools.