Reference

SDK REST v1 Reference

Use this reference to debug SDK traffic, build a native client surface, or verify the v1 contract behind sessions, announcements, notifications, preferences, and APNs tokens.

Base URL And Headers

Most apps should call the Gleam iOS 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>

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

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,
    "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"
}