Skip to main content
The wondeya Developer API is a REST surface under /v1, authenticated by a workspace API key you create in the console. It lets you automate everything the product does (agents, projects, pages, knowledge, assets, brand, theme, usage) and talk to an agent directly: retrieval, and a headless generative turn. The endpoint pages in this tab are generated from wondeya’s OpenAPI document, so they describe exactly what the server accepts.

​
Base URL

Local development runs on http://localhost:8080/v1.

​
Authentication in one line

Every request carries a key as a bearer token:
A key is scoped to one workspace and to explicit permissions, and the workspace is the KEY’s: no request ever names a tenantId, so a key can only ever reach its own workspace. Create a key and see the full flow on the Authentication page.

​
The model

An agent is configured once and reused; a project is a site with a public address; a page lives inside a project and is either an agent page (the default, naming the agent that answers on it) or a document page (rendering a markdown body, no agent). Several pages may share one agent, which is why agents are workspace-level.

​
Conventions

Creation answers 201, state transitions answer 200. Publishing and unpublishing a page are their own endpoints (/publish, /unpublish), never a field on the settings patch. Updates are partial and merged. A PATCH carries only what changed. A theme patch carries only the tokens that changed, but a token outside the closed set is a 400, never an ignored field. Ingestion is asynchronous. POST /v1/knowledge/text and /urls answer 202 with the source pending; poll GET /v1/knowledge/sources until it is ready or failed. Code that assumes uploading is synchronous will read chunkCount: 0 and look broken. Lists are cursor-paginated. Every list answers { data, hasMore, nextCursor }; follow nextCursor as ?after=. See Pagination. Retries are safe when you ask. Send an Idempotency-Key on a create and a retry replays the first answer instead of creating a second resource or spending a second chat credit. See Idempotency. Signed URLs expire. Asset URLs are signed and short-lived (about 15 minutes). Ask for the list again rather than caching them.

​
Rate limits

Every /v1 request is rate-limited per key, and every response advertises the budget in both X-RateLimit-* and the IETF RateLimit headers. Over the limit is a 429 with Retry-After. See Rate limits.

​
Errors

Every error is an RFC 9457 problem document (application/problem+json) with a stable machine-readable code. Errors lists them and explains what to branch on.

​
Versioning

The surface is versioned in the path (/v1). Inside v1 changes are additive (new endpoints and new fields, never a removed or renamed one), and a breaking change ships as a new /v2. Anything on the way out is marked deprecated in these pages before it is removed. See Versioning.
The MCP server is a different surface for a different caller: it authenticates with OAuth 2.1 (a browser sign-in you approve), for AI clients like Claude. Machine API keys are for THIS REST API.