AWS.QApps reference

AssociateLibraryItemReview

Source: src/AWS/QApps/AssociateLibraryItemReview.ts

Runtime binding for qapps:AssociateLibraryItemReview.

Upvotes a library item as the calling identity. Provide the implementation with Effect.provide(AWS.QApps.AssociateLibraryItemReviewHttp).

AssociateLibraryItemReview: Library Items

// init — bind the operation to the Q App
const associateLibraryItemReview = yield* AWS.QApps.AssociateLibraryItemReview(app);

// runtime
yield* associateLibraryItemReview({ libraryItemId });

AssociateQAppWithUser

Source: src/AWS/QApps/AssociateQAppWithUser.ts

Runtime binding for qapps:AssociateQAppWithUser.

Links the calling identity to the bound Q App, marking it as a favorite in the user’s inventory. Provide the implementation with Effect.provide(AWS.QApps.AssociateQAppWithUserHttp).

AssociateQAppWithUser: User Inventory

// init — bind the operation to the Q App
const associateQAppWithUser = yield* AWS.QApps.AssociateQAppWithUser(app);

// runtime
yield* associateQAppWithUser();

BatchCreateCategory

Source: src/AWS/QApps/BatchCreateCategory.ts

Runtime binding for qapps:BatchCreateCategory.

Creates library categories that web-experience users use to tag and filter library items. Provide the implementation with Effect.provide(AWS.QApps.BatchCreateCategoryHttp).

BatchCreateCategory: Categories

// init — bind the operation to the Q App
const batchCreateCategory = yield* AWS.QApps.BatchCreateCategory(app);

// runtime
yield* batchCreateCategory({
  categories: [{ title: "HR" }, { title: "Marketing" }],
});

BatchDeleteCategory

Source: src/AWS/QApps/BatchDeleteCategory.ts

Runtime binding for qapps:BatchDeleteCategory.

Deletes library categories by id. Provide the implementation with Effect.provide(AWS.QApps.BatchDeleteCategoryHttp).

BatchDeleteCategory: Categories

// init — bind the operation to the Q App
const batchDeleteCategory = yield* AWS.QApps.BatchDeleteCategory(app);

// runtime
yield* batchDeleteCategory({ categories: [categoryId] });

BatchUpdateCategory

Source: src/AWS/QApps/BatchUpdateCategory.ts

Runtime binding for qapps:BatchUpdateCategory.

Renames or recolors existing library categories. Provide the implementation with Effect.provide(AWS.QApps.BatchUpdateCategoryHttp).

BatchUpdateCategory: Categories

// init — bind the operation to the Q App
const batchUpdateCategory = yield* AWS.QApps.BatchUpdateCategory(app);

// runtime
yield* batchUpdateCategory({
  categories: [{ id: categoryId, title: "People Ops" }],
});

CreateLibraryItem

Source: src/AWS/QApps/CreateLibraryItem.ts

Runtime binding for qapps:CreateLibraryItem.

Publishes a version of the bound Q App into the instance’s library so other users can discover and run it. Provide the implementation with Effect.provide(AWS.QApps.CreateLibraryItemHttp).

CreateLibraryItem: Library Items

// init — bind the operation to the Q App
const createLibraryItem = yield* AWS.QApps.CreateLibraryItem(app);

// runtime
const item = yield* createLibraryItem({
  appVersion: 1,
  categories: [categoryId],
});
console.log(item.libraryItemId);

CreatePresignedUrl

Source: src/AWS/QApps/CreatePresignedUrl.ts

Runtime binding for qapps:CreatePresignedUrl.

Creates a presigned upload URL for a file-upload card of the bound Q App. Provide the implementation with Effect.provide(AWS.QApps.CreatePresignedUrlHttp).

CreatePresignedUrl: Files

// init — bind the operation to the Q App
const createPresignedUrl = yield* AWS.QApps.CreatePresignedUrl(app);

// runtime
const upload = yield* createPresignedUrl({
  cardId,
  fileContentsSha256,
  fileName: "report.pdf",
  scope: "SESSION",
  sessionId,
});
console.log(upload.presignedUrl);

DeleteLibraryItem

Source: src/AWS/QApps/DeleteLibraryItem.ts

Runtime binding for qapps:DeleteLibraryItem.

Unpublishes a library item, removing the app from the instance’s library. Provide the implementation with Effect.provide(AWS.QApps.DeleteLibraryItemHttp).

DeleteLibraryItem: Library Items

