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://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.
What you can do
Full create, read, update, delete is available for:
Read-only access is available for:
- Invoices
- 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://hoursmith.app/api/openapi.json, and a hosted Scalar UI lives at
https://hoursmith.app/api-docs.
Prefer natural language?
The MCP server wraps this same API so AI assistants like Claude and Cursor can read and write your workspace for you.