Hub API Guide

The canonical reference for what the Hub API can do and how to use it — for human developers, AI knowledge systems, and software tooling alike.

Give This to Your AI

Hub is designed to work with AI assistants, and this guide is the canonical reference describing how Hub's API actually works. If you use an AI assistant — ChatGPT, Claude, Gemini, a custom GPT, or another AI that can read documentation — giving it this guide helps it work with Hub correctly instead of guessing.

Providing this documentation to an AI helps it:

• Understand what Hub can do.
• Discover which endpoints actually exist.
• Use the correct routes and parameters instead of inventing plausible-looking ones.
• Prefer Search when discovering a record it doesn't already have an ID for.
• Avoid guessing at undocumented capabilities.
• Produce more reliable, correctly-shaped API calls.

This guide does not, by itself, do any of the following:

• It does not authenticate an AI.
• It does not provide API credentials.
• It does not grant access to Hub.

Authorization is still controlled entirely by API keys, sessions, permissions, company (tenant) isolation, and module entitlements — reading this guide is harmless on its own, and teaches an AI how Hub works, not what it's allowed to do. What it's allowed to do is determined by whatever credentials and scope it's actually given.

Connecting Your AI

For an AI to work in Hub, it needs three things. Each does a different job:

The guide on its own lets an AI explain Hub and draft calls, but it can't make any. Without a connection, the key does nothing. An AI needs all three before it can act on Hub.

The key goes in the tool's auth settings, never into a chat. Put it in an environment variable, a secret store, or the Action's or connector's authentication field. Don't paste it into a conversation, prompt, or shared document. The key in your welcome email is full-scope: it can read, change, and delete your company's data. Only give it to a tool you trust.

AI-led setup: tell your AI "Read https://justwhatsneeded.com/connect-ai and help me connect you to my Hub account." That page is written for the AI. It works out which kind of AI it is and walks you through the steps below.

Code agents with a shell

Claude Code, Codex, Cursor, and similar agents that can run commands only need the guide and the key. Store the key in an environment variable named HUB_API_KEY and have the agent read it from there. Never write the key into a command.

Save the key once, without showing it. Paste one of these into your own terminal window, not into the agent. It asks for the key without showing it on screen, saves it where only you can read it, and makes it available as $HUB_API_KEY in every new terminal window.

Mac / Linux (zsh, the Mac default):

mkdir -p ~/.config/hub && read -rsp "Paste your Hub API key (it won't show): " k && echo && (umask 077; printf '%s' "$k" > ~/.config/hub/api-key) && unset k && { grep -qs HUB_API_KEY ~/.zshrc || echo 'export HUB_API_KEY="$(cat ~/.config/hub/api-key 2>/dev/null)"' >> ~/.zshrc; } && echo "Saved. Open a new terminal window."

If you use bash, replace both ~/.zshrc references with ~/.bashrc. Your agent can tell you which shell you use.

Windows PowerShell:

$k = Read-Host "Paste your Hub API key (it won't show)" -AsSecureString; [Environment]::SetEnvironmentVariable("HUB_API_KEY", [Net.NetworkCredential]::new("", $k).Password, "User"); Remove-Variable k; "Saved. Open a new terminal window."

Then open a new terminal window and start the agent from it. A .env file the agent loads, or the tool's own secret settings, also work.

Rules for the agent:

• Give the command to the person to paste into their own terminal window. Never run it yourself: the hidden prompt doesn't work properly through an agent's tool, and the key could land in the session transcript.
• Never print the key (no echo $HUB_API_KEY). To confirm the setup, call identity&action=whoami and report the company name.
• If $HUB_API_KEY is empty, ask the person to open a new terminal window or re-run the command. Don't ask them to paste the key into chat.

Test the connection, reading the key from the environment:

curl -s -H "X-API-Key: $HUB_API_KEY" \
  "https://hub.justwhatsneeded.com/api.php?resource=identity&action=whoami"

A successful call returns your company and the key's scope. That proves the connection works.

ChatGPT: Custom GPT Action

Create a Custom GPT, then add an Action:

• Schema: import from https://hub.justwhatsneeded.com/docs/openapi.yaml.
• Authentication: API Key, auth type Custom, header name X-API-Key. Paste the key into this field only.
• Add api-guide.md as the GPT's Knowledge.

