PlanewardPlaneward Docs
PlanewardPlaneward Docs
Welcome

Developers

REST APIAuthenticationWebhooksMCPEmbedded projectsTask description contentDeveloper hub
Community appsQuickstartIdentity tokenAPI accessApp webhooksTesting your apppostMessage protocol

API

Community apps

API access

Call Planeward from your app's backend with the app secret.

Credentials

The app secret starts with pwa_. It is shown once when you create the app; rotate it in Settings › Apps › Developer. Keep it on your server.

Each request names the installation it acts for. Take installationId from the identity token or the app.installed webhook.

GET /api/v1/community/members
Host: app.planeward.com
Authorization: Bearer pwa_...
x-planeward-installation: <installationId>

x-api-key: pwa_... works in place of Authorization.

Scopes

The app requests scopes in Settings › Apps › Developer. The installer approves them when installing the app and can untick any of them.

ScopeAllows
COMMUNITY_MEMBERS_READList and read community members, with their badges
COMMUNITY_MESSAGES_READList channels and read message history in channels @everyone can view
COMMUNITY_MESSAGES_WRITEList channels and post messages in them as the app
COURSES_READRead published course outlines and members' course progress
COURSE_PROGRESS_WRITEComplete or uncomplete a module for a member. Also allows COURSES_READ calls
EVENTS_READList and read events shown in community apps
EVENT_REGISTRATIONS_WRITERegister a member, cancel a registration and set attendance
FORMS_SUBMITList forms shown in community apps and submit them as a member
COMMUNITY_BADGES_WRITECreate, edit and delete the app's badges, and award and revoke them
COMMUNITY_NOTIFICATIONS_WRITESend in-app and push notifications to members

COMMUNITY_MESSAGES_WRITE does not allow reading message history. Apps can only hold these scopes: workspace scopes such as CONTACTS_WRITE or FORMS_WRITE are never granted to an app.

When you add a scope to an app that is already installed, the workspace approves it on Community › Apps without reinstalling. Until then calls that need it return 403. See Approve new permissions.

Endpoints that act for a member take memberId, the member's community membership id. It is the id in member payloads and the token's sub when role is member. Writes need the member to be ACTIVE; a suspended or revoked member returns 409 Member is not active..

Event registration and form submission need the member's CRM contact. A member whose customer has no primary contact gets one: the customer's contact with the customer's own email (compared case-insensitively), or else a new contact made from the customer record. Another contact of the customer is never made primary, and the customer record itself is not changed. A customer with no email but other contacts returns 409 Member has no primary contact.; the workspace sets the customer's email or primary contact in the CRM.

Client

import { createPlanewardClient } from "@planeward/sdk/server";

const pw = createPlanewardClient({
  secret: process.env.PLANEWARD_APP_SECRET!,
  installationId,
});

baseUrl is optional. Failed requests throw PlanewardApiError with the HTTP status, the API's error message and, for a missing scope, missingScope. Paths below are under /api/v1.

Members

List members

GET /community/members?limit&offset&search — COMMUNITY_MEMBERS_READ

search matches only names the response shows: username and displayName. A customer or contact name is searched only when it is what displayName shows, and email addresses are never matched.

