# waper API

The waper API gives you the same spaces, watches, briefs, library, documents, media and agent as the web app. Desktop, iOS and other agents use it too.

## Authentication

Send `Authorization: Bearer <token>` with every request. The token is a personal API key (`wpr_…`, create one in Settings → API and MCP) or a session token from signing in (response header `set-auth-token`). Cookies are not accepted. This document itself needs no token.

## Conventions

- **Rate limit**: at most 60 requests per minute per account; beyond that you get 429 `RATE_LIMITED`.
- **Errors** are JSON: `{"error": {"code": "WATCH_NOT_FOUND", "message": "…"}}`. `code` is stable, branch on it; `message` is for people. Invalid input returns 400 `INVALID_INPUT` with `issues` (`path` and `message` for each problem).
- **Pagination**: lists return `{"items": […], "nextCursor": "…"}`. Pass `nextCursor` as `?cursor=` for the next page; `null` means there are no more. Cursors are opaque.
- **Idempotency**: create endpoints accept an `Idempotency-Key` header (any unique string, such as a UUID). Retrying with the same key within 24 hours returns the first result (response header `idempotent-replayed: true`) instead of doing the work twice.
- **Time**: `date-time` fields are ISO 8601 strings; fields described as Unix time are milliseconds.
- **Language**: calls that write content accept `lang` (`zh` or `en`); without it, your content language setting is used. Content comes in one language, never side by side.
- **Credits**: reading is free. Calls that make waper read or write for you (messages to your agent, summaries of saved links and files, media transcripts) spend credits; creating a watch counts toward your monthly watch limit. When credits run out you get 402 `CREDITS_EXHAUSTED`; `GET /me` shows what you have left.
- **Compatibility**: new fields can appear in any response, so ignore fields you do not know. Removing or renaming a field, an endpoint or an `operationId` is a breaking change.

## For agents

Prefer MCP (`https://waper.ai/mcp`) when your client supports it: the same capabilities as a small set of tools, described in `https://waper.ai/skill.md`. This API reference is also available as Markdown at `https://docs.waper.ai/openapi.md`.

## Endpoints

Base URL: `https://waper.ai/api/v1`. Each link is the full reference for one endpoint (parameters, request and response schemas, errors). Everything in one file: https://docs.waper.ai/openapi-full.md. Machine-readable OpenAPI 3.1.0: https://docs.waper.ai/openapi.json.

### Account

Your plan, trial, credits by pool and plan limits.

