PlanewardPlaneward Docs
PlanewardPlaneward Docs
Welcome

Developers

REST APIAuthenticationWebhooksMCPEmbedded projectsTask description contentDeveloper hub

API

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/v1

Pagination

List endpoints accept limit (default 50, max 100) and offset. Responses use:

{
  "data": [],
  "meta": {
    "total": 0,
    "limit": 50,
    "offset": 0
  }
}

Errors

StatusMeaning
400Invalid JSON, a body that fails validation, or a broken rule
401Missing or invalid API key
403Key lacks the required scope; missingScope names it
404Unknown resource, wrong workspace, or a required module is off
409Conflicts with the current state (stale version, WIP limit)
429Rate 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.

MethodPathPurpose
GET / POST/sitesList (search, limit, offset) or create a site
GET / PATCH / DELETE/sites/{siteId}Get, patch (name, slug, language, theme), or trash
POST/sites/{siteId}/publishPublish drafts, collections, and Published items with staged changes; returns the new version
POST/sites/{siteId}/unpublishTake the site offline
GET / POST/sites/{siteId}/pagesList 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}/collectionsList 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}/itemsList (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}/publishPublish itemIds now
POST/sites/{siteId}/collections/{collectionId}/unpublishTake itemIds off the live site
POST/sites/{siteId}/collections/{collectionId}/archiveArchive itemIds (hides and unpublishes)
POST/sites/{siteId}/collections/{collectionId}/upsertCreate 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.

See also

  • Authentication
  • Developer hub
  • API reference

Roles and permissions

Create roles, turn permissions on, and assign them to people.

Authentication

API keys, headers, prefixes, and scopes.

On this page

Base URLPaginationErrorsModulesSitesSee also