// init — bind the operation to the Q App
const deleteLibraryItem = yield* AWS.QApps.DeleteLibraryItem(app);

// runtime
yield* deleteLibraryItem({ libraryItemId });

DescribeQAppPermissions

Source: src/AWS/QApps/DescribeQAppPermissions.ts

Runtime binding for qapps:DescribeQAppPermissions.

Reads the principals and actions granted on the bound Q App. Provide the implementation with Effect.provide(AWS.QApps.DescribeQAppPermissionsHttp).

DescribeQAppPermissions: Permissions

// init — bind the operation to the Q App
const describeQAppPermissions = yield* AWS.QApps.DescribeQAppPermissions(app);

// runtime
const permissions = yield* describeQAppPermissions();
console.log(permissions.permissions?.length);

DisassociateLibraryItemReview

Source: src/AWS/QApps/DisassociateLibraryItemReview.ts

Runtime binding for qapps:DisassociateLibraryItemReview.

Removes the calling identity’s upvote from a library item. Provide the implementation with Effect.provide(AWS.QApps.DisassociateLibraryItemReviewHttp).

DisassociateLibraryItemReview: Library Items

// init — bind the operation to the Q App
const disassociateLibraryItemReview = yield* AWS.QApps.DisassociateLibraryItemReview(app);

// runtime
yield* disassociateLibraryItemReview({ libraryItemId });

DisassociateQAppFromUser

Source: src/AWS/QApps/DisassociateQAppFromUser.ts

Runtime binding for qapps:DisassociateQAppFromUser.

Removes the bound Q App from the calling identity’s inventory of favorited apps. Provide the implementation with Effect.provide(AWS.QApps.DisassociateQAppFromUserHttp).

DisassociateQAppFromUser: User Inventory

// init — bind the operation to the Q App
const disassociateQAppFromUser = yield* AWS.QApps.DisassociateQAppFromUser(app);

// runtime
yield* disassociateQAppFromUser();

ExportQAppSessionData

Source: src/AWS/QApps/ExportQAppSessionData.ts

Runtime binding for qapps:ExportQAppSessionData.

Exports a shared Q App session’s collected data as a downloadable CSV file link. Provide the implementation with Effect.provide(AWS.QApps.ExportQAppSessionDataHttp).

ExportQAppSessionData: Sessions

// init — bind the operation to the Q App
const exportQAppSessionData = yield* AWS.QApps.ExportQAppSessionData(app);

// runtime
const exported = yield* exportQAppSessionData({ sessionId });
console.log(exported.csvFileLink);

GetLibraryItem

Source: src/AWS/QApps/GetLibraryItem.ts

Runtime binding for qapps:GetLibraryItem.

Retrieves a library item — its published app version, categories, status, and rating counts. Provide the implementation with Effect.provide(AWS.QApps.GetLibraryItemHttp).

GetLibraryItem: Library Items

// init — bind the operation to the Q App
const getLibraryItem = yield* AWS.QApps.GetLibraryItem(app);

// runtime
const item = yield* getLibraryItem({ libraryItemId });
console.log(item.ratingCount);

GetQAppSession

Source: src/AWS/QApps/GetQAppSession.ts

Runtime binding for qapps:GetQAppSession.

Retrieves the current state of a Q App session — execution status plus the per-card status map. Provide the implementation with Effect.provide(AWS.QApps.GetQAppSessionHttp).

GetQAppSession: Sessions

// init — bind the operation to the Q App
const getQAppSession = yield* AWS.QApps.GetQAppSession(app);

// runtime
const state = yield* getQAppSession({ sessionId });
if (state.status === "COMPLETED") console.log(state.cardStatus);

GetQAppSessionMetadata

Source: src/AWS/QApps/GetQAppSessionMetadata.ts

Runtime binding for qapps:GetQAppSessionMetadata.

Retrieves a Q App session’s metadata — name, sharing configuration, and ownership. Provide the implementation with Effect.provide(AWS.QApps.GetQAppSessionMetadataHttp).

GetQAppSessionMetadata: Sessions

// init — bind the operation to the Q App
const getQAppSessionMetadata = yield* AWS.QApps.GetQAppSessionMetadata(app);

// runtime
const metadata = yield* getQAppSessionMetadata({ sessionId });
console.log(metadata.sharingConfiguration.enabled);

ImportDocument

Source: src/AWS/QApps/ImportDocument.ts

Runtime binding for qapps:ImportDocument.

