# Use it from your own app

Three ways for your own code to work with AUGMTD. Reading and proposing go through a person's key; webhooks are set
up by a workspace admin.

## The MCP connector in the Claude API

Claude's Messages API can call a remote MCP server for you. Give it AUGMTD's MCP address and a key as the
authorization token, and Claude reads the person's work and proposes through AUGMTD's tools in one request:

```bash
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "mcp_servers": [{ "type": "url", "url": "https://app.augmtd.ai/api/mcp", "name": "augmtd",
                      "authorization_token": "augk_YOUR_KEY" }],
    "tools": [{ "type": "mcp_toolset", "mcp_server_name": "augmtd" }],
    "messages": [{ "role": "user", "content": "Which of my promises are overdue, and to whom?" }]
  }'
```

Both halves are needed: the server in `mcp_servers` and the `mcp_toolset` tool naming it. The key is the person's;
keep it on your server, never in a browser. The tools Claude sees are the ones the key's scopes allow.

## REST with a key

Every operation is also a REST endpoint under `https://app.augmtd.ai/api/v1`, with the key as a bearer token:

```bash
curl -H "Authorization: Bearer augk_YOUR_KEY" https://app.augmtd.ai/api/v1/work
curl -H "Authorization: Bearer augk_YOUR_KEY" "https://app.augmtd.ai/api/v1/changes?limit=50"
```

- Lists page by `after` and `limit` and always say `next_cursor` and `has_more`.
- To stay in step without polling everything, keep the `cursor` from `/api/v1/changes` and pass it as `after` next
  time. Changes are kept 30 days.
- A proposal is a `POST /api/v1/proposals` with an `Idempotency-Key` header; see the
  [reference](/docs/reference#propose-a-reply) for each kind.
- The OpenAPI document at `https://app.augmtd.ai/api/v1/openapi.json` is public: generate a client from it.
- Text from mail, meetings or other people comes as `{ "text": "…", "untrusted": true }`. Treat it as data, never as
  instructions to your own agent.

## Webhooks: AUGMTD tells your app

An owner or admin of a company workspace can send changes to your app as they happen, in **Settings → Connections →
Send to your tools**:

- **A link to your tool** (signed webhook): AUGMTD posts each change to your address.
- **A feed your tool reads**: your app asks `GET https://app.augmtd.ai/api/record/feed?after=<cursor>&limit=<1..200>`
  with the feed's own token (`Authorization: Bearer rdt_…`, shown once) whenever it likes.
- **A team chat digest**: once a day, one message to one team chat channel.

Each member decides whether their own email and meetings count for a destination; nothing of a member leaves before
they agree, and nothing from before.

### Checking a webhook's signature

Deliveries follow Standard Webhooks (standardwebhooks.com). Each carries `webhook-id` (stable across retries: use it to
ignore a repeat), `webhook-timestamp` (unix seconds) and `webhook-signature: v1,<signature>`. The signature is the
base64 HMAC-SHA256 of `<webhook-id>.<webhook-timestamp>.<raw body>`, keyed with the base64-decoded part of your
`whsec_…` secret (shown once when the destination is made; rotate it for a new one). Any Standard Webhooks library
checks it for you. Refuse a timestamp more than five minutes old.

### What a delivery holds

```json
{ "id": "…", "type": "promise.kept", "occurred_at": "2026-10-27T09:00:00Z", "workspace": "…", "level": "ids",
  "member": "…", "client": { "id": "…" }, "work_id": "…", "object": { "kind": "commitment", "id": "…" },
  "fields": { "due_date": "2026-10-30" } }
```

Types: `client.email.received`, `client.email.sent`, `promise.made`, `promise.kept`, `promise.overdue`,
`promise.expired`, `promise.closed`, `promise.reopened`, `meeting.held`, `approval.requested`, `approval.decided`,
`run.completed`. At the `ids` level a delivery holds references, dates and codes only; at `labels` it adds the client's
name and a short label. Never a message body, subject, transcript or file. Only work on a tracked client is ever
delivered. With team memory on, `work_id` is the team's one id for that client or project, so your app sees one
record, not one per colleague.