API overview
A typed, versioned REST API over your whole Hoursmith workspace — clients, projects, tasks, time, expenses, and read access to invoices.
The Hoursmith REST API lets external systems and scripts drive your workspace without scraping the UI. It's the same engine the app uses, exposed as a clean, predictable, JSON API.
- Plan
- StudioAgency
API access is a paid feature. Your workspace must be on Studio or Agency, and you need an
API token. If your plan lapses, tokens stop working with a 402 error.
Base URL and version
https://my.hoursmith.app/api/v1The API is version-prefixed (/api/v1). All requests and responses are JSON with camelCase
keys. A future breaking change would ship under /api/v2.
The API now lives on the my. subdomain. The old https://hoursmith.app/api/v1 host still
answers for existing integrations, but https://my.hoursmith.app/api/v1 is canonical — point new
work there. (Bearer requests aren't redirected across hosts, so use the canonical host directly.)
What you can do
Full create, read, update, delete is available for:
Read-only access is available for:
- Invoices — responses also include a
paymentMethodsarray (the card + manual-method config;nullmeans legacy dynamic resolution) - Members, Organization, and the token's own identity (
/me)
Invoice creation, sending, and team management are not exposed by the API in v1 — those stay in the app. The API focuses on the data you feed invoices (clients, projects, tasks, time, expenses) and read access to the results.
How it fits together
Everything you do over the API maps to the same model as the app: Clients → Projects → Tasks → Time → Invoices. A typical integration creates a client and project, logs time entries against them, and reads back invoices once you bill in the app. See common workflows.
Conventions at a glance
| Concern | Convention | Details |
|---|---|---|
| Auth | Authorization: Bearer hsk_… | Authentication |
| Permissions | Inherited from the token's member role | Permissions & plans |
| Writes | Idempotency-Key required on every POST | Idempotency |
| Lists | Cursor pagination (cursor, limit) | Pagination |
| Lists | sort, search, and field filters | Filtering & sorting |
| Limits | Per-token rate limits with headers | Rate limits |
| Errors | { "error": { "code", "message" } } | Errors |
Interactive reference
The API reference documents every endpoint with parameters,
schemas, responses, and a Try it playground. The machine-readable OpenAPI document is served by
the app at https://my.hoursmith.app/api/openapi.json, and a hosted Scalar UI lives at
https://my.hoursmith.app/api-docs.
Prefer natural language?
The MCP server wraps this same API so AI assistants like Claude, Cursor, Zed, and Odin can read and write your workspace for you.