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 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/meWho you are, the organisation, work items by type and your open todos
GET/searchSearch everything you can see
GET/initiativesList projects (?type=&area=&q=&include_archived=true) (old address; use /api/v1/work-items)
POST/initiativesCreate 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}/contextAdd 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}/commentsComment 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}/todosAdd a todo here {title, due?, due_time?, assignee?, note?} (old address; use /api/v1/work-items/{work_item}/todos)
POST/initiatives/{initiative}/ideasAdd an improvement idea {text} (old address; use /api/v1/work-items/{work_item}/ideas)
GET/initiatives/{initiative}/documentsList 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/clientsList clients (?q=)
POST/clientsCreate 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}/contextAdd 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}/commentsComment on an entry {text, mentions?: [user id]} (write @{user id} in the text)
GET/clients/{client}/documentsList the client's documents
GET/clients/{client}/documents/{document}Read a client's Word document
POST/clients/{client}/todosAdd a todo for a client {title, due?, assignee?, note?}
GET/todosYour 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/todosAdd 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}/commentsComment on a todo {text, mentions?: [user id]}
GET/time/entriesYour 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/entriesLog 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/timerYour running timer, or null
POST/time/timer/startStart a timer {todo? | work_item? | client?, replace?, note?}
POST/time/timer/stopStop 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/categoriesThe Forum boards you can see
GET/forum/categories/{category}/threadsThreads on a board (?cursor=)
GET/forum/threads/{thread}One thread with a page of replies (?cursor=)
POST/forum/threadsStart a thread {category, title, body (Markdown), work?, company?}
POST/forum/threads/{thread}/repliesReply {text (Markdown), quote_of?}
GET/inboxYour Inbox, newest first, 50 a page (?cursor=); text is a short preview
GET/inbox/{id}One Inbox item with its whole text
GET/ideas-pageYour own Ideas items, newest first, 50 a page (?cursor=)
POST/ideas-page/{item}/highlightsHighlight words in an Ideas item {quote, note?, at?}
POST/inbox/{id}/highlightsHighlight words in an Inbox note {quote, note?, at?}
POST/highlights/{id}Change the note on your highlight {note}
POST/ideas-pageAdd 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}/commentsComment on an Ideas item {text, mentions?: [user id]}
POST/inboxSave to your Inbox {text, url?}
GET/claimsYour expense claims (?status=); waiting_to_be_paid_back is deprecated, use waiting_to_be_paid_back_by_currency
POST/claimsClaim an expense {description, amount, date, gst?, receipt: {name, type, base64}, draft?}
GET/claims/reviewClaims to review, finance access only (?status=)
GET/peoplePeople in the organisation (?contacts=true adds client contacts; ?q=)
POST/peopleAdd 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-statusesThe 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-typesThe organisation's work types, in order {work_types: [{id, name, work_items}], untyped}
GET/work-itemsList work items (?type=&area=&q=&include_archived=true)
GET/projectsList projects (?type=&area=&q=&include_archived=true) (old address; use /api/v1/work-items)
POST/work-itemsCreate a work item {title, type? (a work type's id or name), client?, note?, status?}
POST/projectsCreate 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}/contextAdd 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}/contextAdd 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}/commentsComment on an entry {text, mentions?: [user id]} (write @{user id} in the text)
POST/projects/{project}/context/{entry_id}/commentsComment 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}/todosAdd a todo here {title, due?, due_time?, assignee?, note?}
POST/projects/{project}/todosAdd a todo here {title, due?, due_time?, assignee?, note?} (old address; use /api/v1/work-items/{work_item}/todos)
POST/work-items/{work_item}/ideasAdd an improvement idea {text}
POST/projects/{project}/ideasAdd an improvement idea {text} (old address; use /api/v1/work-items/{work_item}/ideas)
GET/work-items/{work_item}/documentsList the Word and PDF documents
GET/projects/{project}/documentsList 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.