- [`GET /me`](https://docs.waper.ai/reference/getMe.md) `getMe`: Who am I: plan, trial and remaining credits by pool

### Spaces

Spaces hold your watches, library items, documents and conversations. Every account has one default space that cannot be deleted.

- [`GET /spaces`](https://docs.waper.ai/reference/listSpaces.md) `listSpaces`: List spaces
- [`POST /spaces`](https://docs.waper.ai/reference/createSpace.md) `createSpace`: Create a space
- [`PATCH /spaces/{id}`](https://docs.waper.ai/reference/updateSpace.md) `updateSpace`: Rename, change icon, description or position
- [`DELETE /spaces/{id}`](https://docs.waper.ai/reference/deleteSpace.md) `deleteSpace`: Delete a space; its contents move to the default space

### Watches

A watch keeps following a subject, a set of sources or a few pages, and writes a brief with sources on a schedule. Briefs are made of entries; each entry links to its evidence.

- [`GET /watches`](https://docs.waper.ai/reference/listFollowedWatches.md) `listFollowedWatches`: Watches you follow, with their latest brief
- [`POST /watches`](https://docs.waper.ai/reference/createWatch.md) `createWatch`: Create a watch
- [`GET /watches/search`](https://docs.waper.ai/reference/searchWatches.md) `searchWatches`: Find existing public watches for a subject
- [`GET /watches/{slug}`](https://docs.waper.ai/reference/getWatch.md) `getWatch`: A watch with one brief (latest, or a date), its archive and method
- [`GET /watches/{slug}/knowledge`](https://docs.waper.ai/reference/getWatchKnowledge.md) `getWatchKnowledge`: Latest weekly report and the timeline of important items
- [`GET /watches/{slug}/issues`](https://docs.waper.ai/reference/listWatchIssues.md) `listWatchIssues`: Past briefs, newest first
- [`PUT /watches/{slug}/follow`](https://docs.waper.ai/reference/followWatch.md) `followWatch`: Follow a watch (or move it to another space)
- [`DELETE /watches/{slug}/follow`](https://docs.waper.ai/reference/unfollowWatch.md) `unfollowWatch`: Unfollow a watch
- [`PATCH /watches/{slug}/settings`](https://docs.waper.ai/reference/updateWatchSettings.md) `updateWatchSettings`: Owner only: brief cadence and alerts
- [`PUT /entries/{id}/feedback`](https://docs.waper.ai/reference/setEntryFeedback.md) `setEntryFeedback`: Thumbs up or down on a brief item (null clears)
- [`PUT /entries/{id}/saved`](https://docs.waper.ai/reference/setEntrySaved.md) `setEntrySaved`: Save a brief item to the library (or remove it)

### Library

Everything you keep: saved web pages, brief entries, uploaded files and video/audio. waper reads each one, writes a summary and key points, and picks a space when you leave it out.

- [`GET /library`](https://docs.waper.ai/reference/listLibrary.md) `listLibrary`: Saved pages, brief items, uploaded files and saved video/audio, newest first; filter by space or kind, or search
- [`POST /library`](https://docs.waper.ai/reference/saveLink.md) `saveLink`: Save a web page; waper reads it and writes a summary and key points
- [`GET /library/{id}`](https://docs.waper.ai/reference/getLibraryItem.md) `getLibraryItem`: One library item
- [`PATCH /library/{id}`](https://docs.waper.ai/reference/updateLibraryItem.md) `updateLibraryItem`: Change the note or move to another space
- [`DELETE /library/{id}`](https://docs.waper.ai/reference/deleteLibraryItem.md) `deleteLibraryItem`: Remove from the library
- [`GET /library/{id}/text`](https://docs.waper.ai/reference/readLibraryText.md) `readLibraryText`: Full text extracted from an uploaded file, in chunks
- [`POST /library/files`](https://docs.waper.ai/reference/uploadFile.md) `uploadFile`: Upload a PDF, Word (.docx), Markdown, text or image file to the library

### Docs

Documents in waper Markdown. Every save bumps `revision`; pass the revision you read so you never overwrite newer changes.

- [`GET /docs`](https://docs.waper.ai/reference/listDocs.md) `listDocs`: List documents, most recently updated first (no bodies)
- [`POST /docs`](https://docs.waper.ai/reference/createDoc.md) `createDoc`: Create a document from waper Markdown
- [`GET /docs/search`](https://docs.waper.ai/reference/searchDocs.md) `searchDocs`: Search documents by keywords and meaning
- [`GET /docs/{id}`](https://docs.waper.ai/reference/getDoc.md) `getDoc`: Read a document (Markdown body and revision)
- [`PATCH /docs/{id}`](https://docs.waper.ai/reference/updateDoc.md) `updateDoc`: Replace the title and/or body; 409 with the latest content when baseRevision is stale
- [`DELETE /docs/{id}`](https://docs.waper.ai/reference/deleteDoc.md) `deleteDoc`: Delete a document
- [`POST /docs/{id}/edits`](https://docs.waper.ai/reference/editDoc.md) `editDoc`: Apply exact-match edits (replace, insert_after, append, prepend, rewrite)

### Media

YouTube, Bilibili and podcast links turned into timestamped transcripts and summaries. Ask for a quote first: it is charged by the minute.

- [`POST /media/quote`](https://docs.waper.ai/reference/quoteMedia.md) `quoteMedia`: Duration and credit cost before transcribing a link (one price per minute, summary and translation included)
- [`POST /media`](https://docs.waper.ai/reference/startMedia.md) `startMedia`: Turn a YouTube, Bilibili or podcast link into a timestamped transcript and summary (credits per minute)
- [`GET /media`](https://docs.waper.ai/reference/listMedia.md) `listMedia`: Your videos and podcasts, most recently saved first
- [`GET /media/{id}`](https://docs.waper.ai/reference/getMedia.md) `getMedia`: Status, summary, chapters and transcript segments (new segments after a revision while processing)
- [`GET /media/{id}/transcript`](https://docs.waper.ai/reference/getTranscript.md) `getTranscript`: Summary and transcript as Markdown with timestamp links (optionally a time range)

### Agent

Your agent's name, memory and email address, and the home overview of what it is doing for you.

- [`GET /agent`](https://docs.waper.ai/reference/getAgent.md) `getAgent`: Your agent: name, memory (Markdown) and email address
- [`PATCH /agent`](https://docs.waper.ai/reference/updateAgent.md) `updateAgent`: Rename the agent or edit its memory
- [`GET /home`](https://docs.waper.ai/reference/getHome.md) `getHome`: Home: what your agent read, the latest briefs, running tasks, actions waiting for you, suggestions, unread inbox items and recent conversations

### Inbox

Finished tasks, briefs, alerts and suggestions, plus the actions waiting for your decision.

- [`GET /inbox`](https://docs.waper.ai/reference/listInbox.md) `listInbox`: Inbox: actions waiting for your decision, then finished tasks, briefs, alerts and suggestions
- [`POST /inbox/{id}`](https://docs.waper.ai/reference/markInboxItem.md) `markInboxItem`: Mark an inbox item read, done or dismissed

### Tasks

Background work the agent runs for you (watch setup, research, transcription, scheduled tasks). Poll a task to follow its milestones.

- [`GET /tasks`](https://docs.waper.ai/reference/listTasks.md) `listTasks`: Tasks the agent ran for you (watch setup, research, transcription, scheduled tasks), newest first
- [`GET /tasks/{id}`](https://docs.waper.ai/reference/getTask.md) `getTask`: A task with its milestones (plan, steps, output) and the actions it is waiting on
- [`POST /tasks/{id}/cancel`](https://docs.waper.ai/reference/cancelTask.md) `cancelTask`: Cancel a running task; work already done is kept

### Conversations

Talk to your agent. Sending a message starts a turn and returns at once; read the reply from the conversation's messages.

- [`GET /conversations`](https://docs.waper.ai/reference/listConversations.md) `listConversations`: Conversations with your agent, most recently active first
- [`GET /conversations/{id}/messages`](https://docs.waper.ai/reference/getConversationMessages.md) `getConversationMessages`: A conversation and its most recent messages (oldest first)
- [`POST /conversations/messages`](https://docs.waper.ai/reference/sendMessage.md) `sendMessage`: Send a message to your agent (starts a turn); leave out conversationId to start a new conversation
- [`DELETE /conversations/{id}`](https://docs.waper.ai/reference/deleteConversation.md) `deleteConversation`: Delete a conversation

### Actions

Changes the agent wants to make that need your approval, and actions it already did that you can undo.

- [`POST /actions/{id}/decide`](https://docs.waper.ai/reference/decideAction.md) `decideAction`: Approve or reject an action waiting for your decision
- [`POST /actions/{id}/undo`](https://docs.waper.ai/reference/undoAction.md) `undoAction`: Undo an action the agent already did (within its undo window)