# HoneyBook — full agent reference

> Companion to https://www.honeybook.com/llms.txt. Read that first for what HoneyBook is and when
> to use it. This file is the connection detail: auth, the two interfaces, and the complete list of
> documented REST operations and OAuth scopes, so an agent can plan a call without fetching and
> parsing a 150 KB OpenAPI document.
>
> Generated from HoneyBook API v3 (OpenAPI 3.0.0): 26 paths, 37 operations, 47 schemas —
> snapshot verified 2026-09-09, re-verified weekly against the live spec. If this file is
> visibly older than that, treat the counts as approximate and defer to the OpenAPI spec.

## Two ways in

HoneyBook exposes an MCP server and a REST API. They share one OAuth identity and one account.

1. **MCP** — `https://mcp.api.honeybook.com/mcp`, transport `streamable-http`, POST only.
   A GET returns 405; that is correct behaviour, not an outage. Server card:
   `https://mcp.api.honeybook.com/mcp/server-card` (aliases: `/.well-known/mcp.json`,
   `/.well-known/mcp/server-card.json`). The card describes the server as: "Run your HoneyBook
   business — contacts, clients, projects, invoices and account settings."
   Prefer MCP for invoicing and account work — those have no REST endpoints (see below).
2. **REST** — base URL `https://api.honeybook.com/api/v3`. Reference:
   `https://developers.honeybook.com`.

## Authentication

OAuth 2.0 authorization code with PKCE (S256). There is no API key and no unauthenticated access.

- Protected-resource metadata (RFC 9728): `https://mcp.api.honeybook.com/.well-known/oauth-protected-resource`
- Authorization-server metadata: `https://mcp.api.honeybook.com/.well-known/oauth-authorization-server`
- Issuer: `https://oauth.honeybook.com`
- Authorize: `https://oauth.honeybook.com/oauth2/auth` · Token/refresh: `https://oauth.honeybook.com/oauth2/token`
- Send the token as `Authorization: Bearer <access_token>`.

A human account owner must approve the consent screen. Request least privilege; do not ask for
write scopes for a read-only task.

### Scopes

The authoritative, always-current scope list is `scopes_supported` in the authorization-server
metadata above (`https://mcp.api.honeybook.com/.well-known/oauth-authorization-server`) — fetch
it directly rather than trust a static copy of a security-relevant list.

Note: a scope existing does not imply a REST endpoint exists. Most scopes have no documented REST
path yet — they are reachable, if at all, over MCP.

## API conventions

- **Ids are opaque** 24-character hex strings. Do not parse them or assume ordering.
- **Timestamps are ISO 8601 UTC** (`2026-08-11T14:30:52Z`); date-only fields are `YYYY-MM-DD`.
- **Money is an object**, an amount plus its currency. Never assume a currency.
- **Unknown query parameters are ignored, not rejected.** A misspelled filter silently does not
  filter — if a list returns more rows than expected, check the parameter spelling first.
- **Absent is not the same as empty.** A field not requested is distinguishable from one that is
  genuinely empty (see the Relation Includes guide).
- **A 404 on a real endpoint can mean "unauthenticated", not "does not exist."** With no
  `Authorization` header at all, existing v3 paths answer `404` with a JSON body of
  `{"error_type":"HBUnauthorizedError"}`. Send any token and the documented codes apply: `401`
  (`HBInvalidJWTError`) for a missing/malformed/expired token, `403` when the token lacks a
  required scope. Do not conclude an endpoint is missing from an unauthenticated probe.
- Versioning is in the path. `v3` endpoints are not removed or changed in place.
- Cross-cutting guides in the spec: Authentication, Errors, Pagination, Filtering & Sorting,
  Relation Includes, Async Operations.

## Documented REST operations (37)

### Contacts (6) — write-side only
    POST   /contacts
    PATCH  /contacts/{id}
    DELETE /contacts/{id}                                 Delete a contact
    PUT    /contacts/{id}/interaction
    PUT    /contacts/{id}/tags/{tag_id}
    DELETE /contacts/{id}/tags/{tag_id}

There is no documented `GET /contacts` or `GET /contacts/{id}` in this version, despite a
`contacts.read` scope. Do not assume a contact read endpoint exists.

### Pipeline (2) — read only
    GET    /pipeline                                      List the caller company's pipeline (workspaces by stage)
    GET    /pipeline/counts                               Pipeline stage/category tallies for the caller's company

### Workspaces (14)
    GET    /workspaces                                    List the caller company's workspaces
    GET    /workspaces/counts                             Workspace counts (all / active / inactive)
    GET    /workspaces/any                                Whether the caller's company has any workspace
    GET    /workspaces/{id}                               Get a workspace by id
    PATCH  /workspaces/{id}                               Update a workspace (partial; renames the tab)
    DELETE /workspaces/{id}                               Delete a workspace
    GET    /workspaces/{id}/deletable                     Whether a workspace can be deleted by the caller
    GET    /workspaces/{id}/members                       List a workspace's members
    PUT    /workspaces/{id}/members/{user_id}             Add a member to a workspace (idempotent)
    DELETE /workspaces/{id}/members/{user_id}             Remove a member from a workspace
    PUT    /workspaces/{id}/tags/{tag_id}                 Tag a workspace (idempotent)
    DELETE /workspaces/{id}/tags/{tag_id}                 Untag a workspace (idempotent)
    POST   /workspaces/{id}/archive                       Archive a workspace for the caller and their team
    POST   /workspaces/{id}/unarchive                     Unarchive a workspace for the caller

### Projects (15)
    GET    /projects
    POST   /projects                                      Create a project
    GET    /projects/{id}
    PATCH  /projects/{id}
    GET    /projects/{id}/conflicts
    POST   /projects/{id}/dates                           Add a project date
    PATCH  /projects/{id}/dates/{date_id}
    DELETE /projects/{id}/dates/{date_id}
    POST   /projects/{id}/workspaces
    PUT    /projects/{id}/spaces/{space_id}
    DELETE /projects/{id}/spaces/{space_id}
    GET    /projects/payroll_employee_counts
    GET    /projects/{id}/payroll_employees
    PUT    /projects/{id}/payroll_employees/{employee_id}
    DELETE /projects/{id}/payroll_employees/{employee_id}

## Not in the REST API

The documented v3 surface covers contacts, pipeline, workspaces and projects only. There are **no**
REST endpoints for invoices, payments, contracts, proposals, smart files, tasks, notes,
conversations/communications, lead forms, reports, files or the calendar. If a task needs those,
use MCP or the product UI — do not construct a URL and hope. HoneyBook is also not a general
ledger (it integrates with QuickBooks Online), and does not do e-commerce, subscription billing,
payroll or inventory.