# Weekkeep agent API and private RSS

Base URL: https://weekkeep.com. Version: 1. Authentication is delegated by a human in Settings → Agents & private feeds. Passkeys require user participation; machine clients use scoped tokens rather than impersonating a biometric verification. There is no anonymous journal or public account feed.

## Credentials

Create a named connection, choose scopes, select 7/30/90-day expiry and confirm with your passkey. The token is shown once. Only its SHA-256 hash is stored. Scope options are `journal:read`, `journal:write` and `feed:read`. Read-only is the default; write access includes deletion of memories. Ten active connections per account, 60 requests per connection per minute, plus account-edge abuse limiting.

Tokens are bearer credentials: possession grants the chosen access. Store them in a password manager or agent secret store. Never paste them into URLs. Revoke a connection in Settings. Recovery-kit changes invalidate old connections; deleting an account deletes its keys. Signing out a browser does not revoke independent connections. Revocation cannot erase content already copied by clients.

## Read

GET `/api/agent/journal` with `Authorization: Bearer <token>`. Returns `{revision, data, sync}`. `data` follows [journal schema v3](https://weekkeep.com/journal.schema.json). `sync` includes `paused` and `epoch`. This is the cloud archive; devices with paused/offline changes may have newer local writing. No session cookies or account administration data are returned.

## Write

POST `/api/agent/events` with `Content-Type: application/json` and the Bearer header. Example body:

```json
{"revision":12,"epoch":4,"event":{"type":"SAVE_ENTRY","entry":{"date":"2026-09-08","title":"A quiet afternoon","text":"## A moment\nA walk by the river.","memory":"Room to think."}}}
```

Use current revision/epoch values from a read. The example values are illustrative. New entries omit `entry.id`; editing requires the existing ID and preserves its creation identity under the app's rules. Supported events: SAVE_ENTRY, DELETE_ENTRY (`id`), TOGGLE_LIVED (`date`), SAVE_COMPASS (`compass` with values/calls/chapter/experiment), CLOSE_WEEK (`start`, `memory`, `experiment`, optional `carry`), REOPEN_WEEK (`start`), ACKNOWLEDGE (`id`). Refer to the schema and error response for validation. Onboarding, restore, account security, AI calls and resuming sync are not agent operations.

Writes apply the domain reducer and schema validation, compare both cloud revision and sync epoch, and retain the previous committed snapshot. Paused sync rejects writes. Calendar transition checks use UTC on the server. Successful writes return `{revision,sync}`; a write-only key does not receive the journal contents. A 409 or unknown network result must be reconciled, not blindly retried: the API does not offer idempotency keys. Read-only or feed-only tokens cannot write.

Errors return JSON `{error}`: 400 invalid input, 401 invalid/expired/revoked key, 403 missing scope or forbidden origin, 409 stale state or paused sync, 413 size limit, 429 rate limit. Retry 429 after at least a minute. API response caching is disabled and credentials are never accepted from query strings. Browser cross-origin access is not enabled.

## Private RSS

GET `/api/agent/feed.rss`. Use `Authorization: Bearer <token>` or a reader supporting HTTP Basic authentication: username `weekkeep`, password the full token. Create a **feed-only** token for a feed reader. Readers that accept only a URL without authentication are not supported; never embed the token in the URL. Configure the reader not to publicly republish the feed.

The RSS 2.0 feed contains the latest 50 memories sorted by journal date, with stable entry IDs and escaped plain-text Markdown bodies. Future-dated notes can appear. Publication timestamps are entry creation times. It excludes account security details. Re-fetch to see edits/deletions; a feed reader may retain previously downloaded copies. Responses are private/no-store and noindex. No feed is advertised publicly for an account.