> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumos.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Appstore Apps > List all AppStore apps. ## OpenAPI ````yaml openapi/lumos.json GET /appstore/apps openapi: 3.1.0 info: title: Lumos description: |2 The Lumos API gives you the building blocks to administer and extend Lumos programmatically. Our REST API provides a management interface for the AppStore and a read interface for the Lumos Core. Go to https://developers.lumos.com to see our complete documentation. version: 0.1.0 servers: - url: https://api.lumos.com security: [] tags: - name: Access Reviews description: > Create and manage access review campaigns — scheduled reviews of who has access to what across your connected apps. **Typical workflow for creating a review:** 1. `GET /apps` — find the domain app UUIDs you want to review. 2. `GET /access_reviews/scope_options?domain_app_id={id}` — discover available scope filters (employment status, team, last login, etc.). Each returned `items` entry is a ready-to-POST `scope_filters` payload; datetime and custom-attribute groups instead expose a `filter_input_template`. 3. `POST /access_reviews` with `apps` (optionally with `scope_filters` per app) — creates the campaign. 4. `GET /access_reviews/{id}` — poll until `status` transitions from `IN_PREPARATION` to `IN_PROGRESS`. **After creation:** - `POST /access_reviews/{id}/apps` — add more apps while `status != COMPLETED`. - `PATCH /access_reviews/{id}` — update name / deadline / owner, or per-ARDA `scope_filters` and removal action. - `DELETE /access_reviews/{id}` — soft-delete the whole campaign. - `DELETE /access_reviews/{id}/apps/{arda_id}` — soft-delete a single app from the campaign. All endpoints require an API token with the `access_reviews.create` or `access_reviews.view` permission (Access Review Administrator or App Admin role). - name: Tasks description: > **Tasks** are work items emitted by Lumos workflows — things that need a human (or an automated caller) to make a decision or perform a step before the workflow can proceed. Typical examples: - An access request is waiting on an approver's decision. - A provisioning or deprovisioning step needs manual fulfillment. - An error needs acknowledgement. Each task carries two classification fields you can filter on: - **`task_category`** — what kind of decision or step the task represents. Values: `APPROVAL`, `PROVISIONING`, `DEPROVISIONING`, `ERROR`. - **`product_area`** — which Lumos product surface emitted the task. Values: `APPSTORE`, `ACCESS_REVIEWS`, `MOVER`, `ATTRIBUTE_SYNC`, `OFFBOARDING`, `ONBOARDING`, `PLATFORM`, `SAVINGS`. ### Which endpoint should I call? - **To approve or deny an access request**, use `POST /tasks/{task_id}/complete` (approve) or `POST /tasks/{task_id}/dismiss` (deny). - **To find pending approval tasks**, call `GET /tasks?task_category=APPROVAL&product_area=APPSTORE&status=PENDING` (access requests). - **Only use `POST /tasks/{task_id}/perform-action`** for tasks that expose custom workflow actions. Discover those actions via `GET /tasks/{task_id}/actions`. Approval tasks do not require this endpoint — `complete` and `dismiss` are the right primitives. For a full walkthrough with `curl` and Python examples, see the [Tasks API How-To](https://developers.lumos.com/docs/tasks-api-how-to) guide. - name: Integrations description: > An integration is a service Lumos knows how to connect to, identified by an `app_class_id` such as `okta.com` or `workspace.google.com`. This is the catalog you connect *from*. Apps you have already connected are read through the Apps endpoints. Only connectable integrations appear here. Software discovered in your environment that has no Lumos integration behind it is excluded. ### Discovering how to connect 1. `GET /v1/integrations?query=google` to find the integration. The filter matches both the `app_class_id` and the display name, so `google` returns `workspace.google.com` and `cloud.google.com`. 2. `GET /v1/integrations/{app_class_id}/connection-schema` for the JSON schema of the `auth` and `settings` fields it expects. 3. `POST /v1/apps` with those values. Step 2 is the point of this group: it lets you build a connect form, or generate a Terraform resource, without hardcoding one credential shape per integration. Integrations whose connection schema Lumos cannot describe yet return 404. - name: Apps description: > An app is an integration you have connected, one per connected instance of a service. Your Okta tenant is an app. A second Slack workspace is a second app. ### Connecting one 1. `GET /v1/integrations/{app_class_id}/connection-schema` to see which `auth` and `settings` keys the integration expects. 2. `POST /v1/apps` with those credentials. Apps whose credentials validate right away connect and start an initial sync. Apps that need browser consent are finished in the Lumos UI. 3. `GET /v1/apps/{app_uuid}` to follow `sync_status`. 4. `POST /v1/apps/{app_uuid}/sync` to resync later. Only one sync runs per app at a time, so a second request while one is in flight returns 409. Rotate credentials with `PUT /v1/apps/{app_uuid}`. `DELETE /v1/apps/{app_uuid}` drops the stored credentials and returns the app to a connectable state. ### Reading apps `expand` is opt-in and evaluated per field: ask for `admins`, `custom_attributes`, `appstore_settings`, or any of the three workflow slots. A field you lack permission to read is left out of the response instead of failing the whole request, so a 200 does not prove every field you asked for came back. To reconcile the apps you manage from automation such as Terraform, combine `connection_source=API` with `disconnected=false`. ### Workflow slots Each app carries three bindings: an approval workflow, a default provisioning workflow, and a default deprovisioning workflow. The two `default_` slots supply the workflow that entitlements on the app fall back to. To bind a workflow to one entitlement instead, use the Entitlements endpoints. - name: Entitlements description: > An entitlement is a grantable unit of access on an app: a role, a license tier, a group, a permission. Accounts hold entitlements. - `POST /v1/entitlements` creates a requestable entitlement on an app. - `GET /v1/apps/{app_uuid}/entitlements` lists the entitlements on one app. - `GET /v1/entitlements/{entitlement_uuid}/accounts` lists who currently holds one. - `PATCH /v1/entitlements/{entitlement_uuid}` renames it. `label` is the only field you can change today, and sending any other field returns 400. - `DELETE /v1/entitlements/{entitlement_uuid}` refuses while the entitlement is still held, returning 409 with an `active_accounts` count. ### Per-entitlement workflows Three slots bind a workflow to a single entitlement rather than to the whole app: an approval override, a provisioning workflow, and a deprovisioning workflow. Each has a GET and a PUT. Not every entitlement supports them. An entitlement with no request configuration behind it returns 404 with `Workflows are not available for this entitlement.` on all six. - name: Accounts description: > An account is a person's presence inside a connected app. Accounts arrive through sync; you cannot create one through this API. `GET /v1/accounts/{account_uuid}/entitlements` lists what one account holds. It reads the same relationship as `GET /v1/entitlements/{entitlement_uuid}/accounts`, from the account's side rather than the entitlement's. - name: Workflows description: > A workflow is a reusable definition of the steps Lumos runs to approve a request, provision access, or deprovision it. Create the definition here, then bind it to an app or an entitlement through their own workflow endpoints. ### Building one 1. `GET /v1/workflow-steps?app_id={app_uuid}` to discover the steps available for that app, each with the input schema it accepts. 2. `POST /v1/workflows` with the steps you want. 3. Bind it, for example with `PUT /v1/apps/{app_uuid}/default-provisioning-workflow`. `type` and `app_id` are fixed at creation. `PUT /v1/workflows/{workflow_id}` rejects changes to either. ### Workflows this API cannot describe Some workflows Lumos builds for you, including the out-of-the-box provisioning defaults, contain steps with no public representation. `GET /v1/workflows` skips them, so a page can hold fewer items than `page_size` while more results remain. Treat an absent `next_page_token`, not a short page, as the end of the list. Binding one of these to a slot returns 400. - name: Custom Attribute Definitions description: > Custom attributes are the extra fields your organization keeps on users and accounts. These endpoints read their *definitions*, not the values stored against any particular user. `GET /v1/custom-attribute-definitions` returns one entry per label, unified across every app that supplies it. Narrow the list with `config_type` to separate user attributes from account attributes, with `source_type` to tell attributes synced from an app apart from ones your team created, or with `app_id` to see only what a single app supplies. - name: Knowledge description: > Knowledge entries are the documents and notes Lumos agents draw on when they answer access questions. Each entry carries a title, body, tags, and product scopes, plus an optional file attachment. Because of that attachment, create and update send `multipart/form-data` rather than JSON. On update, tag and scope lists replace what was there instead of appending, and `clear_attachment=true` removes an existing file without uploading a replacement. `DELETE` archives rather than destroys. The entry stops appearing in list results and stays recoverable. Pages here are small: `page_size` defaults to 10 and is clamped to 25. paths: /appstore/apps: get: tags: - AppStore summary: Get Appstore Apps description: List all AppStore apps. operationId: getAppStoreApps parameters: - name: app_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Filters apps by the ID of the app. title: App Id description: Filters apps by the ID of the app. - name: name_search in: query required: false schema: anyOf: - type: string - type: 'null' description: Search against name, app instance identifier, and app class ID. title: Name Search description: Search against name, app instance identifier, and app class ID. - name: exact_match in: query required: false schema: type: boolean description: Search filter should be an exact match. default: false title: Exact Match description: Search filter should be an exact match. - name: all_visibilities in: query required: false schema: type: boolean description: >- Get all apps in the AppStore regardless of visibility. Only available to admins. default: false title: All Visibilities description: >- Get all apps in the AppStore regardless of visibility. Only available to admins. - name: expand in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: 'Fields to expand. Supported fields: custom_attributes.' title: Expand description: 'Fields to expand. Supported fields: custom_attributes.' - name: page in: query required: false schema: type: integer minimum: 1 description: Page number default: 1 title: Page description: Page number - name: size in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Page size default: 50 title: Size description: Page size responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Page_AppStoreApp_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: Page_AppStoreApp_: properties: items: items: $ref: '#/components/schemas/AppStoreApp' type: array title: Items total: anyOf: - type: integer minimum: 0 - type: 'null' title: Total page: anyOf: - type: integer minimum: 1 - type: 'null' title: Page size: anyOf: - type: integer minimum: 1 - type: 'null' title: Size pages: anyOf: - type: integer minimum: 0 - type: 'null' title: Pages type: object required: - items - total - page - size title: Page[AppStoreApp] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AppStoreApp: properties: id: type: string title: Id description: The ID of this app. app_class_id: type: string title: App Class Id description: >- The non-unique ID of the service associated with this requestable permission. Depending on how it is sourced in Lumos, this may be the app's name, website, or other identifier. instance_id: type: string title: Instance Id description: >- The non-unique ID of the instance associated with this app. This will be the Okta app id if it’s an Okta app, or will be marked as custom_app_import if manually uploaded into Lumos. user_friendly_label: type: string title: User Friendly Label description: The user-friendly label of this app. status: $ref: '#/components/schemas/DomainAppStatus' description: >- The status of this app. Possible values: 'DISCOVERED', 'IN_REVIEW', 'NEEDS_REVIEW', 'APPROVED', 'BLOCKLISTED', 'DEPRECATED' sources: items: $ref: '#/components/schemas/DiscoverySource' type: array title: Sources description: The sources of this app. allow_multiple_permission_selection: type: boolean title: Allow Multiple Permission Selection description: >- Determines whether users can request multiple permissions at once.This field will be removed in subsequent API versions. logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: The URL of the logo of this app. website_url: anyOf: - type: string - type: 'null' title: Website Url description: The URL of the website of this app. request_instructions: anyOf: - type: string - type: 'null' title: Request Instructions description: The request instructions. description: anyOf: - type: string - type: 'null' title: Description description: The user-facing description of the app category: anyOf: - type: string - type: 'null' title: Category description: The category of the app, as shown in the AppStore disconnected: type: boolean title: Disconnected description: >- Whether this app has been disconnected (its stored credentials removed via `DELETE /apps/{app_id}`). A disconnected app is excluded from `GET /apps?disconnected=false`; reconnect it with `PUT /apps/{app_id}`. links: $ref: '#/components/schemas/AppLinks' description: A collection of URLs related to this application sync_status: anyOf: - $ref: '#/components/schemas/SyncStatus' - type: 'null' description: >- The state of this app's most recent sync: `SYNCING` while one is running, `SUCCESS` or `FAILED` once it finished. Poll this after `POST /apps/{app_id}/sync` to follow that sync. `null` when no sync result is recorded — the app has never synced, or was disconnected. custom_attributes: anyOf: - additionalProperties: $ref: '#/components/schemas/CustomAttribute' type: object - type: 'null' title: Custom Attributes description: Custom attributes configured on the app type: object required: - id - app_class_id - instance_id - user_friendly_label - status - sources - allow_multiple_permission_selection - disconnected - links title: AppStoreApp ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError DomainAppStatus: type: string enum: - DISCOVERED - IN_REVIEW - NEEDS_REVIEW - APPROVED - BLOCKLISTED - DEPRECATED title: DomainAppStatus DiscoverySource: type: string enum: - GSUITE_QUICK_INBOX - GSUITE_DEEP_INBOX - MICROSOFT_DEEP_INBOX - MICROSOFT_OAUTH - MICROSOFT_GCC - GSUITE_OAUTH - OKTA - MANUAL - ONELOGIN - ATLASSIAN - GOOGLE_CLOUD - LUMOS_INTEGRATION - JUMPCLOUD - CUSTOM - MCP title: DiscoverySource AppLinks: properties: self: type: string title: Self description: The canonical API URL for retrieving this specific application admin_url: type: string title: Admin Url description: A URL to access this application within the Lumos web UI type: object required: - self - admin_url title: AppLinks SyncStatus: type: string enum: - SYNCING - SUCCESS - FAILED title: SyncStatus CustomAttribute: properties: type: $ref: '#/components/schemas/CustomAttributeType' description: >- The type of custom attribute. Only text and user options are available today value: anyOf: - type: string - items: $ref: '#/components/schemas/User' type: array - type: string format: date-time - type: integer - type: 'null' title: Value description: The value of the attribute for an individual Order type: object required: - type title: CustomAttribute CustomAttributeType: type: string enum: - TEXT - USER - SINGLE_SELECT title: CustomAttributeType User: properties: id: type: string title: Id description: The ID of this user. email: anyOf: - type: string - type: 'null' title: Email description: The email of this user. given_name: anyOf: - type: string - type: 'null' title: Given Name description: The given name of this user. family_name: anyOf: - type: string - type: 'null' title: Family Name description: The family name of this user. status: anyOf: - $ref: '#/components/schemas/UserLifecycleStatus' - type: 'null' description: The status of this user. type: object required: - id title: User UserLifecycleStatus: type: string enum: - STAGED - ACTIVE - SUSPENDED - INACTIVE title: UserLifecycleStatus securitySchemes: HTTPBearer: type: http scheme: bearer ````