Uploads a base64-encoded file into a card of the bound Q App, at app or session scope. Provide the implementation with Effect.provide(AWS.QApps.ImportDocumentHttp).

ImportDocument: Files

// init — bind the operation to the Q App
const importDocument = yield* AWS.QApps.ImportDocument(app);

// runtime
const imported = yield* importDocument({
  cardId,
  fileContentsBase64,
  fileName: "notes.txt",
  scope: "SESSION",
  sessionId,
});
console.log(imported.fileId);

ListCategories

Source: src/AWS/QApps/ListCategories.ts

Runtime binding for qapps:ListCategories.

Lists the library categories of the bound app’s Q Business application environment instance. Provide the implementation with Effect.provide(AWS.QApps.ListCategoriesHttp).

ListCategories: Categories

// init — bind the operation to the Q App
const listCategories = yield* AWS.QApps.ListCategories(app);

// runtime
const result = yield* listCategories();
console.log(result.categories?.map((c) => c.title));

ListLibraryItems

Source: src/AWS/QApps/ListLibraryItems.ts

Runtime binding for qapps:ListLibraryItems.

Lists the library items published in the bound app’s Q Business application environment instance. Provide the implementation with Effect.provide(AWS.QApps.ListLibraryItemsHttp).

ListLibraryItems: Library Items

// init — bind the operation to the Q App
const listLibraryItems = yield* AWS.QApps.ListLibraryItems(app);

// runtime
const page = yield* listLibraryItems({ limit: 25 });
console.log(page.libraryItems?.length);

ListQApps

Source: src/AWS/QApps/ListQApps.ts

Runtime binding for qapps:ListQApps.

Lists the calling identity’s Q Apps in the bound app’s Q Business application environment instance. Provide the implementation with Effect.provide(AWS.QApps.ListQAppsHttp).

ListQApps: User Inventory

// init — bind the operation to the Q App
const listQApps = yield* AWS.QApps.ListQApps(app);

// runtime
const page = yield* listQApps({ limit: 25 });
console.log(page.apps.map((a) => a.title));

ListQAppSessionData

Source: src/AWS/QApps/ListQAppSessionData.ts

Runtime binding for qapps:ListQAppSessionData.

Lists the per-user data collected in a shared Q App session. Provide the implementation with Effect.provide(AWS.QApps.ListQAppSessionDataHttp).

ListQAppSessionData: Sessions

// init — bind the operation to the Q App
const listQAppSessionData = yield* AWS.QApps.ListQAppSessionData(app);

// runtime
const data = yield* listQAppSessionData({ sessionId });
console.log(data.sessionData?.length);

PredictQApp

Source: src/AWS/QApps/PredictQApp.ts

Runtime binding for qapps:PredictQApp.

Generates a Q App definition from a natural-language problem statement or a Q Business conversation. Provide the implementation with Effect.provide(AWS.QApps.PredictQAppHttp).

PredictQApp: Generation

// init — bind the operation to the Q App
const predictQApp = yield* AWS.QApps.PredictQApp(app);

// runtime
const predicted = yield* predictQApp({
  options: {
    problemStatement: "Summarize meeting notes into action items",
  },
});
console.log(predicted.app.title);

QApp

Source: src/AWS/QApps/QApp.ts

An Amazon Q App — a lightweight, purpose-built AI app defined as a flow of cards (text inputs, file uploads, LLM query cards, plugin cards) running inside an Amazon Q Business application environment.

Caution

Q Apps live inside an Amazon Q Business application (pass its id as instanceId), which itself requires IAM Identity Center. The calling identity must be a user of that Q Business application.

QApp: Creating Q Apps

Prompt-Driven Q App

import * as AWS from "alchemy/AWS";

const summarizer = yield* AWS.QApps.QApp("Summarizer", {
  instanceId: qbusinessApp.applicationId,
  description: "Summarizes pasted text",
  appDefinition: {
    cards: [
      {
        textInput: {
          id: "11111111-1111-4111-8111-111111111111",
          title: "Source Text",
          type: "text-input",
        },
      },
      {
        qQuery: {
          id: "22222222-2222-4222-8222-222222222222",
          title: "Summary",
          type: "q-query",
          prompt: "Summarize the following text: @Source Text",
        },
      },
    ],
  },
});

File Upload Q App

