Reference

SDK REST v1 Reference

Use this reference to debug SDK traffic, build custom native feedback and update surfaces, or verify the v1 contract behind sessions, feedback, announcements, notifications, preferences, and APNs tokens.

Last reviewed June 2, 2026

Base URL And Headers

Most iOS apps should call the Gleam SDK methods instead of hand-writing REST calls. This page is here for teams building custom native UI, reviewing network behavior, or troubleshooting request and response shapes with backend logs.

The hosted SDK API defaults to https://app.gleam.land. Client requests identify the project with the app ID and SDK key. Authenticated endpoints also require a Bearer token returned by bootstrap or signed identity exchange.

Header	Required	Value
X-Gleam-App-Id	GET endpoints	Project ID, project slug, or portal subdomain.
X-Gleam-SDK-Key	GET endpoints	Client-safe SDK initialization key.
Authorization	Authenticated endpoints	Bearer <sessionToken>

Authentication Model

The SDK REST v1 surface has two layers. Project identification uses client-safe values so the server can resolve the right Portal and allowed surfaces. User authentication uses a session token returned by bootstrap or signed identity exchange, and only authenticated endpoints should receive that bearer token.

Do not send service-role keys, dashboard secrets, APNs private keys, or identity signing secrets from an iOS or browser client. Those values belong in the Gleam dashboard or on your own backend.

Credential	Where it lives	Used for
Project ID or project slug	Client configuration	Identifies the Gleam project for bootstrap, announcements, and Portal URL resolution.
SDK initialization key	Client configuration	Client-safe key that validates the app is allowed to use the SDK surface for the project.
Session bearer token	SDK runtime session	Authorizes user-specific calls such as notification inbox, preferences, and APNs token registration.
Identity signing secret	Your backend only	Signs short-lived HS256 identity tokens before the client calls identify(...).
APNs private key	Gleam dashboard project settings	Lets the Gleam backend send Apple push notifications; it never belongs in the app bundle.

Endpoints

Method	Path	Auth	Purpose
POST	/sdk/v1/session/bootstrap	Optional Bearer token	Validate project access, create or refresh the SDK session, and resolve the Portal descriptor.
POST	/sdk/v1/session/identity	No Bearer token	Exchange a backend-signed identity token for a Gleam session.
GET	/sdk/v1/project/{projectPathId}/announcements	Optional Bearer token	List published announcements visible to the current SDK user.
GET	/sdk/v1/project/{projectPathId}/announcements/latest	Optional Bearer token	Read the latest visible announcement for an in-app update surface.
GET	/sdk/v1/project/{projectPathId}/feedback	Optional Bearer token	List public feedback posts, visible boards, counts, and viewer vote state for a native feedback UI.
POST	/sdk/v1/project/{projectPathId}/feedback	Bearer token	Create a feedback post from the current SDK session, including anonymous no-login sessions.
PUT	/sdk/v1/project/{projectPathId}/feedback/{postId}/vote	Bearer token	Set or clear the current SDK user's vote for a feedback post.
POST	/sdk/v1/project/{projectPathId}/feedback/{postId}/comments	Bearer token	Add a visible comment to a feedback post from the current SDK session.
GET	/sdk/v1/notifications?limit=&unreadOnly=	Bearer token	Poll the authenticated user's in-app notification inbox.
GET	/sdk/v1/preferences/notifications	Bearer token	Read iOS push notification preferences for the authenticated SDK user.
PUT	/sdk/v1/preferences/notifications	Bearer token	Update iOS push notification preferences.
POST	/sdk/v1/push/device-token	Bearer token	Register an APNs device token for the current project and user.
DELETE	/sdk/v1/push/device-token	Bearer token	Unregister an APNs device token, usually during sign-out or token replacement.
POST	/sdk/v1/push/test-notification	Bearer token	Queue a server-sent APNs test push for the authenticated SDK user.

Session Bootstrap

Bootstrap validates project access, creates or refreshes the SDK session, and returns the Portal descriptor that the client should use for Portal URLs.

Bootstrap request

curl -X POST https://app.gleam.land/sdk/v1/session/bootstrap \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "YOUR_PROJECT_ID",
    "publishableKey": "YOUR_GLEAM_SDK_KEY",
    "anonymousId": "device-or-install-id",
    "platform": "ios",
    "sdkVersion": "1.0.0"
  }'

Bootstrap response shape

{
  "sessionToken": "eyJ...",
  "portalAuthStorageRef": "supabase-project-ref",
  "session": {
    "accessToken": "eyJ...",
    "refreshToken": "refresh-token",
    "portalAuthStorageRef": "supabase-project-ref"
  },
  "portal": {
    "baseURL": "https://app.gleam.land",
    "projectPathId": "your-project",
    "routeMode": "path"
  },
  "capabilities": {
    "announcements": true,
    "customSignedIdentity": true,
    "feedback": true,
    "notifications": true,
    "notificationPreferences": true,
    "pushRegisterDevice": true,
    "authenticated": true
  }
}

Error Envelope

All SDK API errors return a stable code, human-readable message, and requestId. Include the requestId when reporting integration issues.

Error response

{
  "code": "invalid_sdk_key",
  "message": "Invalid SDK publishable key",
  "requestId": "req-or-uuid"
}