Hourtick API V1 API
The Hourtick REST API. Authenticate with a personal API token: create one in **Settings → API tokens**, then send `Authorization: Bearer ht_…`.
Operations 134
GET
/api/v1/bootstrap
Current user, workspace, projects and task types
GET
/api/v1/time-entries
Your time entries in a date range, plus the running entry
PATCH
/api/v1/time-entries
Edit one or many entries (managers and up)
POST
/api/v1/commands
Start, stop, continue, create, edit, delete or restore time
GET
/api/v1/reports
Totals, groups and entries for a period (team scope for managers). For admins, totals and groups also carry the P&L: `peopleCostMinor` (hours × each person's cost rate on that day)
GET
/api/v1/stream
Server-Sent Events: live entry changes for your account and task changes in the workspace
GET
/api/v1/timesheets
Your status for a week
POST
/api/v1/timesheets
Submit or withdraw your week
GET
/api/v1/approvals
Weeks waiting for approval (managers)
POST
/api/v1/approvals
Approve, send back or reopen a week (managers)
POST
/api/v1/invoicing
Mark entries as invoiced or not (admins; locks entries)
GET
/api/v1/members
Workspace members (managers)
GET
/api/v1/cost-rates
Every member's hourly cost rates, newest first (admins)
PUT
/api/v1/members/{userId}/cost-rate
Set what an hour of a member costs, from a day on (admins). Effective-dated: time is costed at the rate valid on its day
GET
/api/v1/agent-costs
Agent cost ledger for a period: an agent's own rows, or all for admins (`agentId` narrows it)
POST
/api/v1/agent-costs
Report what a piece of work cost (agent token: its own; admins: give agentId). Counts toward the agent's budget and the P&L. Report each cost once (here, MCP log_time usage, or ses
GET
/api/v1/ai-providers
AI provider connections for verified agent cost (admins). Keys are never returned, only their last 4 characters
POST
/api/v1/ai-providers
Connect Anthropic (Admin API key), OpenAI (admin key) or OpenRouter (management key) to read what they billed (admins). The key is checked against the provider, then stored encrypt
PATCH
/api/v1/ai-providers/{id}
Rename, or turn filling in from bills on or off (admins)
DELETE
/api/v1/ai-providers/{id}
Remove the key, its synced bills and the cost it filled in (admins)
GET
/api/v1/ai-providers/{id}/scopes
What the key can see (Anthropic workspaces, OpenAI projects and API keys, OpenRouter keys) and which agent each is mapped to (admins)
PUT
/api/v1/ai-providers/{id}/scopes
Map a scope to an agent, or clear it with agentId null. A scope belongs to one agent (admins)
POST
/api/v1/ai-providers/{id}/sync
Read the last 30 days of bills now and reconcile (admins). Runs every 6 hours on its own
GET
/api/v1/reports/cost-reconciliation
Agent cost as reported vs as billed by the providers, per agent and UTC month, with what was filled in (source `provider` in the cost ledger) (admins)
GET
/api/v1/reports/agent-outcomes
Agent outcomes: tasks with agent work done in the period, with the agent's time and cost plus people's time before (briefing) and after (review and rework) the agent delivered, how
GET
/api/v1/client-ai-reports/preview
Client AI work report without sharing it: people's and agents' hours, agents and models, and whether a person reviewed each piece of agent work. No rates, costs or notes (managers)
GET
/api/v1/client-ai-reports
Shared client AI work reports, newest first (managers). Links are not listed
POST
/api/v1/client-ai-reports
Freeze a client AI work report and get a share link (admins). The link (`link.url`) is only in this response; the page is /ai-report/{token} and its JSON /api/ai-reports/{token}, w
DELETE
/api/v1/client-ai-reports/{id}
Revoke a shared report: its link stops working at once (admins)
GET
/api/ai-reports/{token}
A shared client AI work report as JSON, no account needed (the link is the credential). CORS open
DELETE
/api/v1/agent-costs/{id}
Remove a wrong cost row (admins)
GET
/api/v1/integrations
Linear, Notion, Teamwork and Asana: whether each is available and whether you are connected
POST
/api/v1/integrations/{provider}
Start connecting: returns the vendor's approval address to open in a browser
DELETE
/api/v1/integrations/{provider}
Disconnect: forgets the tokens and asks the vendor to revoke them where it supports that
GET
/api/v1/work-items/{id}/links
Items linked to a task, with their current title and status (re-read when older than 5 minutes)
POST
/api/v1/work-items/{id}/links
Link a Linear issue, Notion page, Teamwork task or Asana task by its address
DELETE
/api/v1/work-items/{id}/links/{linkId}
Remove a link. Time already sent to Teamwork stays there
GET
/api/v1/notes
Notes on a project (`projectId`) or client (`clientId`): titles and previews, newest edit first
POST
/api/v1/notes
Create a note on a project or client
GET
/api/v1/notes/{id}
One note: title, Tiptap `content`, `markdown`, plain `text` and `version`
PATCH
/api/v1/notes/{id}
Save a note
DELETE
/api/v1/notes/{id}
Delete a note (its creator or a manager)
GET
/api/v1/files
Files on a project (`projectId`) or client (`clientId`), newest first
POST
/api/v1/files
Upload a file to a project or client (multipart: file, projectId or clientId; up to 25 MB; counts toward usage)
GET
/api/v1/files/{id}
Open a file: redirects to a short-lived signed URL (`?download=1` to download, `?format=json` for `{ url }`)
DELETE
/api/v1/files/{id}
Delete a file (its uploader or a manager)
GET
/api/v1/records/counts
Notes and files per project and client
GET
/api/v1/clients
Clients with VAT numbers and active project counts
POST
/api/v1/clients
Create a client (admins, or an agent an admin allowed), optionally with a VAT number. Records who added it
GET
/api/v1/payments
The workspace's Stripe connection: connected, ready to send invoices, and (admins) account, VAT and payment-term settings
PATCH
/api/v1/payments
VAT rate (basis points) and label, and default days until due (admins)
DELETE
/api/v1/payments
Stop sending invoices through the account (admins). The Stripe account, its money and sent invoices stay the business's
POST
/api/v1/payments/connect
Start or resume Stripe-hosted onboarding and get its one-time URL (admins, people only). The first time it needs `country`, where the business is registered
POST
/api/v1/invoices/preview
What an invoice would contain: lines, VAT, total, and anything that stops sending (admins; agents for their clients). Changes nothing
GET
/api/v1/invoices
Invoices, newest first (admins; agents see their clients')
POST
/api/v1/invoices
Create an invoice from a client's billable time not invoiced yet and send it through Stripe. The time is locked as invoiced. An agent outside its mandate gets status `pending_appro
GET
/api/v1/invoices/{id}
One invoice with its lines, payment page and timesheet link
POST
/api/v1/invoices/{id}/approve
Approve an agent's invoice waiting outside its mandate, and send it (admins)
POST
/api/v1/invoices/{id}/retry
Send an invoice again that didn't reach Stripe (admins). Nothing is created twice
POST
/api/v1/invoices/{id}/void
Void an invoice (or discard one not sent); its time becomes billable again (admins). A paid invoice is refunded in Stripe instead
GET
/api/v1/invoice-mandates
What agents may invoice without approval (admins; an agent sees its own)
POST
/api/v1/invoice-mandates
Let an agent send invoices on its own: clients (empty: any it works on), most per invoice (minor units, workspace currency), expiry (admins)
DELETE
/api/v1/invoice-mandates/{id}
Stop an invoice mandate; the agent's invoices wait for approval again (admins)
PATCH
/api/v1/clients/{id}
Rename a client, set or clear its VAT number, set its billing details for invoices (email, address, country, language, VAT treatment; people only), or archive it (admins)
POST
/api/v1/projects
Create a project (admins, or an agent an admin allowed). Records who added it
PATCH
/api/v1/projects/{id}
Update a project (admins): billing, budget, rate, task types, archive, and memberIds (the team; empty means everyone can track on it)
GET
/api/v1/work-items
Tasks on the board: open ones plus done in the last 14 days (`done=all` for everything)
POST
/api/v1/work-items
Create a task (any member)
GET
/api/v1/work-items/{id}
A task with description, checklist, timeline (comments, files, events) and time per person
PATCH
/api/v1/work-items/{id}
Update a task. Moving between columns: send `status` (and `position` to place it; lower is higher up)
DELETE
/api/v1/work-items/{id}
Delete a task with its comments and files (creator or managers). Tracked time is kept
GET
/api/v1/work-items/{id}/comments
The task's comments, oldest first, with their files (an agent's comment has `meta.agentId`)
POST
/api/v1/work-items/{id}/comments
Post in the task's chat; `attachmentIds` links files you uploaded
PATCH
/api/v1/work-items/{id}/comments/{commentId}
Edit your comment
DELETE
/api/v1/work-items/{id}/comments/{commentId}
Delete a comment and its files (author or managers)
POST
/api/v1/work-items/{id}/checklist
Add a checklist item
PATCH
/api/v1/work-items/{id}/checklist/{itemId}
Tick, rename or move a checklist item
DELETE
/api/v1/work-items/{id}/checklist/{itemId}
Remove a checklist item
POST
/api/v1/work-items/{id}/attachments
Upload a file (multipart/form-data, field `file`, up to 25 MB). Link it by posting a comment with its id
GET
/api/v1/attachments/{id}
Redirects to a 5-minute signed URL. Images, PDFs, video, audio and text preview inline; everything else downloads. `?download=1` forces a download
DELETE
/api/v1/attachments/{id}
Delete a file (uploader or managers)
GET
/api/v1/task-views
Your saved Tasks views (personal)
POST
/api/v1/task-views
Save a view: people, agents, projects, clients and labels (any-of; `none` for unset), search and layout
PATCH
/api/v1/task-views/{id}
Rename, move or update a view's filters
DELETE
/api/v1/task-views/{id}
Delete a view
GET
/api/v1/usage
Usage this month and the plan's limit, in bytes (1 GB = 10^9): stored data (database share and files) plus data in and out since the 1st
PUT
/api/v1/billing/storage
Set extra GB on Pro ($10/GB per month; admins). More is charged pro rata right away
GET
/api/v1/chat/channels
Your channels and DMs with unread and mention counts. `?browse` adds public channels you haven't joined
POST
/api/v1/chat/channels
Create a channel (name is slugged; private channels need `memberIds`)
PATCH
/api/v1/chat/channels/{id}
Rename, set the topic or archive
POST
/api/v1/chat/channels/{id}/join
Join a public channel
GET
/api/v1/search
Search the workspace (the ⌘K palette)
GET
/api/v1/gifs
GIFs for the chat picker (Powered by GIPHY)
PATCH
/api/v1/chat/channels/{id}/preferences
Your preferences for a channel
POST
/api/v1/chat/channels/{id}/leave
Leave a channel
POST
/api/v1/chat/channels/{id}/members
Add people and agents
POST
/api/v1/chat/channels/{id}/read
Mark the channel read
GET
/api/v1/chat/channels/{id}/messages
50 top-level messages, newest last, with `refs`. `?before=` pages back; `?thread=` returns a whole thread
POST
/api/v1/chat/channels/{id}/messages
Post a message (`parentId` replies in a thread; `attachmentIds` links uploaded files). Mentioning an agent queues a session
POST
/api/v1/chat/channels/{id}/files
Upload a file (multipart/form-data, field `file`, up to 25 MB), then send its id in `attachmentIds`
GET
/api/v1/chat/files/{id}
Redirects to a 5-minute signed URL; `?download=1` forces a download
POST
/api/v1/chat/dms
Open (or reuse) a DM with one or more people and agents
PATCH
/api/v1/chat/messages/{id}
Edit your message
DELETE
/api/v1/chat/messages/{id}
Delete a message and its files (author or managers)
POST
/api/v1/chat/messages/{id}/reactions
Toggle an emoji reaction
POST
/api/v1/chat/messages/{id}/task
Turn a message into a task; a reply links to it
POST
/api/v1/chat/typing
Say you're typing (shown for 5 seconds)
GET
/api/v1/chat/search
Full-text search in messages you can read
GET
/api/v1/presence
Who's online, what they're tracking (if they share it) and which agents are connected
GET
/api/v1/agents
Agents in the workspace: provider, model, skills, access, whether they're connected, and canUse (whether you may ask it)
POST
/api/v1/agents
Add an agent (admins only): name, description, provider, model, skills. Returns its token once
PATCH
/api/v1/agents/{id}
Rename, describe, set provider, model and skills, set who may ask it (access: everyone or restricted to allowedRoles and allowedUserIds; its owner and admins always may), or turn o
POST
/api/v1/work-items/{id}/dependencies
Mark this task blocked by another (type blocked_by) or blocking another (type blocks). Refuses itself, loops and more than 50 blockers. A blocked task can't move to in progress, re
DELETE
/api/v1/work-items/{id}/dependencies
Remove the dependency; a task with no open blockers left unlocks
GET
/api/v1/agents/{id}/events
The agent's activity log and this month's usage against its budget (owner or admins)
GET
/api/v1/agents/{id}/instructions
The agent's instructions and every earlier version (owner or admins)
POST
/api/v1/agents/{id}/webhook
action: test (sends a signed agent.ping and returns the status it got) or rotate (a new signing secret, shown once). Owner or admins
GET
/api/v1/agent-requests
Requests for new agents: all for admins, your own otherwise
POST
/api/v1/agent-requests
Ask the admins for a new agent (people and agents)
PATCH
/api/v1/agent-requests/{id}
Approve (creates the agent, owned by you, without a token) or decline. Admins signed in as themselves
POST
/api/v1/agents/{id}/token
Replace the agent's token (owner)
GET
/api/v1/agent-sessions/{id}
One agent session: status, steps, answer, reported tokens and cost, and the helpers it delegated to
POST
/api/v1/agent-sessions/{id}/cancel
Stop an agent's work and every helper it delegated to (requester or managers)
POST
/api/v1/delegations
Hand work to an agent: an existing task (workItemId), a new task (title), or a quick request (neither). Agents chain helpers with the MCP tool agent_delegate
POST
/api/v1/workspaces
Create a workspace
POST
/api/v1/workspace/switch
Move this signed-in device to another workspace you're a member of, and make it your default. Sign-in sessions only; API and agent tokens stay in their own workspace. Bootstrap lis
GET
/api/v1/connected-apps
Apps you connected over OAuth (ChatGPT, Claude…). They act as you in your default workspace
DELETE
/api/v1/connected-apps/{clientId}
Disconnect an app: its tokens stop working at once
POST
/api/v1/work-items/{id}/delegate
Hand a task to an agent. The people on it stay responsible
GET
/api/v1/work-items/{id}/agent-sessions
Agent work on a task, with each session's activity
GET
/api/v1/activity
Your day: tracked entries and what you did (tasks created, moved or commented on, chat messages per channel, agent requests), for drafting a timesheet
GET
/api/v1/reports/agents
Agent session time (how long agents worked on requests), tokens and reported cost in USD, by agent and project. Time agents log appears in the normal reports as their own rows
POST
/api/v1/tasks
Create a task type (admins)
PATCH
/api/v1/tasks/{id}
Update a task type (admins)