const analyzer = yield* AWS.QApps.QApp("DocAnalyzer", {
  instanceId: qbusinessApp.applicationId,
  appDefinition: {
    initialPrompt: "Upload a document to analyze",
    cards: [
      {
        fileUpload: {
          id: "33333333-3333-4333-8333-333333333333",
          title: "Document",
          type: "file-upload",
        },
      },
      {
        qQuery: {
          id: "44444444-4444-4444-8444-444444444444",
          title: "Analysis",
          type: "q-query",
          prompt: "List the key points of @Document",
        },
      },
    ],
  },
});

StartQAppSession

Source: src/AWS/QApps/StartQAppSession.ts

Runtime binding for qapps:StartQAppSession.

Starts a new session of the bound Q App, optionally seeding initial card values. Provide the implementation with Effect.provide(AWS.QApps.StartQAppSessionHttp).

StartQAppSession: Sessions

// init — bind the operation to the Q App
const startQAppSession = yield* AWS.QApps.StartQAppSession(app);

// runtime
const session = yield* startQAppSession({ appVersion: 1 });
console.log(session.sessionId);

StopQAppSession

Source: src/AWS/QApps/StopQAppSession.ts

Runtime binding for qapps:StopQAppSession.

Stops an active Q App session, halting any in-progress card executions. Provide the implementation with Effect.provide(AWS.QApps.StopQAppSessionHttp).

StopQAppSession: Sessions

// init — bind the operation to the Q App
const stopQAppSession = yield* AWS.QApps.StopQAppSession(app);

// runtime
yield* stopQAppSession({ sessionId });

UpdateLibraryItem

Source: src/AWS/QApps/UpdateLibraryItem.ts

Runtime binding for qapps:UpdateLibraryItem.

Updates a library item’s publication status or categories. Provide the implementation with Effect.provide(AWS.QApps.UpdateLibraryItemHttp).

UpdateLibraryItem: Library Items

// init — bind the operation to the Q App
const updateLibraryItem = yield* AWS.QApps.UpdateLibraryItem(app);

// runtime
yield* updateLibraryItem({ libraryItemId, status: "DISABLED" });

UpdateLibraryItemMetadata

Source: src/AWS/QApps/UpdateLibraryItemMetadata.ts

Runtime binding for qapps:UpdateLibraryItemMetadata.

Updates a library item’s verification badge (isVerified). Provide the implementation with Effect.provide(AWS.QApps.UpdateLibraryItemMetadataHttp).

UpdateLibraryItemMetadata: Library Items

// init — bind the operation to the Q App
const updateLibraryItemMetadata = yield* AWS.QApps.UpdateLibraryItemMetadata(app);

// runtime
yield* updateLibraryItemMetadata({ libraryItemId, isVerified: true });

UpdateQAppPermissions

Source: src/AWS/QApps/UpdateQAppPermissions.ts

Runtime binding for qapps:UpdateQAppPermissions.

Grants or revokes read/edit permissions on the bound Q App for Identity Center principals. Provide the implementation with Effect.provide(AWS.QApps.UpdateQAppPermissionsHttp).

UpdateQAppPermissions: Permissions

// init — bind the operation to the Q App
const updateQAppPermissions = yield* AWS.QApps.UpdateQAppPermissions(app);

// runtime
yield* updateQAppPermissions({
  grantPermissions: [{ action: "read", principal: userId }],
});

UpdateQAppSession

Source: src/AWS/QApps/UpdateQAppSession.ts

Runtime binding for qapps:UpdateQAppSession.

Submits new card values into a running Q App session (e.g. answers a text-input card). Provide the implementation with Effect.provide(AWS.QApps.UpdateQAppSessionHttp).

UpdateQAppSession: Sessions

// init — bind the operation to the Q App
const updateQAppSession = yield* AWS.QApps.UpdateQAppSession(app);

// runtime
yield* updateQAppSession({
  sessionId,
  values: [{ cardId, value: "Hello, Q Apps!" }],
});

UpdateQAppSessionMetadata

Source: src/AWS/QApps/UpdateQAppSessionMetadata.ts

Runtime binding for qapps:UpdateQAppSessionMetadata.

Updates a Q App session’s metadata — rename it or reconfigure how it is shared with collaborators. Provide the implementation with Effect.provide(AWS.QApps.UpdateQAppSessionMetadataHttp).

UpdateQAppSessionMetadata: Sessions

// init — bind the operation to the Q App
const updateQAppSessionMetadata = yield* AWS.QApps.UpdateQAppSessionMetadata(app);

// runtime
yield* updateQAppSessionMetadata({
  sessionId,
  sharingConfiguration: { enabled: true, acceptResponses: true },
});