apps

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: '...',
  limit: 1,
})

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`	Yes
`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: '...',
  limit: 1,
})

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`	Yes
`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 Durable Object harness

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