The full spec is large and includes Internal operations. If ChatGPT rejects or truncates it, import a trimmed copy with just the operations you need, such as tasks, projects, comments, search, and identity. For the clicks, see OpenAI's own docs: GPT Actions.

Knowledge-only AIs

Gemini Gems, Copilot knowledge, and Claude or ChatGPT projects without an Action or connector can read this guide. They can explain Hub and draft API calls for you to run. They cannot act on Hub. They have no way to send an authenticated request, so don't give them your key.

Claude

A Claude connector for Hub customers is coming. Until then, Claude Code can connect as a code agent, and Claude chat can use this guide as knowledge only.

Choose the Format That Fits Your AI

This guide is published in three forms, generated from one canonical source so they can't drift apart. Pick whichever matches how your AI (or tooling) actually consumes documentation.

Humans

Read this HTML guide: https://justwhatsneeded.com/api-guide.html. Formatted for browsers, with the same content as the other two formats plus page styling and navigation.

AI Knowledge

A plain-Markdown version of this exact guide is published at:

https://justwhatsneeded.com/api-guide.md

This is the form to use for:

• ChatGPT Custom GPT Knowledge
• Claude Projects and Claude knowledge uploads
• Gemini Gems
• Microsoft Copilot knowledge systems
• Any other AI system that accepts Markdown or plain-text documentation uploads

Software / Tools

The detailed machine contract — every field, schema, and response shape — is the OpenAPI specification:

https://hub.justwhatsneeded.com/docs/openapi.yaml

This is the form to use for:

• API tooling
• SDK generation
• MCP servers
• API clients
• Automated integrations

Example Instructions for Your AI

Two copy-ready examples — pick whichever matches how you're giving your AI this guide.

If your AI can retrieve public web pages:

Use the Hub API Guide at https://justwhatsneeded.com/api-guide.html as the canonical reference for Hub API capabilities, routing conventions, authentication requirements, parameters, responses, and usage guidance. Consult it before assuming an endpoint exists.

If you're uploading this guide as knowledge (Custom GPT, Claude Project, Gemini Gem, etc.):

Use the Hub API Guide at https://justwhatsneeded.com/api-guide.md as your primary knowledge source for Hub API behavior. Prefer documented search capabilities when locating unknown records and direct resource endpoints once IDs are known.

Not every AI can open a URL on its own — it needs browsing, web retrieval, a connector, or a configured action to do that. If yours can't, use the second example and actually upload or paste the Markdown version into its knowledge configuration instead of just handing it the link.

Document Metadata

AI Agent Guidance

• This page is the canonical public Hub API reference. Consult it before assuming an endpoint or capability exists.
• Hub uses resource and action query-parameter routing — not REST-style paths. See Routing.
• At the start of a session, identity&action=whoami tells you which company, user and scope you are acting as, and timezone&action=now gives the user's current local time.
• When the user describes a record but doesn't know its ID or location, use search first — it is the preferred discovery mechanism.
• Once a resource ID is known (from a prior search, a prior response, or the user), use the direct resource endpoint (e.g. tasks&action=get) rather than searching again.
• Do not enumerate every project or resource merely to locate an unknown record when search can satisfy the request directly.
• Tenant isolation, authorization, API-key scope, and module entitlement rules must always be respected — there is no supported way around them, and none should be assumed.
• A zero-result search is not evidence that a record doesn't exist. It only means nothing matched inside the caller's own tenant and currently-enabled modules.
• Do not infer or assume access to a module that is disabled for the current company.
• Destructive or modifying actions (create, update, complete, delete) must never be inferred from a search request — search is read-only discovery.

Contents

• Connecting Your AI
• Authentication
• Routing
• Projects
• Tasks
• Ideas
• Comments
• Search
• Documents and Folders
• Activity Events
• Connections and Who
• Identity and Timezone
• Pagination
• Errors
• Machine-Readable Reference

Authentication

API key (recommended for developers and AI agents). Send your API key in the X-API-Key header on every request. Keys are scoped to one company — a request can only read and write that company's own data.

X-API-Key: your-api-key-here
Content-Type: application/json

