Skip to content

Feature

A typed REST API for the parts of Hoursmith you live in.

Mint a Bearer token, point your script (or Zapier, or n8n) at /api/v1, and you have a typed surface for every resource Hoursmith manages — clients, projects, tasks, time entries, expenses, invoices. Add an HTTPS endpoint for outbound webhooks and you're notified the instant something happens. OpenAPI 3.1 means your IDE auto-completes the response shapes; an Idempotency-Key header means safe retries; Bearer tokens inherit the minter's role so the API can't accidentally exceed the UI's permissions.

Plans: Studio · Agency

Start freeSee pricing

Free for solo freelancers · No credit card required

What's in it

  • Bearer-token authentication

    Any team member can mint a Personal Access Token from Settings → API. The token authenticates AS that member — Owner/Admin tokens see the whole workspace, Member tokens see only what their session would. Remove the member, the token dies.

  • Every resource, one consistent shape

    GET/POST/PATCH/DELETE on clients, projects, tasks, time entries, expenses. Read-only on invoices, members, and organization. Cursor pagination, decimal-preserving money strings, ISO dates everywhere.

  • OpenAPI 3.1 + Scalar reference

    Auto-generated spec at /api/openapi.json and a live API reference at /api-docs. Drop the spec into your SDK generator and you're done.

  • Stripe-style idempotency

    Every POST takes an Idempotency-Key header. Retry the same key with the same body → cached response. Different body → 409. 24h window. Build retry-safe pipelines without reasoning about timeouts.

  • Per-token rate limiting

    Burst + sustained tiers per plan (Studio: 30/10s + 600/min; Agency: 60/10s + 1200/min). X-RateLimit headers on every response; Retry-After on 429.

  • Outbound webhooks (Agency)

    Subscribe an HTTPS endpoint to invoice.sent, invoice.paid, time_entry.created, task.completed, and more. We POST signed JSON (HMAC-SHA256, Stripe-shaped Hoursmith-Signature) and retry with exponential backoff. Replay any delivery from the Settings UI.

How it works

  1. 01

    1. Mint a token

    Settings → API → New token. Pick read or read+write scope. Copy the secret once — we hash it at rest and never re-render it.

  2. 02

    2. Hit /api/v1

    curl -H 'Authorization: Bearer hsk_live_…' https://app.hoursmith.com/api/v1/clients. JSON in, JSON out. Cursor-paginated lists.

  3. 03

    3. Add idempotency on writes

    Generate a UUID per intended action and pass it as Idempotency-Key on POSTs. Retries during flaky networks become safe by construction.

  4. 04

    4. Subscribe to events (Agency)

    Settings → Webhooks → New endpoint. Pick the events, get a signing secret, verify with crypto.timingSafeEqual on your end. Receive, do work, return 2xx.

Common questions

  • What plans get API access?

    Studio and Agency. The token mint UI is locked on Free with a clear upgrade target; existing tokens stop working immediately if a workspace drops below Studio.

  • What plans get outbound webhooks?

    Agency only. Endpoints can be created and existing endpoints continue firing on Agency; on Studio or Free, endpoint creation 402s and existing endpoints stop firing without code changes.

  • How is a Member token different from an Owner token?

    Both authenticate as their creator. Owner/Admin tokens see the whole org; Manager and Member tokens see only the projects they've been added to. Role changes take effect on the next request — no re-mint needed.

  • Can I forge an invoice via the API?

    No — invoice POST/PATCH/DELETE is deferred to v1.1. Invoices are money-critical and we want one full release cycle of the read path under load before we ship the write path. You can still mark sent, mark paid, etc. via the in-app UI; webhooks notify your systems.

  • Where do I find the API reference?

    Live at /api-docs (powered by Scalar), with the underlying OpenAPI 3.1 document at /api/openapi.json — both public, no auth needed.

  • What if my webhook receiver is down?

    We retry on a 5s / 1m / 5m / 30m / 2h / 6h / 24h schedule — 7 attempts over ~32h. After the last attempt the delivery is marked failed and the endpoint is marked failing; you'll see both in Settings → Webhooks and can replay any individual delivery on demand.

Related

Try it free, in two minutes.

Create an account, set up your first client, and log an hour. The invoice will already be on the way to building itself.

Create your free account

Free for solo freelancers · No credit card · Cancel any time