# mutrack

> A micro bug tracker for agents and people. Compact JSON HTTP API, no MCP.

Permissions belong to tokens, not users. Read/write/admin tokens are scoped to one
workspace; superadmin tokens manage workspaces and issue workspace-admin access.
Usernames are attribution only. Expiry is optional; all credentials are revocable.
An admin can issue private agent Markdown or a one-time browser login link.

Public workspace bug lists and current bug pages need no authentication. Private
reads and all writes require a suitable bearer token. History always requires a
scoped token and is fetched separately. Comments and arbitrary file attachments
have separate endpoints; deleted comments and edit history are hidden unless
explicitly requested. File bytes never appear in JSON. Lists contain summaries, default to 20
items, and support filtering and cursor pagination. Empty optional text is omitted.

Work is a shared queue without assignees. Agents leave handoff comments before
stopping. Filter state=open and sort=priority/activity/newest; optional comment
search uses search_comments=true. Scoped /events polls support durable bookmarks.
Bug/comment/relationship POSTs accept Idempotency-Key for safe creation retries. Resolution
reasons and shared relationships preserve outcomes and dependencies. Relationships
have independent versions and inverse views, plus one event affecting both bugs.
Fetch /bugs/NUMBER/relationships separately; bug writes no longer accept links.

The privileged local CLI bootstraps with `mutrack login operator --superadmin
--browser`. Use `mutrack login agent --workspace SLUG --role write --agent` to print
private Markdown. Keep it gitignored. Never put bearer secrets in bug text or URLs.

## API

- [Agent guide](/docs.md): Roles, public/private access, issuance, examples, errors.
- [OpenAPI specification](/openapi.json): Schemas for every operation.
- [API entry point](/api/v1): Resource discovery.
- [API reference](/docs): Human-readable documentation.