Connect your tools

API, MCP and webhook

The team instance’s three access paths, authentication and an incoming webhook example.

Version 0.1.0 · English documentationMarkdown documentation ↓

The team instance provides three complementary access paths. A standalone desktop workspace exposes no network port.

AccessPurposeAuthentication
/api/v1Accounts, projects, time entries, sync, reports and exportsApp session with member permissions; browser cookie + CSRF or native Bearer session
/mcpPersonal tools for Codex and Claude CodeExpiring, revocable personal token with explicit scopes
POST /hooks/work-notesReceive a proposed private work notePersonal token with work.draft_own and an Idempotency-Key

A personal MCP token does not open REST routes, collective exports or another member’s account. See the REST reference and assistant integrations.

Call the API

POST /api/v1/auth/login with email, password and native: true returns an application Bearer session. Treat it like a password. It inherits the account’s permissions and expires; it is not a narrowly scoped integration token. For REST automation, use a dedicated account with the minimum necessary role and keep credentials outside the repository. V0.1 has no separate REST service tokens or OAuth.

http
GET /api/v1/projects
Authorization: Bearer APPLICATION_SESSION

Time commands carry the received version and a unique idempotency key. If a network response is lost, replay the same key and content. After 409, reread the state and resolve the conflict.

http
POST /api/v1/timer/start
Authorization: Bearer APPLICATION_SESSION
Content-Type: application/json
Idempotency-Key: automation-2026-11-06-0001

{"projectId":"PROJECT_UUID","description":"Prepare the presentation"}

Browsers use their cookie and X-CSRF-Token; JavaScript does not receive a native Bearer session. Cross-origin writes are rejected. The native client keeps its session in the system keychain.

Prepare a work-note webhook

In Connections → Create access, name the automation, choose its lifetime and select only Propose private drafts. Copy the secret once and store it in the external tool’s secret manager. Add projects.read only if MCP project discovery is also needed.

Send HTTPS requests with a stable identifier for each source event:

http
POST /hooks/work-notes
Authorization: Bearer PERSONAL_TOKEN
Content-Type: application/json
Idempotency-Key: source-event-2026-11-06-0001

{
  "projectId": "ASSIGNED_PROJECT_UUID",
  "workDate": "2026-11-06",
  "text": "Mockups prepared; next step: review navigation."
}

Response: {"id":"NOTE_UUID","shared":false,"source":"assistant"}. The note belongs to the token owner and stays private in Work notes until its owner reviews it. The webhook rejects extra properties such as memberId, shared, duration or administration flags. Even an administrator can target only projects personally assigned to them.

The endpoint permits 60 requests per minute per token, with at most 8,000 text characters. The same key and body return the existing note; the same key with different content returns 409. Ordinary REST/webhook keys are retained for 30 days; time-sync receipts have separate retention.

Revocation cuts MCP and webhook access at the next request. Account deactivation and other access revocations apply as well. Keep secrets out of URLs, logs and screenshots.

Hosting and errors

Forward /hooks/ through the same proxy as /api/ and /mcp. No inbound port needs to be opened on desktop clients.

StatusAction
400Check the schema and work date
401Token missing, expired or revoked
403Scope or project assignment insufficient
409Same key reused with different content; resolve before retrying
429Slow down; keep the same key for the same event

External tools must handle errors and never claim a write succeeded without confirmation.

Scope in V0.1

This is an incoming private-note webhook. Outgoing event subscriptions, signed notifications to third-party URLs and webhooks that modify hours are not delivered. MCP timer commands require the additional explicit personal scope timer.write_own.

Ctrl/Cmd + K to open · Escape to close · Search stays on this site.