{
  "data": [
    {
      "id": "cm_123",
      "customerId": "cus_123",
      "username": "ada",
      "displayName": "Ada Lovelace",
      "avatarUrl": null,
      "status": "ACTIVE",
      "accessPlans": [{ "id": "plan_1", "name": "Pro" }],
      "roles": [{ "id": "role_1", "name": "Moderator" }],
      "badges": [
        {
          "id": "bdg_1",
          "appId": "app_1",
          "key": "first-post",
          "name": "First post",
          "description": "",
          "color": "#f59e0b",
          "iconUrl": null,
          "awardedAt": "2026-11-01T00:00:00.000Z"
        }
      ],
      "joinedAt": "2026-08-25T00:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}

status is ACTIVE, SUSPENDED or REVOKED.

badges lists badges from every app installed in the workspace, newest award first. Badges of uninstalled apps are left out.

avatarUrl is a signed storage URL that stays valid for up to about 1 hour, or null when the member has no avatar. Don't store it. Fetch or copy the image when you need it, and call the API again for a fresh URL.

await pw.community.members.list({ limit: 50, offset: 0, search: "ada" });

Get a member

GET /community/members/{memberId} — COMMUNITY_MEMBERS_READ. Returns { "data": <member> } with the same shape.

await pw.community.members.get(memberId);

Channels and messages

An app sees channels with the rights of the @everyone role, after category and channel overwrites. Staff roles never apply. A channel @everyone can't view returns 404 Channel not found., the same as a missing one.

List channels

GET /community/channels — COMMUNITY_MESSAGES_READ or COMMUNITY_MESSAGES_WRITE

Text and app channels @everyone can view, in sidebar order. App channels are listed only while their app is installed and available.

{
  "data": [
    {
      "id": "ch_123",
      "name": "general",
      "slug": "general",
      "description": "",
      "kind": "TEXT",
      "categoryId": null,
      "position": 0
    }
  ]
}
const { data: channels } = await pw.community.channels.list();

List messages

GET /community/channels/{channelId}/messages?limit&cursor — COMMUNITY_MESSAGES_READ

Newest first, with reaction counts. Deleted messages are left out. limit is 1–100 (default 50). Pass meta.nextCursor as cursor until it is null.

{
  "data": [
    {
      "id": "msg_456",
      "channelId": "ch_123",
      "body": "Hello everyone",
      "replyToId": null,
      "createdAt": "2026-08-25T00:00:00.000Z",
      "editedAt": null,
      "author": {
        "kind": "member",
        "memberId": "cm_123",
        "installationId": null,
        "name": "Ada Lovelace"
      },
      "reactions": [{ "emoji": "🎉", "count": 3 }]
    }
  ],
  "meta": {
    "nextCursor": "WyIyMDI2LTA4LTI1VDAwOjAwOjAwLjAwMFoiLCJtc2dfNDU2Il0"
  }
}

author.kind is member, staff or app. memberId is set for members; installationId is set for apps. Staff are identified by name only.

body can contain mention tokens, stored as written and not resolved for you:

TokenMeans
@[id]A person. For a member id is their memberId; look the name up with Get a member. It can also be a staff member's id, which the API can't look up.
#[id]A channel, by channel id. Match it against List channels.
@everyoneEveryone in the community. Written as literal text.

Tokens inside code, or escaped with a backslash, are plain text. Replace tokens before you show a body to people or pass it to a model.

let cursor: string | undefined;
do {
  const page = await pw.community.messages.list(channelId, { cursor });
  // page.data
  cursor = page.meta.nextCursor ?? undefined;
} while (cursor);

Post a message

POST /community/channels/{channelId}/messages — COMMUNITY_MESSAGES_WRITE

{ "body": "Hello from the app", "replyToId": "msg_123" }

body is 1–4000 characters of Markdown, with block quotes and lists nested at most 16 levels deep (deeper bodies return 400 Message is nested too deeply.). replyToId is optional.

An app can post only in a text channel where @everyone can both view the channel and send messages.

  • 404 Channel not found. — the channel doesn't exist, or @everyone can't view it.
  • 403 This app can't post in that channel. — @everyone can view the channel but can't send messages, for example an announcements channel.

To mention a member, write @[memberId] in body. They get a notification like any other mention. Each person mentioned counts against the same hourly allowance as your notifications, once per message, and a person already over it isn't notified (the message still posts). A member who switched your app's In-app or Push notifications off doesn't get that kind for your mentions either. A literal @everyone in an app's message never notifies anyone. To reach a member without posting in a channel, use Notifications.

Returns 201:

{
  "data": {
    "id": "msg_456",
    "channelId": "ch_123",
    "body": "Hello from the app",
    "replyToId": "msg_123",
    "createdAt": "2026-08-25T00:00:00.000Z",
    "author": { "kind": "app", "installationId": "inst_123", "name": "My app" }
  }
}
await pw.community.messages.create(channelId, { body: "Hello from the app" });

Courses and progress

List courses

GET /community/courses?limit&offset — COURSES_READ

Published courses that are sold through at least one product, in sidebar order. Drafts are never listed. chapterCount and moduleCount skip chapters without modules.

{
  "data": [
    {
      "id": "crs_1",
      "title": "Foundations",
      "description": "Start here.",
      "position": 0,
      "chapterCount": 3,
      "moduleCount": 12,
      "publishedAt": "2026-08-25T00:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "limit": 50, "offset": 0 }
}
await pw.community.courses.list({ limit: 50 });

Get a course

GET /community/courses/{courseId} — COURSES_READ

The summary plus chapters, each with its modules (id, title, description, durationSeconds, position). Outline only: no module bodies, videos or attachments.

const { data: course } = await pw.community.courses.get(courseId);

Member progress

GET /community/members/{memberId}/progress?courseId — COURSES_READ

One row per module the member has started or completed, in the courses List courses returns: published and sold through at least one product. Filter with courseId; any other course returns 404. Works for members in any status.

{
  "data": [
    {
      "memberId": "cm_123",
      "moduleId": "mod_1",
      "chapterId": "chp_1",
      "courseId": "crs_1",
      "completedAt": "2026-11-01T00:00:00.000Z",
      "videoPositionSeconds": 0
    }
  ]
}
await pw.community.members.progress.list(memberId, { courseId });

Complete or uncomplete a module

PUT / DELETE /community/members/{memberId}/progress/{moduleId} — COURSE_PROGRESS_WRITE

PUT marks the module complete; DELETE clears completedAt. Both return the progress row and are safe to repeat. Any module of a course members can see works, whatever the member's plan unlocks; other modules return 404. A new completion sends community.module.completed, and community.course.completed when it finishes the course. community.course.completed goes out at most once per member and course: clearing and completing the last module again does not resend it.

await pw.community.members.progress.complete(memberId, moduleId);
await pw.community.members.progress.uncomplete(memberId, moduleId);

Events

Apps only see events that staff turned on with Show in community apps in the event's settings. Any other event returns 404 Event not shown in community.. Events need the workspace's CRM module.

List and get events

GET /events?limit&offset and GET /events/{eventId} — EVENTS_READ

Newest first, with a registration count. get also returns counts by attendance. Apps never get the CRM pipeline (pipeline, pipelineId). formId and form are set only when the event's form is published and shown in community apps, so you can submit it; otherwise they are null.

productIds lists the products that sell seats at the event (Sold by on the event). A completed payment for any plan of one of them registers the buyer. See Paid events. Apps can read productIds but not change them; workspace API keys and MCP set them on event create and update. Setting productIds also needs the catalog write scope.

const { data: events } = await pw.events.list({ limit: 20 });
const { data: event } = await pw.events.get(eventId);

Register and cancel

POST /events/{eventId}/registrations and DELETE /events/{eventId}/registrations?memberId= — EVENT_REGISTRATIONS_WRITE

Send { "memberId": "cm_123" }. Apps must use memberId; contactId is for workspace API keys and returns 400 from an app.

Registering is safe to repeat: a new registration returns 201 with created: true, an existing one 200 with created: false. A member without a CRM contact gets one (see Scopes). Responses to apps leave out the contact's name and email, the CRM deal and the payment that bought the seat (contact, opportunityId, paymentId).

A member who buys a product linked to the event is registered without a call from your app, and a refund that ends their plan cancels that seat and sends event.registration_cancelled.

Cancelling returns { eventId, contactId, cancelled }. cancelled is false when the member wasn't registered. It sends event.registration_cancelled.

const { data } = await pw.events.registrations.create(eventId, { memberId });
// data.created, data.registration
await pw.events.registrations.cancel(eventId, { memberId });

Set attendance

PUT /events/{eventId}/attendance — EVENT_REGISTRATIONS_WRITE

{ "memberId": "cm_123", "attendance": "ATTENDED" }

attendance is PENDING, ATTENDED, LEFT_EARLY, NO_SHOW or UNCLASSIFIED. joinedAt and leftAt are optional ISO timestamps. The member must already be registered. A change sends event.attendance_classified.

await pw.events.attendance.set(eventId, { memberId, attendance: "ATTENDED" });

Forms

Apps only see published forms that staff turned on with Show in community apps in the form's settings. Forms need the workspace's CRM module.

List forms

GET /forms?limit&offset&search — FORMS_SUBMIT

Each form includes its fields definition and submissionCount. settings holds only what rendering needs: respondent (confirmation message, submit label, disableAfterSubmit), theme and css. CRM routing, embed origins and the public-link switch are not sent to apps.

const { data: forms } = await pw.forms.list({ search: "feedback" });

Submit as a member

POST /forms/{formId}/submissions — FORMS_SUBMIT

{ "memberId": "cm_123", "fields": { "q_rating": 5, "q_comment": "Great call" } }

fields are answers keyed by field id, checked against the form like a public submission. Invalid answers return 400. The submission runs the form's normal side effects: form.submitted, workflows, and event registration for a linked event. A member without a CRM contact gets one (see Scopes). Returns 201 with the submission.

An app can't consent for a member. Every answer is stored on the submission, but marketing consent, guardian consent and the guardian email are not set on the member's contact.

await pw.forms.submissions.create(formId, {
  memberId,
  fields: { q_rating: 5 },
});

Badges

An app defines its own badges and awards them to members. Members see them on their profile, in the member list and next to their name in chat.

Badges belong to the app in each workspace, not to one installation. Uninstalling hides them everywhere, and reinstalling brings them back with their awards. An app can have up to 50 badges per workspace.

Only apps can call badge endpoints. A workspace API key gets 403.

List badges

GET /community/badges — COMMUNITY_BADGES_WRITE. The app's badges in this workspace, oldest first.

Create or update by key

POST /community/badges — COMMUNITY_BADGES_WRITE

{
  "key": "first-post",
  "name": "First post",
  "description": "Posted for the first time",
  "color": "#f59e0b"
}

key is your stable id: lowercase letters, digits and hyphens, up to 48 characters. name is up to 40 characters, description up to 200, and color a hex color like #7c3aed. A new key returns 201; an existing key updates that badge and returns 200. A 51st badge returns 409.

const { data: badge } = await pw.community.badges.upsert({
  key: "first-post",
  name: "First post",
  color: "#f59e0b",
});

Edit and delete

PATCH /community/badges/{badgeId} takes any of name, description and color; key can't change. DELETE /community/badges/{badgeId} deletes the badge and every award of it, without sending community.badge.revoked. Both need COMMUNITY_BADGES_WRITE.

await pw.community.badges.update(badge.id, { color: "#16a34a" });
await pw.community.badges.delete(badge.id);

Award and revoke

PUT / DELETE /community/members/{memberId}/badges/{badgeId} — COMMUNITY_BADGES_WRITE

Both are safe to repeat. A new award sends community.badge.awarded and needs an ACTIVE member; an existing award keeps its awardedAt. Revoking works for members in any status and sends community.badge.revoked when an award was removed.

await pw.community.members.badges.award(memberId, badge.id);
await pw.community.members.badges.revoke(memberId, badge.id);

Notifications

An app can send a member a notification. It appears in the member's bell in the community and as a push notification on devices where they turned push on. It is never sent by email.

POST /community/notifications — COMMUNITY_NOTIFICATIONS_WRITE

Only apps can call this endpoint. A workspace API key gets 403, even one with every permission.

{
  "memberIds": ["cm_123", "cm_456"],
  "body": "Your order #123 has shipped.",
  "href": "/orders/123",
  "key": "order-123-shipped"
}
FieldRules
memberIds1–100 community membership ids, each 1–128 characters. Duplicates are removed.
body1–280 characters of plain text, trimmed. It is not Markdown or HTML, and members see it as typed. No null characters.
hrefWhere a click goes, as a path inside your app. See below.
keyOptional. 1–100 characters from letters, digits, ., _, : and -. Makes a retry safe. See Retries.

The title is always your app's name. Planeward sets it, so a title field is ignored, like any other field the endpoint doesn't know.

href is a path inside your app, for example /orders/123?tab=items. It must start with a single /, be at most 512 characters, and contain no . or .. segments (written plainly or as %2e) and no #. Anything else returns 400. When a member clicks the notification, the community opens your app's channel with your app loaded at this path. See Deep links.

Response

Always 200 once the request is valid, even when every member is skipped. Both lists keep the order of the request.

{
  "data": {
    "accepted": ["cm_123"],
    "skipped": [{ "memberId": "cm_456", "reason": "over_limit" }]
  }
}

Each member is checked in this order, and gets the first reason that applies:

ReasonMeaning
member_not_foundNot a community membership in this workspace. Staff ids, ids from other workspaces and unknown ids all land here: you can't notify staff.
member_not_activeThe member can't open the community right now: suspended, revoked, or their plan has lapsed.
channel_not_visibleThe app has no channel that @everyone can view, so there is nothing for the notification to open. Staff add the app as a channel members can see.
over_limitThe member already got 10 from your app this hour, counting mentions in your messages and badges you awarded. See below.

A member who passes all four is accepted.

Limits

  • 10 notifications per member per app per hour. The hour is a fixed window that opens with the member's first notification or mention from your app; it is not a rolling hour. The 11th inside it is over_limit until the window ends. Mentions of the member in messages your app posts, and badges your app awards them, count toward the same 10. This is on top of the 60 requests a minute every call counts toward.
  • 100 members per request.

Retries

Send a key and a retry of the same notification is safe. The key holds for 24 hours from the first accepted send, per app and member. A repeat inside that time is listed in accepted, sends nothing and doesn't count toward the hourly limit. The key is checked before the limit, and a member skipped as over_limit does not keep it, so you can send it again later.

What "accepted" means

accepted means Planeward took the notification for delivery. It is not a delivery receipt.

  • Delivery happens just after the response. No notification ids are returned, and there is no way to look one up.
  • Members can switch your app's In-app and Push notifications off in their settings. Such a member is still listed in accepted, so you can't tell who muted you, and no call reveals it.
  • A community that isn't published yet accepts everything and shows nothing.
  • If Planeward can't deliver after it has answered, the notification is dropped and not retried. The key is spent, so a retry with the same key inside 24 hours reports accepted and sends nothing.
  • Push only reaches members who turned it on for a device and only where the workspace's administrator has set push up. The bell item is still there.
const { data } = await pw.community.notifications.send({
  memberIds: [memberId],
  body: "Your order #123 has shipped.",
  href: "/orders/123",
  key: "order-123-shipped",
});
// data.accepted, data.skipped

To try it without a real community, use the CLI emulator's Inbox tab. See Testing your app.

Errors

Errors return { "error": string }. A 403 for a scope the installation doesn't have also names it, always a scope an app can request (FORMS_SUBMIT for GET /forms, not FORMS_READ):

{
  "error": "Insufficient API key permissions",
  "missingScope": "EVENTS_READ"
}
import { PlanewardApiError } from "@planeward/sdk/server";

try {
  await pw.events.registrations.create(eventId, { memberId });
} catch (error) {
  if (error instanceof PlanewardApiError && error.missingScope) {
    // Ask the workspace to approve error.missingScope on Community › Apps.
  }
}
StatusMeaning
400Invalid JSON body., an invalid body or query (the message names the field, for example an href that isn't a safe relative path), or contactId sent by an app
401Bad or revoked secret, or the installation was uninstalled
403Missing scope (missingScope), @everyone can't send in the channel, a badge or notification call from an API key (Only community apps can send notifications.), the Community module is off, or a localhost app called from outside its own workspace
404Member, channel, course, module, event, form or badge not found, a channel @everyone can't view, an event or form not shown to apps, or a notification call in a workspace that has not set up a community
409Member is not active., Member has no primary contact., or the app already has 50 badges
429Over 60 requests a minute for the installation. Every authenticated call counts, including ones rejected with 403

See Testing your app to find failed calls in the Requests tab.

Identity token

The signed JWT that tells your app who is viewing.

App webhooks

Signed events sent to your app's webhook URL.

On this page

CredentialsScopesClientMembersList membersGet a memberChannels and messagesList channelsList messagesPost a messageCourses and progressList coursesGet a courseMember progressComplete or uncomplete a moduleEventsList and get eventsRegister and cancelSet attendanceFormsList formsSubmit as a memberBadgesList badgesCreate or update by keyEdit and deleteAward and revokeNotificationsResponseLimitsRetriesWhat "accepted" meansErrors