Browser session (Hub's own web UI). A logged-in Hub browser session (a valid PHPSESSID cookie) is also accepted and behaves identically to a full-scope API key. This exists for Hub's own first-party pages, not third-party integrations — external developers and AI agents should use an API key instead.

API key scopes. A company's own key is always full-scope. Hub also supports narrower, purpose-specific scoped keys, but customers can't create them themselves yet; self-service scoped keys are planned. Until then, the full-scope key from your welcome email is your company's key. A scoped key can only perform the exact resource/action pairs its scope allows — anything else is rejected with 401 and the same {"error": "Invalid or inactive API key"} response as an invalid key (never 403), so a caller can never distinguish "wrong scope" from "no key at all."

Hub also uses a few internal scopes for its own background processes; they can't be issued to customers and aren't covered here.

Suspended companies. If a company is suspended, every one of its API keys (full or scoped) and every existing browser session is rejected with 401 on the very next request — the same response as an invalid key or no session, so suspension is never disclosed.

Base URL: https://hub.justwhatsneeded.com/api.php — this is the only public base URL. Every canonical_url Hub returns uses it.

Your company's full-scope API key is shown in the welcome email and on the Admin panel. Keep it private — it grants full read/write access to your company's data. Never paste a real key into a prompt, log, or shared document.

Routing

Hub's API is resource/action routed, not REST-path routed. Every request targets /api.php with two query-string parameters:

There is no path-templated equivalent like /tasks/42 — every operation is /api.php?resource=...&action=..., with GET query parameters or a JSON POST body carrying the rest of the request. GET is used for read operations, POST for anything that writes. Responses are always JSON.

resource and action must be in the URL query string, never in the JSON body — a request without resource in the query string fails with 400. With a full-scope key or session, an unknown resource returns 404 ("Unknown resource") and an unknown action on a known resource returns 400 ("Unknown action"). A scoped key gets 401 for both, because they fall outside its scope.

This applies uniformly, including to search: it is ?resource=search&action=search, not a bare ?action=search — the resource/action pair is always required, even when a resource has only one action.

Projects

All project actions require the projects module to be enabled for the company (otherwise 403) and only ever touch the caller's own company's projects.

List Projects

GET /api.php?resource=projects&action=list — scope: full, ai_agent

Purpose: List the caller's company's projects, most recently updated first.
When to use: Browsing or picking a project when you don't yet know its ID.
When not to use: Don't page through this to find one task or record — use search instead.
Optional parameters: show_all (boolean) — include hidden (display=0) projects. Default false. archived (boolean) — return archived projects instead of active ones. Default false (archived projects are excluded).

Example response

[
  {
    "id": 11,
    "company_id": 1,
    "name": "JWN - All",
    "description": "Main project board",
    "status": "active",
    "display": 1,
    "client": "JWN",
    "archived_at": null,
    "created_at": "2025-01-10 09:00:00",
    "updated_at": "2026-06-01 14:22:00",
    "url": "/project.php?id=11",
    "canonical_url": "https://hub.justwhatsneeded.com/project.php?id=11"
  }
]

Get Project

GET /api.php?resource=projects&action=get&id=11 — scope: full, ai_agent

Purpose: Read one project row (same shape as one list item). 404 if it doesn't exist or belongs to another company.

Get Project with Context

GET /api.php?resource=projects&action=get-with-context&id=11 — scope: full

Purpose: The project row plus all of its tasks (tasks, not paginated) and up to 10 historical rows from the retired interactions log (interactions, usually empty).

Create Project

POST /api.php?resource=projects&action=create — scope: full, ai_agent

Purpose: Create a new project — or return the existing one if the name is already taken.
Duplicate handling: If the company already has a non-archived project whose name matches case-insensitively (after trimming), that project is returned with "duplicate": true and status 200, and nothing new is created. A genuinely new project returns 201 with "duplicate": false. Safe to retry.
Tenant isolation: Created under the caller's own company automatically — there is no company_id field to set.

Example request

{ "name": "Q3 Marketing Campaign", "description": "All tasks for the Q3 push", "status": "active", "client": "JWN" }

Example response (201)

{ "id": 14, "company_id": 1, "name": "Q3 Marketing Campaign", "status": "active", "client": "JWN", "archived_at": null, "duplicate": false, "url": "/project.php?id=14", "canonical_url": "https://hub.justwhatsneeded.com/project.php?id=14" }

Update, Hide, Archive, Unarchive, Delete Project

All POST, scope: full only — not available to ai_agent keys.

Tasks

All task actions require the tasks module (otherwise 403) and only ever reach tasks whose project belongs to the caller's company.

List Tasks

GET /api.php?resource=tasks&action=list&project_id=11 — scope: full, ai_agent

Purpose: List tasks, optionally filtered to one project or one category.
When to use: You already know the project (or category) and want every task in it.
When not to use: Looking for one specific task by title or keyword across many projects — use search instead of listing and scanning client-side.
Optional parameters: project_id (integer) — restrict to one project. category (string) — restrict to a category; when set, done tasks are excluded unless include_done is also set. include_done (boolean) — only relevant alongside category. Without category, done tasks are always included.
Validation: No pagination on this endpoint — it returns every matching row. For large result sets or keyword filtering, prefer search, which supports limit/offset.

Example response

[
  {
    "id": 42,
    "project_id": 11,
    "title": "Review contract",
    "description": null,
    "tags": null,
    "status": "todo",
    "priority": "high",
    "category": null,
    "due_date": "2026-06-20",
    "delivery_mode": "commit_push",
    "version": 1,
    "created_at": "2026-06-10 08:00:00",
    "updated_at": "2026-06-10 08:00:00",
    "url": "/project.php?id=11&task=42",
    "canonical_url": "https://hub.justwhatsneeded.com/project.php?id=11&task=42"
  }
]

Get Task

GET /api.php?resource=tasks&action=get&id=42 — scope: full, ai_agent

Purpose: Read one task, including its full comment history (comments, oldest first) and attached images (images). Use this once you know the ID. Includes the current version for safe updates.

Create Task

POST /api.php?resource=tasks&action=create — scope: full, ai_agent, quick_capture

Purpose: Create a new task inside a project.
Common mistakes / agent guidance: Always pass project_id. If it is omitted, the server substitutes one fixed internal project that exists in only one company's account; for every other company an omitted project_id fails with 404 "Project not found". Never assume a default project exists.
Tenant isolation: The target project must belong to the caller's company, or the request fails with 404.
Not idempotent: A retried call creates a second task.

Example request

{ "project_id": 11, "title": "Review contract", "priority": "high", "status": "todo", "due_date": "2026-06-20" }

Example response (201)

{ "id": 42, "message": "Task created", "delivery_mode": "commit_push", "url": "/project.php?id=11&task=42", "canonical_url": "https://hub.justwhatsneeded.com/project.php?id=11&task=42" }

Update Task

POST /api.php?resource=tasks&action=update — scope: full, ai_agent

Purpose: Update one or more fields on an existing task. Only include fields you want to change. Sending no changeable field → 400 "Nothing to update".

Example request

{ "id": 42, "status": "in-progress", "priority": "urgent", "version": 1 }

Example response — the full, updated task row:

{ "id": 42, "project_id": 11, "title": "Review contract", "status": "in-progress", "priority": "urgent", "delivery_mode": "commit_push", "version": 2, "url": "/project.php?id=11&task=42" }

Complete Task

POST /api.php?resource=tasks&action=complete — scope: full, ai_agent

Purpose: Convenience wrapper that sets status=done. Completing an already-complete task just succeeds again.
Required parameters: id (integer)
Optional parameters: version (integer) — same optimistic-concurrency check as update: a stale value fails with 409 and returns current_task.

Example request

{ "id": 42, "version": 2 }

Example response — the full, updated task row:

{ "id": 42, "status": "done", "version": 3, "url": "/project.php?id=11&task=42" }

Reopen Task

POST /api.php?resource=tasks&action=reopen — scope: full, ai_agent

Purpose: Sets status=todo (Hub doesn't record the earlier status, so nothing else is restored). Same id and optional version as Complete Task, same 409 behavior; returns the full task row.

Task History, Images, Delete

Scope: full only — not available to ai_agent keys.

Ideas

A lighter-weight backlog for things worth capturing before they're ready to become a task. Requires the ideas module (otherwise 403). There is no delete action.

Create Idea

POST /api.php?resource=ideas&action=create — scope: full, ai_agent

Purpose: Capture an idea for later triage — not yet committed engineering work.
Required parameters: title (string)
Optional parameters: description, status (idea · reviewing · ready; default idea), created_by

Example response

{ "id": 210, "title": "...", "status": "idea", "url": "/ideas.php" }

Promote Idea

POST /api.php?resource=ideas&action=promote — scope: full, ai_agent

Purpose: Turns an idea into a real task under a given project. The idea itself is kept (not deleted), status set to ready, promoted_task_id linked to the new task.
Required parameters: id (the idea), project_id (where the new task should live — must belong to your company, otherwise 404)
Common mistakes / agent guidance: An idea can only be promoted once — a second attempt fails with 400.

Example response (201)

{ "idea": { "...": "updated idea, status: ready" }, "task": { "...": "newly created task" } }

Comments

Task comments. Require the tasks module (otherwise 403).

List Comments

GET /api.php?resource=comments&action=list&task_id=42 — scope: full, ai_agent

Purpose: The task's complete comment history, oldest first (ties broken by comment ID). Not paginated.
Required parameters: task_id (integer). 404 if the task is unknown or another company's.

Example response

[
  { "id": 7, "task_id": 42, "author": "Bill", "body": "Ready for review", "created_at": "2026-06-11 10:30:00" }
]

Create Comment

POST /api.php?resource=comments&action=create — scope: full, ai_agent

Purpose: Adds a comment to a task. Not idempotent — a retried call adds a second comment.

Example request

{ "task_id": 42, "author": "Bill", "body": "Ready for review" }

Example response (201) — the new comment:

{ "id": 8, "task_id": 42, "author": "Bill", "body": "Ready for review", "created_at": "2026-06-11 10:31:00" }

Delete Comment

POST /api.php?resource=comments&action=delete — scope: full only

Purpose: Permanently deletes one comment. Body: { "id": 8 }. Response: {"message": "Comment deleted"}. 404 if unknown or another company's.

Search

The general-purpose, canonical way to find a record when you don't already know its ID. This is the preferred discovery mechanism for AI agents — see AI Agent Guidance.

GET /api.php?resource=search&action=search&q=password — scope: full, ai_agent

Purpose: Search across Hub resources by keyword. Today this covers tasks only — the response shape and the type parameter are designed so more resource types (documents, ideas, and others) can be added later without changing this contract, but only task is implemented right now.

When to use: The user describes a record (by title, keyword, or ID) but you don't already know exactly where it lives.
When not to use: Once you have a concrete ID, use the resource's own get action instead of searching again. Don't use search as a substitute for a targeted list when you already know the exact project/filter and have no free-text to match.

Route: GET /api.php?resource=search&action=search — deliberately not the bare ?action=search form; Hub's routing convention (see Routing) requires an explicit resource on every request, even one with a single action.

Authentication & scope: API key or browser session, same as every other endpoint. Included in the ai_agent scoped-key allowlist — this is the intended search mechanism for AI-agent integrations. Not available to quick_capture-scoped keys.

Required parameters:

Optional parameters:

Query forms: q is interpreted as a whole (after trimming):

A literal % or _ in q is always treated as a literal character, never a SQL wildcard.

Ranking / order: Results are ordered by, in priority order: (1) exact task-ID match, (2) exact title match, (3) title contains the query, (4) description contains the query, then (5) most-recently-updated first as the tiebreaker within any of the above.

Validation rules and limits: A filter that matches nothing — an unrecognized status/priority value, or a project_id with no matching tasks — returns an empty results array, not an error. A project_id belonging to a different company also returns an empty array, identically to any other non-matching filter — this is deliberate and matches Hub's tenant-isolation convention of never revealing, even indirectly, whether a record exists outside the caller's own company.

Module entitlement: Each result type checks the entitlement for its own module independently. Today that means: if the tasks module is disabled for the company, the task type simply contributes zero results — the whole search request still succeeds. This is intentional: a future search spanning several resource types must not have every type blocked just because one of that company's modules happens to be off.

Tenant isolation: Only tasks belonging to the caller's own company are ever returned, enforced the same way as every other tasks endpoint.

Response shape: A JSON object with query, results (an array), and pagination. Each result includes:

pagination is { "limit": ..., "offset": ..., "has_more": ... } — see Pagination.

Status / error responses: 200 success (including a legitimate zero-result search) · 400 missing/blank q, unsupported type, or invalid limit/offset · 401 missing/invalid authentication.

Common mistakes / agent guidance: Don't request type=document, type=idea, or type=all — only task exists today, and anything else is a 400, not an empty result. Don't treat a zero-result search as proof a record doesn't exist anywhere — it only means nothing matched in this tenant's currently-searchable data.

Search Examples

1. Normal keyword search

GET /api.php?resource=search&action=search&q=password
X-API-Key: your-api-key-here

{
  "query": "password",
  "results": [
    {
      "type": "task",
      "id": 1104,
      "project_id": 11,
      "project_name": "Platform Polish",
      "title": "Add Admin Password Reset",
      "description_excerpt": "Platform administrators need a safe way to reset...",
      "status": "todo",
      "priority": "high",
      "matched_fields": ["title", "description"],
      "url": "/project.php?id=11&task=1104"
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "has_more": false }
}

2. Search restricted to a project

GET /api.php?resource=search&action=search&q=reset&project_id=11
X-API-Key: your-api-key-here

3. Task-ID search (bare, #, task: or [[task:…]] form)

GET /api.php?resource=search&action=search&q=%231104
X-API-Key: your-api-key-here

{ "query": "#1104", "results": [ { "type": "task", "id": 1104, "matched_fields": ["id"] } ], "pagination": { "limit": 25, "offset": 0, "has_more": false } }

4. Exact-phrase search

GET /api.php?resource=search&action=search&q=%22password%20reset%22
X-API-Key: your-api-key-here

5. Pagination

GET /api.php?resource=search&action=search&q=onboarding&limit=10&offset=10
X-API-Key: your-api-key-here

6. Zero-result response

GET /api.php?resource=search&action=search&q=zzz_no_such_term_zzz
X-API-Key: your-api-key-here

{ "query": "zzz_no_such_term_zzz", "results": [], "pagination": { "limit": 25, "offset": 0, "has_more": false } }

7. Invalid resource type → 400

GET /api.php?resource=search&action=search&q=x&type=document
X-API-Key: your-api-key-here

{ "error": "Unsupported type(s): document. Supported types: task" }

8. Unauthenticated request → 401

GET /api.php?resource=search&action=search&q=password

{ "error": "Unauthenticated" }

Documents and Folders

Markdown documents, organized in folders and optionally attached to a project. Requires the documents module (otherwise 403). Every action only touches the caller's own company.

Create Document

POST /api.php?resource=documents&action=create: scope full, ai_agent

Purpose: Create a Markdown document. Not idempotent: there is no dedupe key, so a retried call creates a second document. If a retry is possible, search before creating again.

Example response (201): the new document, with its first revision already recorded:

{ "id": 12, "title": "Onboarding checklist", "document_type": "document", "folder_id": 4, "project_id": null, "version": 1, "markdown_content": "...", "url": "..." }

Folders

Folders live under the same documents module.

Document Attachments

Files attached to a document. Same documents module.

Activity Events

A durable log of meaningful work: what was started, decided, finished or found, linked to a project, task or document. This is the main way an AI agent records what it did. Requires the tasks module (otherwise 403).

Record an Activity Event

POST /api.php?resource=activity_events&action=create: scope full, ai_agent

Purpose: Record one meaningful piece of work. Idempotent when you send client_dedupe_key: a retry with the same key returns the original event with "duplicate": true instead of creating a second one. Without a key, a retry creates a duplicate.

Example request

{ "event_type": "task_completed", "summary": "Fixed the login redirect loop", "task_id": 42, "performed_by_type": "agent", "performed_by": "Claude Code", "client_dedupe_key": "task-42-done" }

Example response (201): the event, plus duplicate:

{ "id": 901, "event_type": "task_completed", "summary": "Fixed the login redirect loop", "task_id": 42, "occurred_at": "2026-10-27 21:05:12", "duplicate": false }

Connections and Who

The relationships resource tracks Connections: ongoing relationships with a person or organization (a sale, a vendor, a job search, a customer), each with a timeline of communications, a "next move" that says who owes what by when, and participants linked to people in Who, Hub's contacts directory. It is not module-gated.

For an ai_agent key, reads are open and writes are narrow. There are no deletes. Confirming or rejecting a person's identity, and adding or closing a next move on its own, are human-only. Writes made with an ai_agent key are always recorded as agent-originated, whatever the request body says.

Values used across these actions:

Create a Connection

POST /api.php?resource=relationships&action=engagement.create: scope full, ai_agent

Purpose: Start tracking a relationship. In the same call you can add the first person, the first next move and links. No communication is recorded. Use event.log for that.
Required parameters: title, category
Optional parameters: state (default action_needed), headline, project_id, person (one first person) or participants (several), next_obligation ({ "owner": "us", "next_action": "Send proposal", "due_date": "2026-11-03" }; due_date is optional), links, next_review_date
Common mistakes / agent guidance: This action does not check for an existing Connection with the same title unless you send guarded_create: true, so call engagement.find_duplicate first. With guarded_create: true, an open Connection with the same title returns 409 (send confirm_duplicate: true to create it anyway). A state of action_needed, waiting_on_them or scheduled with no next_obligation returns 422 (send allow_no_next_action: true to save it anyway).

Log a Communication

POST /api.php?resource=relationships&action=event.log: scope full, ai_agent

Purpose: Record one communication on a Connection and, in the same call, optionally move its state, resolve an open next move and set the next one. History is append-only: a logged communication can't be edited or deleted.

Identity and Timezone

Two small read-only resources an agent can call at the start of a session to learn who it is acting as and what time it is for the user. Neither is module-gated.

now and format use the caller's effective timezone unless you pass timezone (an IANA name; offsets and abbreviations such as CST are rejected with 400). Pass hour12=false for a 24-hour clock. Hub stores and returns timestamps in UTC; use format rather than converting them yourself.

Setting a timezone isn't available to ai_agent keys. timezone&action=update_user sets your own preference and needs a signed-in user. update_company_default sets the company default and needs a company admin or a full-scope key.

Pagination

Hub uses limit/offset pagination. Only search returns a pagination object. The list actions for projects, tasks, ideas, comments, document attachments and Connections return every matching row in one response, and document search returns at most 50 documents.

Search responses include a pagination object:

To page through results: keep the same filters and limit, and increase offset by limit each time until has_more is false.

A few endpoints accept a size limit but return no pagination object or has_more. For those, getting fewer results than limit means you have reached the end. See the OpenAPI specification for details:

Errors

The resources in this guide report validation failures as 400. The one exception is engagement.create with guarded_create: true, which returns 422 when a Connection that needs a next move has none.

Error responses always return a JSON object with an error field (some add context, such as module or current_task):

{ "error": "Missing required field: title" }

Machine-Readable Reference

The full, detailed machine contract — every field, every schema, every response shape — lives in one place: the OpenAPI specification. This guide is the operational usage guide; the OpenAPI document is the authoritative detailed schema.

The OpenAPI specification documents every operation api.php routes, and a test in the Hub repository fails if one goes missing. Beyond the resources in this guide, it covers Briefings, Songs, document revisions, shares and sets, task images and dependencies, company settings, email drafts (Outbox), work sessions, schedules and file transfer. Operations tagged Internal are Hub's own AI-orchestration, operations, billing and test-harness surface. They are specified for completeness, are not a supported integration point, and may change without notice. Each operation has its own "Scopes" line saying which keys can call it. If you need a resource's exact field types, enums or nullability and this guide doesn't spell them out, the OpenAPI document is authoritative.

Keeping This Guide Current

This guide has one canonical source — docs/api-guide-source.md in the jwn-hub repository — generated into api-guide.html and api-guide.md by scripts/generate-api-guide.php, and cross-checked against docs/openapi.yaml by tests/validate-api-guide.php. Nobody edits html/api-guide.html or html/api-guide.md directly; both are build output and get overwritten the next time the generator runs.

Whenever a public Hub API capability, route, parameter, response contract, authentication rule, scope, module entitlement, or error behavior changes: edit docs/api-guide-source.md, run php scripts/generate-api-guide.php, and update docs/openapi.yaml — all before that work is considered complete. This is a standing Hub engineering requirement (Hub Engineering Standard, Section 8), not a one-off effort tied to any single change.

© 2026 Just What's Needed · Back to Hub overview