REST API

The same capabilities as MCP over plain HTTP: JSON, Bearer auth. This page covers the conventions; every endpoint, with its parameters, schemas, errors and examples, is in the API reference.

API reference

  • Interactive API reference: browse every endpoint and send test requests with your own key (the key stays in your browser).
  • OpenAPI 3.1: import it into Postman or Insomnia, or generate a client (for example openapi-generator, Apple's swift-openapi-generator, openapi-typescript). Every operation has a stable operationId, and shared structures have names, so generated method and type names stay put.
  • Markdown version: an overview and an endpoint list, with one Markdown page per endpoint. Point an AI agent here, or at llms.txt.

The text in the API reference is in English.

Site management, publishing and unpublishing documents, and permanently deleting watches you created are currently available only to signed-in apps and Waper’s first-party agents. They do not accept API keys and are not directly exposed through MCP. See the API reference for parameters and caller access.

Basics

Base URL: https://waper.ai/api/v1 OpenAPI: https://waper.ai/api/v1/openapi.json Auth: Authorization: Bearer <API key>

Create a key in Waper under Settings → API & MCP (see API keys). The OpenAPI document itself needs no key.

A few calls need you in person and don't accept API keys: approving or undoing your agent's actions or approving and retrying a blocked one, reading or changing your "always allow" rules and trusted recipients, listing what the auto-review recently allowed or blocked, reading or changing memory, registering or renaming a computer, disconnecting devices, creating or changing routines (reading the list and run history is not restricted), adding, drafting, changing or deleting agents, giving your main agent a new email address (POST /mail-address/rotate), creating a group chat or adding members to or removing them from one, disconnecting a connected app or turning the recipes it brings on or off (/apps), listing, adding or deleting your own model API keys (/model-keys) and the OpenAI-compatible services you added (/model-services), deleting things in the trash for good (DELETE /trash/{id}), and deleting your account. With a key they return 403 SESSION_REQUIRED, so a key that leaks can't grant itself more power. Do these in the Waper app.

Conventions

  • Errors are JSON: { "error": { "code": "WATCH_NOT_FOUND", "message": "…" } }. Branch on code, which is stable; message is for people. Invalid input returns 400 INVALID_INPUT with issues, one { path, message } per field. The reference lists the errors each endpoint can return. A routine that doesn't pass returns 422 INVALID_ROUTINE with fields, one { field, code } per problem (field is a path such as triggers.0.rule).
  • Pagination: lists that grow (followed watches, library, documents, audio and video, conversations, tasks, routine runs, the work an agent did) return { items, nextCursor } and take ?limit=. Pass nextCursor as ?cursor= for the next page; null means there are no more. Each routine run carries the agent that carried it out (agentId; the main agent for built-ins), which stays the same even if the routine later moves to another agent; the list takes ?agentId= to show only one agent's runs, paged the same way. Small fixed lists (knowledge bases, search results) return { items }.
  • Names: a space in the API is a knowledge base in the app, so filter by knowledge base with spaceId; a watch's writing language is language; lang elsewhere is the content language for summaries and answers.
  • Idempotency: create calls accept an Idempotency-Key header. For a completed request, retrying with the same key within 24 hours returns the first result (with idempotent-replayed: true) instead of doing the work twice. While the earlier request is still running, or its outcome is unknown (the connection dropped, or the server hit an error it could not classify), the same key gets 409 IDEMPOTENCY_IN_PROGRESS for up to 5 minutes: try again later with the same key rather than a new one, which could do the work twice. After 5 minutes the request may execute again, but the same key must still identify the same request within its retention period (422 IDEMPOTENCY_MISMATCH otherwise; the same request sent with a different API key counts as a different request). An explicitly rejected request releases its key: for example, after 422 INVALID_ROUTINE, you can correct the fields and submit with the same key. Retrying watch creation after a lost result returns the existing task. If the watch was removed after failure or cancellation, it is not recreated. Use the returned taskId to check the original task; use the task retry endpoint to restart failed work.
  • Long-running work returns 202 at once: creating a watch gives you a taskId (follow it with GET /tasks/{id}); transcribing audio or video gives you a mediaId (poll GET /media/{id}); a message to your agent gives you the conversation and the reply's ID (poll GET /conversations/{id}/messages until answering is false; load earlier messages with ?before=<id of the oldest message you have> until hasMore is false); an uploaded file is read in the background, and GET /library/{id}/text answers 400 TEXT_NOT_READY until the item's status is ready (poll GET /library/{id}; NO_TEXT means there is no stored text: only uploaded files have it, or the file has no text to read, for example a scan). A failed task whose retryable is true can be started again with POST /tasks/{id}/retry. Pass skill (a slug from GET /skills) with a message to have your agent follow that skill.
  • Uploading a file takes three steps; the bytes go straight to storage, not through Waper's servers:
    1. POST /library/uploads with the file name, its exact size in bytes and the SHA-256 of the whole file (lowercase hex). You get an id, a grant and put.
    2. PUT the file itself as the body to put.url, with exactly the headers in put.headers (do not send Authorization). Storage rejects a size, type or content that differs from what you asked for.
    3. POST /library/uploads/{id}/complete with the grant (and spaceId or note if you like). The file is added to the library and you get its clipId, as when saving a page. When the same content was uploaded before, put is null: skip step 2 and complete. Start the upload within 15 minutes; the grant lasts an hour.
  • Language: content has one language. Calls that write content accept lang (zh or en); without it, your account's content language is used. Watches carry language (the language they are written in), and GET /watches/{slug} and each item in watch lists add contentLanguage (the language of what was returned: a translation into your content language when someone else's watch in another language has one; in lists, the summary and the latest lead switch only when both are translated).
  • Paused watches: GET /watches/{slug} says why a watch's briefs are paused in pause (its owner paused it, ran out of credits, or their plan no longer covers it). The owner pauses and resumes a watch they created with PUT /watches/{slug}/paused (canPause says whether you can). Whether anyone reads a watch doesn't pause it.
  • Time: date-time fields are ISO 8601 strings; fields described as Unix time are milliseconds.
  • Clearing a value: requests never use null. Send an empty string or an explicit value instead (for example "" for a knowledge base icon restores the default, "none" clears entry feedback); leave out fields you don't want to change.
  • Compatibility: new fields can appear in any response, so ignore the ones you don't know.

