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.
| Scope | Allows |
|---|---|
COMMUNITY_MEMBERS_READ | List and read community members, with their badges |
COMMUNITY_MESSAGES_READ | List channels and read message history in channels @everyone can view |
COMMUNITY_MESSAGES_WRITE | List channels and post messages in them as the app |
COURSES_READ | Read published course outlines and members' course progress |
COURSE_PROGRESS_WRITE | Complete or uncomplete a module for a member. Also allows COURSES_READ calls |
EVENTS_READ | List and read events shown in community apps |
EVENT_REGISTRATIONS_WRITE | Register a member, cancel a registration and set attendance |
FORMS_SUBMIT | List forms shown in community apps and submit them as a member |
COMMUNITY_BADGES_WRITE | Create, edit and delete the app's badges, and award and revoke them |
COMMUNITY_NOTIFICATIONS_WRITE | Send 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:
| Token | Means |
|---|---|
@[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. |
@everyone | Everyone 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.
404Channel not found.— the channel doesn't exist, or@everyonecan't view it.403This app can't post in that channel.—@everyonecan 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"
}| Field | Rules |
|---|---|
memberIds | 1–100 community membership ids, each 1–128 characters. Duplicates are removed. |
body | 1–280 characters of plain text, trimmed. It is not Markdown or HTML, and members see it as typed. No null characters. |
href | Where a click goes, as a path inside your app. See below. |
key | Optional. 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:
| Reason | Meaning |
|---|---|
member_not_found | Not 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_active | The member can't open the community right now: suspended, revoked, or their plan has lapsed. |
channel_not_visible | The 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_limit | The 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_limituntil 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
keyis spent, so a retry with the same key inside 24 hours reportsacceptedand 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.skippedTo 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.
}
}| Status | Meaning |
|---|---|
400 | Invalid 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 |
401 | Bad or revoked secret, or the installation was uninstalled |
403 | Missing 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 |
404 | Member, 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 |
409 | Member is not active., Member has no primary contact., or the app already has 50 badges |
429 | Over 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.
Planeward Docs