Hypha Desk API
Read and write your organisation's work items, clients, Important Context, todos and Inbox from scripts, automations or other AI tools. The API acts as you and sees exactly what you can see on the website. Documents are the Word (.docx) and PDF files attached to a work item's or client's Important Context timeline.
1. Get a key. In Hypha Desk open Settings → API keys and create one. It is shown once; keep it secret. Each key belongs to one organisation.
2. Call the API. Base address
2. Call the API. Base address
https://hyphadesk.com/api/v1, JSON in and out, key in the Authorization header. Text is Markdown: lists, **bold**, *italic*, links, `code`, quotes, headings.
curl https://hyphadesk.com/api/v1/me \
-H "Authorization: Bearer hd_your_key"
curl -X POST https://hyphadesk.com/api/v1/work-items/website-refresh/context \
-H "Authorization: Bearer hd_your_key" -H "Content-Type: application/json" \
-d '{"text":"The client approved the site map"}'
curl -X PATCH https://hyphadesk.com/api/v1/todos/TODO_ID \
-H "Authorization: Bearer hd_your_key" -H "Content-Type: application/json" \
-d '{"done":true}'
Work items and clients can be named by id or by name. A work item's type is one of your organisation's work types (/work-types); give its id or name. Work items were called projects, and before that initiatives: /projects and /initiatives still work and return their old field names (project or initiative, and type as the type's name); /work-items returns work_item, work_items, type (the id) and type_name. Errors come back as {"error": "…"} with status 400, 401 or 404. Deleting is not possible through the API.| GET | /me | Who you are, the organisation, work items by type and your open todos |
| GET | /search | Search everything you can see |
| GET | /initiatives | List projects (?type=&area=&q=&include_archived=true) (old address; use /api/v1/work-items) |
| POST | /initiatives | Create a project {title, type? (a work type's id or name), client?, note?, status?} (old address; use /api/v1/work-items) |
| GET | /initiatives/{initiative} | One project with its Important Context, todos and ideas (old address; use /api/v1/work-items/{work_item}) |
| PATCH | /initiatives/{initiative} | Update {title?, type? (id or name; "none" to clear), client?, status? (New, Progressing or Done), key_people? (list of person ids or names, first = primary)} (old address; use /api/v1/work-items/{work_item}) |
| POST | /initiatives/{initiative}/context | Add to Important Context {text?, url?, happened_on? (YYYY-MM-DD, today or earlier), files?: [{name, type?, base64}] (up to 10, 20 MB each)} (old address; use /api/v1/work-items/{work_item}/context) |
| PATCH | /initiatives/{initiative}/context/{entry_id} | Replace an entry's text {text} (old address; use /api/v1/work-items/{work_item}/context/{entry_id}) |
| DELETE | /initiatives/{initiative}/context/{entry_id} | Undo an entry you just added (own entries, within 10 minutes) (old address; use /api/v1/work-items/{work_item}/context/{entry_id}) |
| POST | /initiatives/{initiative}/context/{entry_id}/comments | Comment on an entry {text, mentions?: [user id]} (write @{user id} in the text) (old address; use /api/v1/work-items/{work_item}/context/{entry_id}/comments) |
| POST | /initiatives/{initiative}/todos | Add a todo here {title, due?, due_time?, assignee?, note?} (old address; use /api/v1/work-items/{work_item}/todos) |
| POST | /initiatives/{initiative}/ideas | Add an improvement idea {text} (old address; use /api/v1/work-items/{work_item}/ideas) |
| GET | /initiatives/{initiative}/documents | List the Word and PDF documents (old address; use /api/v1/work-items/{work_item}/documents) |
| GET | /initiatives/{initiative}/documents/{document} | Read a Word document's text and comments (old address; use /api/v1/work-items/{work_item}/documents/{document}) |
| GET | /clients | List clients (?q=) |
| POST | /clients | Create a client {name, type?, contactName?, contact?, website?} |
| GET | /clients/{client} | One client with Important Context, work items and todos |
| PATCH | /clients/{client} | Update {name?, type?, website?, contacts?: [{name, email?, phone?, role?}], next_follow_up?: YYYY-MM-DD or ""} |
| POST | /clients/{client}/context | Add to a client's Important Context {text?, url?, happened_on? (YYYY-MM-DD, today or earlier), files?: [{name, type?, base64}]} |
| PATCH | /clients/{client}/context/{entry_id} | Replace an entry's text {text} |
| DELETE | /clients/{client}/context/{entry_id} | Undo an entry you just added (own entries, within 10 minutes) |
| POST | /clients/{client}/context/{entry_id}/comments | Comment on an entry {text, mentions?: [user id]} (write @{user id} in the text) |
| GET | /clients/{client}/documents | List the client's documents |
| GET | /clients/{client}/documents/{document} | Read a client's Word document |
| POST | /clients/{client}/todos | Add a todo for a client {title, due?, assignee?, note?} |
| GET | /todos | Your todos (?scope=mine|team&include_done=true; ?starred=true for the open todos you starred). The list is a plain array; the day it used is in the X-Today and X-Time-Zone response headers (your own time zone, or the X-Timezone header you send) |
| POST | /todos | Add a todo {title, due?, due_time?, note?, project?, client?, assignee?} |
| PATCH | /todos/{id} | Update a todo {done?, title?, due?, due_time?, note?, assignee?, starred?} |
| POST | /todos/{id}/comments | Comment on a todo {text, mentions?: [user id]} |
| GET | /time/entries | Your own time entries with day totals (?from=YYYY-MM-DD&to=YYYY-MM-DD; default the last 7 days, 92 days at most) |
| POST | /time/entries | Log time {minutes (1 to 1440), date? (YYYY-MM-DD, default today), todo? | work_item? | client?, note? (required unless on a todo)} |
| PATCH | /time/entries/{id} | Change a time entry {minutes?, date?, note?} |
| GET | /time/timer | Your running timer, or null |
| POST | /time/timer/start | Start a timer {todo? | work_item? | client?, replace?, note?} |
| POST | /time/timer/stop | Stop your timer and log it {note? (required on a work item or company)} |
| GET | /time/todos/{todo} | Time logged on a todo |
| GET | /time/work-items/{work_item} | Time logged on a work item |
| GET | /time/clients/{client} | Time logged on a client or company |
| GET | /forum/categories | The Forum boards you can see |
| GET | /forum/categories/{category}/threads | Threads on a board (?cursor=) |
| GET | /forum/threads/{thread} | One thread with a page of replies (?cursor=) |
| POST | /forum/threads | Start a thread {category, title, body (Markdown), work?, company?} |
| POST | /forum/threads/{thread}/replies | Reply {text (Markdown), quote_of?} |
| GET | /inbox | Your Inbox, newest first, 50 a page (?cursor=); text is a short preview |
| GET | /inbox/{id} | One Inbox item with its whole text |
| GET | /ideas-page | Your own Ideas items, newest first, 50 a page (?cursor=) |
| POST | /ideas-page/{item}/highlights | Highlight words in an Ideas item {quote, note?, at?} |
| POST | /inbox/{id}/highlights | Highlight words in an Inbox note {quote, note?, at?} |
| POST | /highlights/{id} | Change the note on your highlight {note} |
| POST | /ideas-page | Add to the Ideas page {title?, body (Markdown, up to 200 KB), url?, shared?} (private unless shared) |
| GET | /ideas-page/{item} | One Ideas item: full text, highlights, comments |
| POST | /ideas-page/{item}/comments | Comment on an Ideas item {text, mentions?: [user id]} |
| POST | /inbox | Save to your Inbox {text, url?} |
| GET | /claims | Your expense claims (?status=); waiting_to_be_paid_back is deprecated, use waiting_to_be_paid_back_by_currency |
| POST | /claims | Claim an expense {description, amount, date, gst?, receipt: {name, type, base64}, draft?} |
| GET | /claims/review | Claims to review, finance access only (?status=) |
| GET | /people | People in the organisation (?contacts=true adds client contacts; ?q=) |
| POST | /people | Add a client contact {name, title?, email?, phone?, client?} |
| GET | /people/{person} | One client contact with Important Context and todos |
| PATCH | /people/{person} | Update {name?, title?, email?, phone?, add_client?, remove_client?} |
| GET | /work-statuses | The organisation's work statuses, in order {work_statuses: [{id, name, group}], default} |
| GET | /fields/{table} | The fields of work, companies or people: built-in and custom, in display order {table, fields: [{key, label, builtin, type?, hidden, options?}]} |
| GET | /work-types | The organisation's work types, in order {work_types: [{id, name, work_items}], untyped} |
| GET | /work-items | List work items (?type=&area=&q=&include_archived=true) |
| GET | /projects | List projects (?type=&area=&q=&include_archived=true) (old address; use /api/v1/work-items) |
| POST | /work-items | Create a work item {title, type? (a work type's id or name), client?, note?, status?} |
| POST | /projects | Create a project {title, type? (a work type's id or name), client?, note?, status?} (old address; use /api/v1/work-items) |
| GET | /work-items/{work_item} | One work item with its Important Context, todos and ideas |
| GET | /projects/{project} | One project with its Important Context, todos and ideas (old address; use /api/v1/work-items/{work_item}) |
| PATCH | /work-items/{work_item} | Update {title?, type? (id or name; "none" to clear), client?, status? (New, Progressing or Done), key_people? (list of person ids or names, first = primary)} |
| PATCH | /projects/{project} | Update {title?, type? (id or name; "none" to clear), client?, status? (New, Progressing or Done), key_people? (list of person ids or names, first = primary)} (old address; use /api/v1/work-items/{work_item}) |
| POST | /work-items/{work_item}/context | Add to Important Context {text?, url?, happened_on? (YYYY-MM-DD, today or earlier), files?: [{name, type?, base64}] (up to 10, 20 MB each)} |
| POST | /projects/{project}/context | Add to Important Context {text?, url?, happened_on? (YYYY-MM-DD, today or earlier), files?: [{name, type?, base64}] (up to 10, 20 MB each)} (old address; use /api/v1/work-items/{work_item}/context) |
| PATCH | /work-items/{work_item}/context/{entry_id} | Replace an entry's text {text} |
| PATCH | /projects/{project}/context/{entry_id} | Replace an entry's text {text} (old address; use /api/v1/work-items/{work_item}/context/{entry_id}) |
| DELETE | /work-items/{work_item}/context/{entry_id} | Undo an entry you just added (own entries, within 10 minutes) |
| DELETE | /projects/{project}/context/{entry_id} | Undo an entry you just added (own entries, within 10 minutes) (old address; use /api/v1/work-items/{work_item}/context/{entry_id}) |
| POST | /work-items/{work_item}/context/{entry_id}/comments | Comment on an entry {text, mentions?: [user id]} (write @{user id} in the text) |
| POST | /projects/{project}/context/{entry_id}/comments | Comment on an entry {text, mentions?: [user id]} (write @{user id} in the text) (old address; use /api/v1/work-items/{work_item}/context/{entry_id}/comments) |
| POST | /work-items/{work_item}/todos | Add a todo here {title, due?, due_time?, assignee?, note?} |
| POST | /projects/{project}/todos | Add a todo here {title, due?, due_time?, assignee?, note?} (old address; use /api/v1/work-items/{work_item}/todos) |
| POST | /work-items/{work_item}/ideas | Add an improvement idea {text} |
| POST | /projects/{project}/ideas | Add an improvement idea {text} (old address; use /api/v1/work-items/{work_item}/ideas) |
| GET | /work-items/{work_item}/documents | List the Word and PDF documents |
| GET | /projects/{project}/documents | List the Word and PDF documents (old address; use /api/v1/work-items/{work_item}/documents) |
| GET | /work-items/{work_item}/documents/{document} | Read a Word document's text and comments |
| GET | /projects/{project}/documents/{document} | Read a Word document's text and comments (old address; use /api/v1/work-items/{work_item}/documents/{document}) |
Using ChatGPT, Gemini, Copilot, Cursor or another AI tool? Connect it over MCP instead: /mcp/setup.
Machine-readable description: /api/v1/openapi.json (OpenAPI 3.1), for Postman, Zapier, Make, n8n or a GPT action.