# Worktruck.app

> Machine-first Personal Information Manager. Contacts, CRM, tasks, calendar, and notes -- accessible via REST API and MCP server. No UI. API and MCP access only.

## API Base URL

https://api.worktruck.app

## Authentication

Three authentication methods:

1. **Bearer API key**: `Authorization: Bearer bsk_live_<key>` -- for developers with Stripe subscriptions
2. **Keycloak OIDC JWT**: `Authorization: Bearer <jwt>` -- OAuth 2.1 access token issued by `auth.builddaddy.app/realms/worktruck` with `aud=mcp`. Used by Claude.ai's custom connector and other OAuth clients via Dynamic Client Registration + PKCE. JWT-authenticated MCP requests must include `Mcp-Protocol-Version: 2025-06-18`
3. **x402 payment receipt**: `PAYMENT-SIGNATURE: <receipt>` -- per-request USDC on Base, no account needed

## Domains

- **Contacts**: People, organizations, relationships, interaction history. CRUD + channels, addresses, dates, relationships, affiliations, interactions, tags, groups.
- **CRM**: Pipelines with ordered stages, deals with value/probability tracking, stage change audit trail, pipeline analytics.
- **Tasks**: Projects with custom status workflows, tasks with subtasks/dependencies/recurrence, sections, milestones, labels, comments, links.
- **Calendar**: Calendars as containers, events with RRULE recurrence, attendees with RSVP, all-day events, timezone handling, cross-domain event links.
- **Notes**: Notebooks, markdown notes, bidirectional wikilinks, cross-domain links (note to contact/task/event/deal), tags, attachments.
- **Agents**: Durable journaled agent runs. One config per blueprint (BYOK Anthropic key). Enqueue runs, journal every step, track cost per run. Integration keys store third-party credentials (Cloudflare, GitHub, Netdata, Postmark, Outstand) for agents to use at runtime. Cron-driven agent schedules auto-enqueue runs on a cadence.
- **Apps**: Tenant-registered MCP servers. Register an external MCP endpoint with auth, Worktruck probes its `tools/list` and mirrors the catalog. Agents can invoke those tools alongside built-in PIM operations.

## Key Endpoints

- `GET /api/v1/contacts` - List/search contacts
- `POST /api/v1/contacts` - Create a contact
- `GET /api/v1/deals` - List deals
- `POST /api/v1/deals` - Create a deal
- `GET /api/v1/tasks` - List tasks
- `POST /api/v1/tasks` - Create a task
- `GET /api/v1/events` - List events
- `POST /api/v1/events` - Create an event
- `GET /api/v1/notes` - List notes
- `POST /api/v1/notes` - Create a note
- `GET /api/v1/tenant` - Get tenant info
- `POST /api/v1/integration-keys` - Store service credential for an agent provider
- `POST /api/v1/integration-keys/{provider}/verify` - Probe credential against provider
- `POST /api/v1/apps` - Register an external MCP server for agents to call
- `POST /api/v1/agents/{blueprint}/runs` - Enqueue an agent run
- `GET /health` - Health check (no auth)

## MCP Server

URL: https://mcp.worktruck.app/mcp/v1
Transport: Streamable HTTP
Auth: Bearer API key, Keycloak OIDC JWT (`aud=mcp`), or x402 payment receipt. JWT callers must send `Mcp-Protocol-Version: 2025-06-18`.

## Pagination

Cursor-based: `?limit=N&cursor=<opaque_string>`
Response: `{ "data": [...], "next_cursor": "...", "has_more": true }`

## Temporal Reads

Contacts, deals, notes, and tasks are bitemporal. Every GET and list endpoint accepts `?as_of=<RFC3339>[&valid_at=<RFC3339>]` to return the state as of that moment. Each entity also exposes:

- `GET /api/v1/{entity}/{id}/history` — full version history, cursor-paginated.
- `GET /api/v1/{entity}/{id}/diff?from=&to=` — field-level diff between two moments.
- `GET /api/v1/{entity}/{id}/timeline?from=&to=[&fields=]` — ordered per-field change events.

Historical responses carry a `_temporal` block with `sys_from`/`sys_to`/`valid_from`/`valid_to` and capture provenance. Reads beyond the tenant's retention window return `410 Gone`. Deals uses `/version-history` (the `/history` route on deals is a legacy stage-change endpoint).

See https://docs.worktruck.app/guides/temporal for the full guide.

## Error Format

`{ "error": { "code": "not_found", "message": "..." } }`

## OpenAPI Spec

https://api.worktruck.app/docs/openapi.json

## Full Documentation

- Docs: https://docs.worktruck.app
- Quickstart: https://docs.worktruck.app/guides/quickstart
- API Reference: https://docs.worktruck.app/api-reference/overview