REST API
Authenticate, paginate, and handle errors on the Planeward public API.
The Planeward public API is workspace-scoped. A key authenticates every request and binds it to one workspace — paths do not include workspaceId.
Base URL
The base URL for all API endpoints is:
https://app.planeward.com/api/v1Pagination
List endpoints accept limit (default 50, max 100) and offset. Responses use:
{
"data": [],
"meta": {
"total": 0,
"limit": 50,
"offset": 0
}
}Errors
| Status | Meaning |
|---|---|
400 | Invalid JSON, a body that fails validation, or a broken rule |
401 | Missing or invalid API key |
403 | Key lacks the required scope; missingScope names it |
404 | Unknown resource, wrong workspace, or a required module is off |
409 | Conflicts with the current state (stale version, WIP limit) |
429 | Rate limited (about 60 requests per key per minute) |
Task writes follow the same rules as the app. Moving a task to a Done status sets completedAt and schedules auto-archive; an archived task then returns 404. A move into a status at its blocking WIP limit returns 409. PATCH /tasks/{taskId} takes an optional expectedVersion (the task's version): when someone else changed the task first, it returns 409 Task was modified by someone else. Refresh and retry. Omit it and the last write wins. Titles allow up to 500 characters.
A missing scope returns { "error": "Insufficient API key permissions", "missingScope": "EVENTS_READ" }, and shows in the key's Usage tab.
Developer, CRM, and Chats can be disabled in workspace settings. When Developer is off, every /api/v1 and POST /api/mcp/{workspaceId} call returns 404 even if the key is valid.
The same key and scopes also power the MCP server. Task descriptions use a stored Plate JSON document, not markdown.
Modules
WRITE scopes imply the matching READ check. Keys are workspace-wide for their scopes and do not use member project or channel ACLs.
The /community/* routes need the Community app. Products and plans (CATALOG_READ and CATALOG_WRITE) are available through MCP only. They need the Commerce app and work with Community off. POST /purchases records a sale whether or not you run a community.
Sites
Sites routes need SITES_READ or SITES_WRITE, the Sites app on, and a plan with Sites. Product docs: Sites.
| Method | Path | Purpose |
|---|---|---|
GET / POST | /sites | List (search, limit, offset) or create a site |
GET / PATCH / DELETE | /sites/{siteId} | Get, patch (name, slug, language, theme), or trash |
POST | /sites/{siteId}/publish | Publish drafts, collections, and Published items with staged changes; returns the new version |
POST | /sites/{siteId}/unpublish | Take the site offline |
GET / POST | /sites/{siteId}/pages | List pages (kind, default PAGE) or create a regular page |
GET / PATCH / DELETE | /sites/{siteId}/pages/{pageId} | Get, patch (title, slug, hidden, hideHeader, hideFooter, seo, body, expectedContentVersion), or delete |
GET / POST | /sites/{siteId}/collections | List or create collections. Create also makes the TEMPLATE page |
GET / PATCH / DELETE | /sites/{siteId}/collections/{collectionId} | Get, patch (name, slug, fields, jsonLd), or delete a collection |
GET / POST | /sites/{siteId}/collections/{collectionId}/items | List (search, status, limit, offset) or create an item (slug, data, seo, status, publish) |
GET / PATCH / DELETE | /sites/{siteId}/collections/{collectionId}/items/{itemId} | Get, patch (slug, data, seo, status, expectedContentVersion, publish), or delete an item |
POST | /sites/{siteId}/collections/{collectionId}/publish | Publish itemIds now |
POST | /sites/{siteId}/collections/{collectionId}/unpublish | Take itemIds off the live site |
POST | /sites/{siteId}/collections/{collectionId}/archive | Archive itemIds (hides and unpublishes) |
POST | /sites/{siteId}/collections/{collectionId}/upsert | Create or update rows by slug (up to 20,000). Above 200 rows returns { kind: "job", jobId } |
Page seo takes schemaType (WebPage, Article, AboutPage, ContactPage, CollectionPage) and optional publishedAt for articles. Collection fields include type list (1–8 sub-fields, up to 50 rows). Bulk bodies take { "itemIds": [...] } (1–500). Poll an upsert job with GET /jobs/{jobId}. Item PATCH without expectedContentVersion overwrites the current draft; with a stale one it fails with an error telling you the current version. Field errors return 400 with the failing path, such as data.price.
The header and footer, domains, tracking, crawl settings, and funnels are available through MCP only.
To credit a sale on your own domain to a site visit, send siteVisit on POST /purchases. See Linked domains.
Planeward Docs