Focused Work
Integration surface / v1

Developer API

Read the work you own and automate explicit project or task commands without scraping the interface. Every write is replay-safe and follows the same ownership and lifecycle rules as the application.

Manage API keys
01

Authentication

Create a named key in Settings. The secret is shown once.

Send the key as a bearer token. Keys are stored as hashes and can be revoked independently without signing out your account.

curl https://focused-work.wscm.eu/api/v1/projects \
  -H "Authorization: Bearer fw_your_key"

Keep keys in a secret manager. Never place them in browser code, URLs, screenshots, or a public repository.

02

Endpoints

Reads are capped at 200 rows; writes require replay protection.

GET/api/v1/projects

Project identity, cadence, status, and optional weekly focus budget.

Filters: status, updatedAfter, limit
POST/api/v1/projects

Create a project with cadence, color, focus budget, and optional client context.

Filters: Idempotency-Key header + JSON body
GET/api/v1/tasks

Tasks with project context, civil schedule dates, recurrence, and completion state.

Filters: projectId, state, scheduledFrom, scheduledTo, updatedAfter, limit
POST / PATCH/api/v1/tasks

Create tasks, change details, move them across civil dates, or complete them through the same ownership-safe commands as the app.

Filters: Idempotency-Key header + JSON body
GET/api/v1/focus-sessions

Recorded focus/rest counters and the real lifecycle state of each session.

Filters: projectId, status, from, to, limit
03

Replay-safe commands

A network retry must not create the same work twice.

Send a unique Idempotency-Key with every POST or PATCH. Repeating the same key and body within 24 hours returns the original result with Idempotency-Replayed: true. Reusing the key for a different body returns 409.

curl -X POST https://focused-work.wscm.eu/api/v1/tasks \
  -H "Authorization: Bearer fw_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-08-24-001" \
  -d '{"projectId":"project_id","title":"Review release","scheduledDate":"2026-08-24"}'
04

Dates and responses

The API keeps calendar dates separate from instants.

  • scheduledDate and schedule filters use civil dates: yyyy-MM-dd.
  • Session and audit timestamps use ISO 8601 instants in UTC.
  • Collections return { data, meta }; errors return { error: { code, message } }.
  • Responses are private, non-cacheable JSON.
05

Imports and webhooks

Bulk writes preview first; outbound events are signed.

  • JSON imports accept up to 500 rows with projectIdor projectName, title, optional description, scheduledDate, estimateMinutes, and priority. Task updates are atomic: use a separate idempotency key for scheduling, completion, and detail edits.
  • CSV uses the same field names as its header. Preview reports every invalid row before a commit can write anything.
  • Webhook bodies use { id, type, occurredAt, data }and include X-Focused-Work-Event, X-Focused-Work-Delivery, and an HMAC-SHA256 X-Focused-Work-Timestamp and X-Focused-Work-Signature. Verify the v1 HMAC againsttimestamp + "." + rawBody, reject stale timestamps, and deduplicate the delivery ID.
  • Failed deliveries retry with backoff and remain auditable.