Agents, chats and background work

You start with one main agent and can add up to 10 more (GET /agents: each with its kind, preset, name and conversationId, its one-to-one chat; kind is main, template or custom). Any agent can move work that takes a while to the background, one Work per piece, shown in the chat as a progress card; when you name another agent or the work clearly belongs to it, it can also ask that agent to do it: the agent you talk to hands a brief to another, and the two agents' exchanges are kept in one thread per pair.

  • With an API key you talk to the main agent in a conversation of your own (POST /conversations/messages): it can move work to the background and do it itself, but never brings in your other agents. The message counts as answered once everything it set off has a result and the agent has said so in the conversation: until then answering stays true, and sending another message returns 409 CONVERSATION_BUSY; the response shape doesn't change. When work stops to wait for your approval, or for something only you can give, the agent says what it is waiting for and that answer is complete; once you have dealt with it, the work carries on and its result comes as a new message in that conversation. Your chats with your agents, and the work in them, are not reachable with a key.
  • Signed in (the apps): PATCH /conversations/{id} pins, hides or marks a chat unread (pinned, hidden, unread: true; the main agent's chat can't be unpinned or hidden, 409 MAIN_CHAT_FIXED); GET /agents/{id}/ongoing backs Needs you, Working on and Routines in the agent's details: waiting (work waiting for your answer, your approval or something only you can give), working (work under way, in line or waiting on other work), routines (its routines and the app recipes it runs, proposals left out; the ones whose last run needs you first), proposed (routines it proposed) and done (the latest work that ended; page back through older ones with the next endpoint); watches aren't here; GET /agents/{id}/works lists every piece of work an agent did (work it took on itself and work other agents asked it for), newest first; GET /works/{id} returns one piece in full (goal what was asked, result what came back, unfinished what was left undone, steps every step, changes what it made, messageId the reply it was started from), 404 WORK_NOT_FOUND when there is none; POST /works/{id}/stop stops one (the apps have no button for this: there you tell the agent;work waiting on it stops too, the rest of the chat carries on; one that already ended is returned as it is; stopped work can be picked up again by asking in the chat); GET /peer-threads/{id} reads the thread between two agents, read-only (?fromSeq= starts at the seq of a peer part, the line "Sent a message to …", "Message from …" or "Done for …" in a reply; nextCursor pages back, nextFromSeq forward). A message from a thread can be quoted back into a chat as a peer_message ref. With an API key all six answer 404. In a Work, agentId is the agent doing it and frontAgentId the agent whose chat started it; when they are the same the agent took it on itself (and threadId is null); status is submitted, working, input-required with waitingOn, completed, failed or canceled; while it is working, line is its latest step in plain words; outcome is dropped when it found the work wasn't needed (result says why); attempt goes up by one each time it is reopened.
  • Trash: deleting a document, a knowledge base or a library item (DELETE /docs/{id}, DELETE /spaces/{id}, DELETE /library/{id}) moves it to the trash, where it stays for 30 days before it is deleted for good. GET /trash?area=knowledge lists deleted documents and knowledge bases (documents deleted together with their knowledge base are not listed on their own; a knowledge base carries docCount), area=library lists deleted library items; each one has deletedAt and purgeAt. POST /trash/{id}/restore brings it back (a document whose knowledge base is in the trash too goes to your default one; the spaceId returned is where it is now; unpublishedPages counts restored documents whose published page is not public again because another page of the same site took its address while they were in the trash), and returns 404 TRASH_ITEM_NOT_FOUND when nothing with that ID is in your trash. DELETE /trash/{id} deletes it for good at once (signed in only). Anything in the trash acts as if it didn't exist on every other endpoint.
  • Agent marketplace: GET /agent-templates lists the ready-made agents Waper made (each with id, name, its look, category, the one line on its card pitch, blurb, duty, opening examples and the apps it works best with). You can call it without a key; with one, added and agentId tell you which ones you already have. Texts come in lang, or in your interface language when you leave it out (in the language of Accept-Language without a key).
  • Adding, changing and deleting agents (signed in only): POST /agents with { "kind": "guided", "name"?, "avatar"? } (what Create an agent in the apps does: with name the agent keeps that name, without it the agent starts with a placeholder and names itself later; it has settingUp: true, asks in its own chat what it should look after and then writes down its duties), { "kind": "template", "template": "<an id from GET /agent-templates>" }, or { "kind": "custom", "name", "blurb", "duty", "avatar"? }, returns 201 and the agent. avatar is { "shape", "face", "color" }, all three required (the values are in AgentAvatar in the API reference); leave it out and a look you haven't used yet is picked; a look exactly like the main agent's default look is 400 INVALID_AVATAR. At the limit 409 AGENT_LIMIT, a template already added 409 TEMPLATE_EXISTS (with the existing one's agentId), a name already used 409 NAME_TAKEN. POST /agents/draft with { "text" } (one sentence, 1 to 500 characters) drafts { name, blurb, duty } at no credit cost; too often 429 RATE_LIMITED, model briefly unavailable 503 MODEL_UNAVAILABLE. PATCH /agents/{id} changes name, blurb, duty, avatar and notify (whether what it tells you is pushed; Mute in the apps turns it off); when you change duty without blurb, the blurb is rewritten from the new duty shortly after (and sent to the apps in an agent frame); every agent takes name, avatar and notify, while the blurb and duty of your main agent can't be changed (409 AGENT_FIXED); giving an agent you added the main agent's default look is 400 INVALID_AVATAR. DELETE /agents/{id} returns 204 and deletes its chat and routines with it; your main agent answers 409 AGENT_PERMANENT.
  • Group chats (signed in only): POST /conversations/messages without a conversationId and with newGroup: { "agentIds": [...] } (1 to 6, in the order you picked them) starts a group and says the first message; the conversationId you get back is the group. With an API key, newGroup returns 400 INVALID_GROUP. In a group, toAll: true is @Everyone; to @ a member, put { "kind": "agent", "id": "<agent ID>" } in refs. A group's Conversation carries memberAgentIds (in the order they joined), agentId: null, title (empty means the apps show the members' names) and spaceId; a one-to-one chat has its agent in agentId, and the main agent's chat has main: true. A user's message in a group that names nobody gets dispatch: { agentIds }: the members picked to answer, in order (empty means nobody answers; null until it is decided). PATCH /conversations/{id} also takes title and spaceId (empty for no knowledge base) for a group: on a chat that isn't a group it is 409 NOT_A_GROUP. POST /conversations/{id}/members with { "agentId" } adds a member (full: 409 GROUP_FULL), DELETE /conversations/{id}/members/{agentId} removes one (not a member: 409 NOT_A_MEMBER); both return the group. POST /conversations with { "agentIds": [...], "title"?, "spaceId"? } creates a group with no messages yet (201 with the group). DELETE /conversations/{id} deletes a group and returns 204; a chat with one agent can't be deleted (409 CONVERSATION_PERMANENT).
  • Routines belong to an agent: POST /routines and PATCH /routines/{id} take an optional agentId (the main agent when you leave it out) deliverTo (the ID of a group chat that agent is in; empty for its own chat) and doneWhen (what counts as done: once a run finds it met, the routine stops for good with pausedReason finished; empty for no end of its own). A routine whose state is proposed was suggested by the agent and does nothing until you POST /routines/{id}/start (signed in only; starting it is your approval, one that is already on is returned as it is, a paused one answers 409 NOT_PROPOSED, resume it instead); to turn it down, DELETE it. Pausing, resuming or test-running a proposal answers 409 ROUTINE_PROPOSED.
  • Where a watch posts: deliverTo in PATCH /watches/{slug}/settings is the ID of a group chat the main agent is in, empty for the main agent's own chat; each follower sets their own. If the main agent isn't in that chat, it is 404 CONVERSATION_NOT_FOUND.
  • Changing a watch you created: PATCH /watches/{slug} changes scope (one sentence on how the scope should change), title (the slug stays), visibility and urls (add / remove, only for source and page-changes watches). A scope or address change returns a taskId: the scope is rewritten in the background, a topic watch finds sources again, and a brief is written right away; follow it with GET /tasks/{taskId}. Credits are held by quote and charged by actual use. Only the owner can change it (403 NOT_OWNER; official watches can't be changed); making it private needs a paid plan (403 PRIVATE_NOT_ALLOWED) and removes other people's follows and email subscriptions; 409 WATCH_UPDATING while the last change is still running; a scope or address change counts as a paid action, so past one key's per-minute limit it is 429 RATE_LIMITED; 400 NOTHING_TO_CHANGE when nothing differs.
  • Approvals (signed in only): POST /actions/{id}/decide with approve, plus alwaysAllow: true for "Always allow" (it records a rule for the action's alwaysAllowScope; on a send card it adds the recipients as trusted recipients; payments and sends to someone you never mentioned after outside content have none, so it is ignored), approving a send card can carry edits (keys are the keys in the action's editable, values the full new text; recipients and the sending account can't change, a wrong key is 400 ACTION_EDIT_INVALID), and POST /actions/decide decides the actions on one card together (edits per action id); GET /rules, POST /rules (with an actionId; the rule covers that action's alwaysAllowScope) and DELETE /rules/{id} list, add and remove "always allow" rules; GET, POST and DELETE /trusted-recipients manage trusted recipients (an email address, an @domain or a #channel, up to 200; at the limit 409 TRUSTED_RECIPIENT_LIMIT; each has confirmed, and false marks one added before sends to them went out directly, which still asks once before the first direct send); GET /actions/reviewed?verdict=allow and ?verdict=block list the actions the auto-review recently allowed or blocked (each with its review: the verdict and the reason shown to you); POST /actions/{id}/retry approves a blocked action and runs it once, without recording a rule (blocked more than 7 days ago: 409 ACTION_NOT_BLOCKED).
  • Model catalogue: GET /models lists Waper's Lite, Pro and Max tiers first in models (kind: "tier", IDs lite, pro, max, maker is null; their underlying models are not revealed), then the specific models you can pick directly (kind: "model", with maker). Names and descriptions are in your interface language, and thinkingLevels and keyProviders are empty. Each item has relativeCost (roughly how many times a Max turn one turn costs; Max is 1) and available (whether you can choose it now; choosing one you can't returns 402). platformDefault is the tier used when you have not chosen (Lite on Free, Pro for members); when your choice is no longer available it is kept while downgradeTo is used. keyModels separately lists actual models for your own keys, with their thinkingLevels and keyProviders; customModels lists models on your own services. The response also includes your connected keys. keysAvailable is false when this server cannot use your own keys (/model-keys then returns 404).
  • Choosing an agent's model: PATCH /agents/{id} with model, thinking and modelKeyProvider (signed in only) changes that agent's model, used in its chat, its group turns and its background work; the current choice is the agent's model. For Waper's models, send a tier ID (lite, pro, max) or a specific model's ID and omit modelKeyProvider. Platform thinking is always stored and returned as null; sending a thinking value does not configure the platform tier. For your own model, send its catalogue model ID and the matching modelKeyProvider, optionally with a supported thinking level. Choosing one your plan doesn't include returns 402 MODEL_NOT_IN_PLAN. With your own key, an unsupported provider, a missing key or an invalid key returns 409 MODEL_NOT_VIA_KEY, MODEL_KEY_MISSING or MODEL_KEY_INVALID.
  • Your own keys (signed in only): GET /model-keys returns only the provider, the last four characters and the status, never the key; PUT /model-keys/{provider} checks the key with the provider first and returns 422 MODEL_KEY_REJECTED when it fails (reason is invalid, no_credit or unreachable), with at most 10 checks an hour; DELETE /model-keys/{provider} deletes it at once; agents using it return to the plan's default Waper tier, clearing the old thinking preference. When a turn stops because your key can't be used, turn.error and the line in the chat carry MODEL_KEY_INVALID (the key is wrong), MODEL_KEY_QUOTA (out of credit or rate limited), MODEL_KEY_REFUSED (the provider refused this one request, for example flagging the input; the key still works) or MODEL_KEY_UNREACHABLE (the provider can't be reached), with the provider. GET /usage/history is your credit history grouped by day (page with cursor); rows that used your key have ownKey.
  • OpenAI-compatible services you added (signed in only): GET /model-services lists them with their models (only the last four characters of a key); POST /model-services adds one and PUT /model-services/{id} replaces one whole (leave key out to keep it, send an empty string to remove it), both checked first and returning 422 MODEL_KEY_REJECTED when the check fails (reason can also be model_missing, the service doesn't have the model, or unsupported, it refused a request with a tool so the model may not support tool calling, both with the model), 400 MODEL_SERVICE_URL_INVALID for an address that can't be used and 409 MODEL_SERVICES_LIMIT at 10 services; DELETE /model-services/{id} deletes one at once. Deleting a service or removing one of its models returns agents using it to the plan's default Waper tier, clearing the old thinking preference. customModels in GET /models lists the models on them (status is invalid when the service refused its key, and then it can't be chosen); choose one with model set to its id and modelKeyProvider set to custom. When such a turn stops, turn.error has no provider. The rules are in Models and your own key.

In an agent's reply, what each model call thought is a thinking part (text is the whole of it, an empty string when the model gave nothing displayable and only durationMs is set; durationMs is how long it took, null when not measured), placed before what that call said and the steps it took; clients that only want the final reply can skip it. Each step is a tool part: label is a progress line built from the tool and its arguments, and activity is the line the agent wrote itself (what it is doing and why, in your language; absent when it wrote none). Show activity when it is there. On the realtime channel the thinking streams first as thinking frames (they share cursor and step with delta; a delta with reset also drops the thinking received for that step).

The apps follow chats over a realtime channel. Its frames for background work: work (a piece of work was started or changed, carrying the whole Work), turn.start with a workId (a turn working on a piece of work: it leaves no reply and ends with turn.closed, which carries the workId too, as does the ready snapshot on reconnect), agent (an agent was created, or its name, duties, one line, figure or mute setting changed, or it finished setting itself up). The progress card in a reply is a work part ({ type: "work", work }). When you reply to a progress card, send its workId with turn.send (REST POST /conversations/messages takes workId as well): work still going gets the message directly, and work that has ended goes to the agent with a note of which one it was. From the app, turn.cancel stops the turn in progress and every unfinished piece of work in that chat; standalone background jobs (/tasks) and routines aren't affected.

Messages sent while a turn is busy are queued behind it. POST /conversations/messages still returns 202, with turnStarted.messageId set to null and a queueId. The input appears in queued from GET /conversations/{id}/messages until the next turn consumes it; only then does it receive a real message seq. The live channel uses conversation.queue (full snapshot) and conversation.queue.item (added, removed, or consumed) for updates. Retract with the client conversation.queue.retract frame: a successful retract produces removed; if consumption won the race, the result is consumed and clients should tell the user that the message was already sent. Supported versions include parts, context, replyTo, and skill on queue items so a retracted input can restore its complete composer state; older clients can use id, text, and createdAt.

Frames for added agents and group chats: turn.send can carry newGroup and toAll (the new group's ID comes back as conversationId in turn.ack); agent.deleted (an agent was deleted: drop it from the roster and the @ menu); conversation (members, name or linked knowledge base changed); dispatch (who was picked to answer a message that named nobody); peer (a new message in a thread between two agents); conversation.delete from the app also deletes a group; conversation.deleted (a group was deleted, or the chat of an agent you added when that agent was deleted).

Frames for notifications (both sent by the app): presence (whether this client is in the foreground: send it on every change and again from time to time while it is; while any client of the account is in the foreground, nothing pops up in the browser, on the phone or in the desktop app, only the numbers change); conversation.seen (the latest message seen in a chat: a message already seen isn't pushed to your devices; opening a chat doesn't count as seeing it). Ignore frames you don't recognize.

Image generation and editing

Image generation and editing accept optional aspectRatio (1:1, 3:2, 2:3, 16:9, 9:16) and quality (standard, high). Generation defaults to square; editing defaults to the closest supported ratio to the original. Quality defaults to standard; use high when you explicitly need high quality. Quality is a preference: fallback services may use their default quality, at the same per-image price. Resolution uses the service default.

Examples

# Watches you follow
curl -H "Authorization: Bearer wpr_xxx" \
  https://waper.ai/api/v1/watches

# Save a web page to the library
curl -X POST https://waper.ai/api/v1/library \
  -H "Authorization: Bearer wpr_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

# Ask your agent; read the reply from the conversation once the turn ends
curl -X POST https://waper.ai/api/v1/conversations/messages \
  -H "Authorization: Bearer wpr_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"What changed in my AI watches this week?"}'

Limits & billing

  • 60 requests per minute per account (shared with MCP); beyond that you get 429 RATE_LIMITED with a Retry-After header in seconds.
  • Actions that spend credits and are started with an API key (transcribing new audio or video, deep research): at most 10 a minute per key; beyond that you also get 429 RATE_LIMITED with Retry-After, and can send it again once the minute is over. You get the same 429 when Waper cannot check the key's usage for a moment (the message says it could not be checked, not that the limit was reached); try again shortly. There is no daily cap: as long as you have credits you can keep going.
  • Reading is free. Messages to your agent use credits based on actual model usage and the selected model; summaries of saved pages and files settle at actual usage; audio and video are charged per minute (ask POST /media/quote first); making and editing images (POST /images/generations, POST /images/edits) is charged per image, only when an image is made: GET /paid-capabilities shows your price right now, a maxCredits below the price returns 402 PRICE_ABOVE_MAX and does nothing, and the daily limit on images returns 429 PAID_LIMIT. Insufficient credits return 402 CREDITS_EXHAUSTED. Before a message starts a new turn, Waper checks the minimum reservation. A refusal includes top-level integer remaining and needed fields, and writes no message or turn. Your own model key, tiers that charge no credits, and messages queued behind an active turn are exempt from this send-time check; queued messages are checked when their turn comes. See Plans & credits.