Apps

SDK reference for apps — Read hosted apps and manage their audiences, conversations, and realtime grants.

Read hosted apps and manage their audiences, conversations, and realtime grants.

listAppsForMember

List every app the calling member can open, across all organizations they belong to

GET

Usage:

const result = await swirls.client.apps.listAppsForMember()

listApps

List apps declared by the project, one row per app name (snapshot from the pinned deployment, else the latest)

GET

Usage:

const result = await swirls.client.apps.listApps({
  projectId: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes

getApp

Resolve one app into the surface payload: brand, shell, nav, and pages with OpenUI source

GET

Usage:

const result = await swirls.client.apps.getApp({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes
`appName`	`string`	Yes

Output:

Field	Type	Description
`name`	`string`
`label`	`string`
`description`	`string \| null`
`icon`	`string \| null`
`deploymentId`	`string`
`brand`	`object \| null`
`shell`	`object \| null`
`nav`	`object \| null`
`pages`	`object[]`
`expose`	`object`

getAppLanding

Public marketing-safe landing payload for app-targeted Surface sign-in (no auth required)

GET

Usage:

const result = await swirls.client.apps.getAppLanding({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes
`appName`	`string`	Yes

Output:

Field	Type	Description
`projectId`	`string`
`appName`	`string`
`layout`	`"centered" \| "split" \| "cover"`
`title`	`string`
`subtitle`	`string \| null`
`logo`	`string \| null`
`icon`	`string \| null`
`image`	`string \| null`
`signInTitle`	`string`
`signInHint`	`string`
`footer`	`string \| null`
`brand`	`object`
`discover`	`object \| null`
`audienceAuth`	`object \| null`
`hostedUrl`	`string \| null`

resolveHostedApp

Resolve a hosted slug to its project/app identity and public audience auth hints

GET

Usage:

const result = await swirls.client.apps.resolveHostedApp({
  hostedSlug: '...',
})

Input:

Parameter	Type	Required	Description
`hostedSlug`	`string`	Yes

Output:

Field	Type	Description
`projectId`	`string`
`appName`	`string`
`appLabel`	`string`
`hostedUrl`	`string`
`audienceAuth`	`object \| null`

getAudiencePolicy

Read the active audience policy and hosting metadata for a builder-administered app

GET

Usage:

const result = await swirls.client.apps.getAudiencePolicy({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes
`appName`	`string`	Yes

Output:

Field	Type	Description
`audienceEnabled`	`boolean`
`hostedSlug`	`string \| null`
`hostedUrl`	`string \| null`
`policy`	`object \| null`
`canManage`	`boolean`

createAudienceInvitation

Invite an external user to a hosted app audience

POST

Usage:

const result = await swirls.client.apps.createAudienceInvitation({
  projectId: '...',
  appName: '...',
  email: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`email`	`string`	Yes

Output:

Field	Type	Description
`id`	`string`
`email`	`string`
`status`	`"pending" \| "accepted" \| "revoked"`
`effectiveStatus`	`"pending" \| "accepted" \| "revoked" \| "expired"`
`expiresAt`	`string`
`createdAt`	`string`
`acceptedAt`	`string \| null`
`lastSentAt`	`string`
`sendCount`	`number`

listAudienceInvitations

List pending and historical app audience invitations

GET

Usage:

const result = await swirls.client.apps.listAudienceInvitations({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`status`	`"pending" \| "accepted" \| "revoked" \| "expired"`	No
`search`	`string`	No

Output:

Field	Type	Description
`invitations`	`object[]`

resendAudienceInvitation

Resend a pending app audience invitation

POST

Usage:

const result = await swirls.client.apps.resendAudienceInvitation({
  projectId: '...',
  appName: '...',
  invitationId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`invitationId`	`string`	Yes

Output:

Field	Type	Description
`id`	`string`
`email`	`string`
`status`	`"pending" \| "accepted" \| "revoked"`
`effectiveStatus`	`"pending" \| "accepted" \| "revoked" \| "expired"`
`expiresAt`	`string`
`createdAt`	`string`
`acceptedAt`	`string \| null`
`lastSentAt`	`string`
`sendCount`	`number`

revokeAudienceInvitation

Cancel a pending app audience invitation

POST

Usage:

const result = await swirls.client.apps.revokeAudienceInvitation({
  projectId: '...',
  appName: '...',
  invitationId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`invitationId`	`string`	Yes

Output:

Field	Type	Description
`ok`	`true`

listAudienceUsers

List external app audience users and their status

GET

Usage:

const result = await swirls.client.apps.listAudienceUsers({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`status`	`"active" \| "revoked"`	No
`authSource`	`"email_otp" \| "oidc"`	No
`search`	`string`	No

Output:

Field	Type	Description
`users`	`object[]`

revokeAudienceUser

Revoke an external app user and their sessions

POST

Usage:

const result = await swirls.client.apps.revokeAudienceUser({
  projectId: '...',
  appName: '...',
  appUserId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`appUserId`	`string`	Yes

Output:

Field	Type	Description
`ok`	`true`

reactivateAudienceUser

Reactivate a revoked external app user

POST

Usage:

const result = await swirls.client.apps.reactivateAudienceUser({
  projectId: '...',
  appName: '...',
  appUserId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`appUserId`	`string`	Yes

Output:

Field	Type	Description
`ok`	`true`

listAudienceUserSessions

List sessions for an external app user

GET

Usage:

const result = await swirls.client.apps.listAudienceUserSessions({
  projectId: '...',
  appName: '...',
  appUserId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`appUserId`	`string`	Yes

Output:

Field	Type	Description
`sessions`	`object[]`

revokeAudienceUserSession

Revoke one external app user session

POST

Usage:

const result = await swirls.client.apps.revokeAudienceUserSession({
  projectId: '...',
  appName: '...',
  sessionId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`sessionId`	`string`	Yes

Output:

Field	Type	Description
`ok`	`true`

revokeAllAudienceUserSessions

Revoke every session for an external app user

POST

Usage:

const result = await swirls.client.apps.revokeAllAudienceUserSessions({
  projectId: '...',
  appName: '...',
  appUserId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`appUserId`	`string`	Yes

Output:

Field	Type	Description
`ok`	`true`

getAudienceOverview

Live roster counts plus range metrics for a hosted app audience

GET

Usage:

const result = await swirls.client.apps.getAudienceOverview({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`range`	`"24h" \| "7d" \| "30d"`	No

Output:

Field	Type	Description
`canManage`	`boolean`
`activeUsers`	`number`
`pendingInvites`	`number`
`activeSessions`	`number`
`signIns`	`number`
`workflowLaunches`	`number`

listAudienceActivity

App-scoped audience activity feed

GET

Usage:

const result = await swirls.client.apps.listAudienceActivity({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`range`	`"24h" \| "7d" \| "30d"`	No
`outcome`	`"success" \| "failure" \| "denied"`	No
`subject`	`string`	No
`limit`	`number`	No
`cursor`	`string`	No

Output:

Field	Type	Description
`data`	`object[]`
`nextCursor`	`string`

listAudienceIdpBindings

GET

Usage:

const result = await swirls.client.apps.listAudienceIdpBindings({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes
`appName`	`string`	Yes

Output:

Field	Type	Description
`bindings`	`object[]`

upsertAudienceIdpBinding

POST

Usage:

const result = await swirls.client.apps.upsertAudienceIdpBinding({
  projectId: '...',
  appName: '...',
  alias: '...',
  provider: '...',
  instanceIdentifier: '...',
  clientId: '...',
  clientSecret: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`alias`	`string`	Yes
`provider`	`"clerk" \| "supabase" \| "okta"`	Yes
`instanceIdentifier`	`string`	Yes
`clientId`	`string`	Yes
`clientSecret`	`string`	Yes

Output:

Field	Type	Description
`ok`	`true`

deleteAudienceIdpBinding

POST

Usage:

const result = await swirls.client.apps.deleteAudienceIdpBinding({
  projectId: '...',
  appName: '...',
  alias: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`alias`	`string`	Yes

Output:

Field	Type	Description
`ok`	`true`

listChatThreads

List chat threads for inbox, participant Mine, Public discovery, or accessible (mine ∪ public)

GET

Usage:

const result = await swirls.client.apps.listChatThreads({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`channelName`	`string`	No
`channelNames`	`string[]`	No
`filter`	`"inbox" \| "mine" \| "public" \| "accessible"`	No
`membershipKind`	`"started" \| "invited" \| "joined"`	No
`limit`	`number`	No
`cursor`	`string`	No

Output:

Field	Type	Description
`data`	`object[]`
`nextCursor`	`string`

getChatThread

Thread metadata, participant summary, and attention snapshot

GET

Usage:

const result = await swirls.client.apps.getChatThread({
  projectId: '...',
  appName: '...',
  threadId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`threadId`	`string`	Yes

Output:

Field	Type	Description
`thread`	`object`
`participantIds`	`string[]`
`participants`	`object[]`

createChatThread

Create a standalone thread; seeds creator as participant

POST

Usage:

const result = await swirls.client.apps.createChatThread({
  projectId: '...',
  appName: '...',
  channelName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`channelName`	`string`	Yes
`threadId`	`string`	No
`title`	`string`	No
`visibility`	`"private" \| "public"`	No

Output:

Field	Type	Description
`id`	`string`
`channelName`	`string`
`title`	`string \| null`
`visibility`	`"private" \| "public"`
`createdBy`	`string`
`creatorDisplayName`	`string \| null`
`archivedAt`	`string \| unknown \| null`
`sequence`	`number`
`createdAt`	`string \| unknown`
`updatedAt`	`string \| unknown`
`participantCount`	`number`
`lastMessagePreview`	`string \| null`
`lastMessageAuthorDisplayName`	`string \| null`
`unreadCount`	`number`
`mentionUnread`	`boolean`
`isParticipant`	`boolean`
`membershipKind`	`"started" \| "invited" \| "joined" \| null`

updateChatThread

Update title, visibility, or archive state (creator controls)

POST

Usage:

const result = await swirls.client.apps.updateChatThread({
  projectId: '...',
  appName: '...',
  threadId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`threadId`	`string`	Yes
`title`	`string`	No
`visibility`	`"private" \| "public"`	No
`archived`	`boolean`	No

Output:

Field	Type	Description
`id`	`string`
`channelName`	`string`
`title`	`string \| null`
`visibility`	`"private" \| "public"`
`createdBy`	`string`
`creatorDisplayName`	`string \| null`
`archivedAt`	`string \| unknown \| null`
`sequence`	`number`
`createdAt`	`string \| unknown`
`updatedAt`	`string \| unknown`
`participantCount`	`number`
`lastMessagePreview`	`string \| null`
`lastMessageAuthorDisplayName`	`string \| null`
`unreadCount`	`number`
`mentionUnread`	`boolean`
`isParticipant`	`boolean`
`membershipKind`	`"started" \| "invited" \| "joined" \| null`

listChatMessages

Paginated thread transcript from app_messages

GET

Usage:

const result = await swirls.client.apps.listChatMessages({
  projectId: '...',
  appName: '...',
  threadId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`threadId`	`string`	Yes
`afterSequence`	`number`	No
`beforeSequence`	`number`	No
`limit`	`number`	No

Output:

Field	Type	Description
`messages`	`object[]`
`hasMore`	`boolean`

postChatMessage

Post a human message; may enqueue agent turn when agent is addressed

POST

Usage:

const result = await swirls.client.apps.postChatMessage({
  projectId: '...',
  appName: '...',
  threadId: '...',
  body: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`threadId`	`string`	Yes
`body`	`string`	Yes
`attachments`	`object[]`	No
`mentions`	`object[]`	No
`controls`	`object`	No
`messageId`	`string`	No
`channelName`	`string`	No
`idempotencyKey`	`string`	No

Output:

Field	Type	Description
`message`	`object`
`agentTurnPending`	`boolean`
`thread`	`object`

listChatMentionCandidates

Roster for @-typeahead: owning-org members, app audience users, channel agents

GET

Usage:

const result = await swirls.client.apps.listChatMentionCandidates({
  projectId: '...',
  appName: '...',
  channelName: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`channelName`	`string`	Yes
`query`	`string`	No

Output:

Field	Type	Description
`candidates`	`object[]`

markChatThreadRead

Mark thread read up to current sequence; returns updated attention

POST

Usage:

const result = await swirls.client.apps.markChatThreadRead({
  projectId: '...',
  appName: '...',
  threadId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`threadId`	`string`	Yes

Output:

Field	Type	Description
`thread`	`object`

joinChatThread

Join a public thread as a participant and initialize read cursor

POST

Usage:

const result = await swirls.client.apps.joinChatThread({
  projectId: '...',
  appName: '...',
  threadId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`threadId`	`string`	Yes

Output:

Field	Type	Description
`id`	`string`
`channelName`	`string`
`title`	`string \| null`
`visibility`	`"private" \| "public"`
`createdBy`	`string`
`creatorDisplayName`	`string \| null`
`archivedAt`	`string \| unknown \| null`
`sequence`	`number`
`createdAt`	`string \| unknown`
`updatedAt`	`string \| unknown`
`participantCount`	`number`
`lastMessagePreview`	`string \| null`
`lastMessageAuthorDisplayName`	`string \| null`
`unreadCount`	`number`
`mentionUnread`	`boolean`
`isParticipant`	`boolean`
`membershipKind`	`"started" \| "invited" \| "joined" \| null`

leaveChatThread

Leave a joined thread; creators retain ownership without membership

POST

Usage:

const result = await swirls.client.apps.leaveChatThread({
  projectId: '...',
  appName: '...',
  threadId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`threadId`	`string`	Yes

Output:

Field	Type	Description
`id`	`string`
`channelName`	`string`
`title`	`string \| null`
`visibility`	`"private" \| "public"`
`createdBy`	`string`
`creatorDisplayName`	`string \| null`
`archivedAt`	`string \| unknown \| null`
`sequence`	`number`
`createdAt`	`string \| unknown`
`updatedAt`	`string \| unknown`
`participantCount`	`number`
`lastMessagePreview`	`string \| null`
`lastMessageAuthorDisplayName`	`string \| null`
`unreadCount`	`number`
`mentionUnread`	`boolean`
`isParticipant`	`boolean`
`membershipKind`	`"started" \| "invited" \| "joined" \| null`

getChatAttention

App-wide and per-channel unread and mention-unread counts for shell nav

GET

Usage:

const result = await swirls.client.apps.getChatAttention({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes
`appName`	`string`	Yes

Output:

Field	Type	Description
`app`	`object`
`channels`	`object[]`

mintActorDirectoryGrant

Mint a short-lived WebSocket grant for the app directory Durable Object

POST

Usage:

const result = await swirls.client.apps.mintActorDirectoryGrant({
  projectId: '...',
  appName: '...',
})

Input:

Parameter	Type	Required	Description
`projectId`	`string`	Yes
`appName`	`string`	Yes

Output:

Field	Type	Description
`actor`	`"directory" \| "project" \| "session" \| "execution"`
`grant`	`string`
`websocketUrl`	`string`
`expiresAt`	`string`
`appId`	`string`
`projectId`	`string`
`sessionId`	`string`
`threadId`	`string`
`runId`	`string`
`executionId`	`string`

mintActorSessionGrant

Mint a short-lived WebSocket grant for an authorized agent-session Durable Object

POST

Usage:

const result = await swirls.client.apps.mintActorSessionGrant({
  projectId: '...',
  appName: '...',
  threadId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`appName`	`string`	Yes
`threadId`	`string`	Yes
`runId`	`string`	No

Output:

Field	Type	Description
`actor`	`"directory" \| "project" \| "session" \| "execution"`
`grant`	`string`
`websocketUrl`	`string`
`expiresAt`	`string`
`appId`	`string`
`projectId`	`string`
`sessionId`	`string`
`threadId`	`string`
`runId`	`string`
`executionId`	`string`

mintActorExecutionGrant

Mint a short-lived WebSocket grant for a workflow execution

POST

Usage:

const result = await swirls.client.apps.mintActorExecutionGrant({
  projectId: '...',
  executionId: '...',
})

Input:

Parameter	Type	Required
`projectId`	`string`	Yes
`executionId`	`string`	Yes
`appName`	`string`	No

Output:

Field	Type	Description
`actor`	`"directory" \| "project" \| "session" \| "execution"`
`grant`	`string`
`websocketUrl`	`string`
`expiresAt`	`string`
`appId`	`string`
`projectId`	`string`
`sessionId`	`string`
`threadId`	`string`
`runId`	`string`
`executionId`	`string`

On this page