> ## 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. # List Access Reviews > List access reviews for your organization. Paginated via standard `page` + `size` query params — `size` is capped at 100; requests over the cap return 422. ## OpenAPI ````yaml openapi/lumos.json GET /access_reviews 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: /access_reviews: get: tags: - Access Reviews summary: List Access Reviews description: >- List access reviews for your organization. Paginated via standard `page` + `size` query params — `size` is capped at 100; requests over the cap return 422. operationId: listAccessReviews parameters: - 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_AccessReviewOutput_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: Page_AccessReviewOutput_: properties: items: items: $ref: '#/components/schemas/AccessReviewOutput' 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[AccessReviewOutput] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AccessReviewOutput: properties: id: type: string title: Id description: UUID of the access review. name: type: string title: Name description: Name of the access review campaign. status: type: string enum: - IN_PREPARATION - IN_PROGRESS - COMPLETED - DUPLICATING - SCHEDULED - SCHEDULED_IN_PREPARATION - DELETED title: Status description: Current status of the access review. creation_path: type: string enum: - UI - RECURRENCE - API - CLI - MCP title: Creation Path description: How this review was created. owner_id: anyOf: - type: string - type: 'null' title: Owner Id description: UUID of the review owner. created_by_id: anyOf: - type: string - type: 'null' title: Created By Id description: UUID of the user who created this review. deadline_at: anyOf: - type: string format: date-time - type: 'null' title: Deadline At description: Deadline for completing reviews. started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At description: When the review was started. completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: When the review was completed. target_launch_date: anyOf: - type: string format: date-time - type: 'null' title: Target Launch Date description: Scheduled launch date, if this is a scheduled review. recurrence_config: anyOf: - $ref: '#/components/schemas/RecurrenceConfig' - type: 'null' description: Recurrence configuration, if this is a recurring review. recurrence_days_frequency: anyOf: - type: integer - type: 'null' title: Recurrence Days Frequency description: Recurrence frequency in days, if this is a recurring review. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: When this record was created. updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At description: When this record was last updated. apps: items: $ref: '#/components/schemas/AccessReviewDomainAppOutput' type: array title: Apps description: Apps included in this review. type: object required: - id - name - status - creation_path title: AccessReviewOutput 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 RecurrenceConfig: properties: freq: type: integer title: Freq description: >- Recurrence frequency. Use dateutil.rrule constants: YEARLY=0, MONTHLY=1, WEEKLY=2, DAILY=3, HOURLY=4, MINUTELY=5, SECONDLY=6. interval: anyOf: - type: integer - type: 'null' title: Interval description: Interval between each recurrence. Defaults to 1 (every freq period). count: anyOf: - type: integer - type: 'null' title: Count description: Total number of occurrences. Mutually exclusive with until. until: anyOf: - type: string - type: 'null' title: Until description: >- End date/time for the recurrence. ISO 8601 datetime string. Mutually exclusive with count. byweekday: anyOf: - items: anyOf: - type: integer - $ref: '#/components/schemas/PositionalWeekday' type: array - type: 'null' title: Byweekday description: >- Days of the week to recur on. 0=Monday, 1=Tuesday, ..., 6=Sunday. For positional weekdays (e.g. the first Monday of the month) use the {"weekday": N, "n": K} form, e.g. {"weekday": 0, "n": 1}. bymonth: anyOf: - items: type: integer type: array - type: 'null' title: Bymonth description: Months to recur on (1–12). bymonthday: anyOf: - items: type: integer type: array - type: 'null' title: Bymonthday description: >- Days of the month to recur on (1–31, negative values count from end). byyearday: anyOf: - items: type: integer type: array - type: 'null' title: Byyearday description: Days of the year to recur on. byweekno: anyOf: - items: type: integer type: array - type: 'null' title: Byweekno description: Week numbers of the year to recur on. bysetpos: anyOf: - items: type: integer type: array - type: 'null' title: Bysetpos description: >- Positions within the recurrence set to include (e.g. -1 for last occurrence, 1 for first). byhour: anyOf: - items: type: integer type: array - type: 'null' title: Byhour description: Hours of the day to recur on (0–23). byminute: anyOf: - items: type: integer type: array - type: 'null' title: Byminute description: Minutes of the hour to recur on (0–59). bysecond: anyOf: - items: type: integer type: array - type: 'null' title: Bysecond description: Seconds of the minute to recur on (0–59). wkst: anyOf: - type: integer - type: 'null' title: Wkst description: Week start day. 0=Monday, 6=Sunday. Defaults to Monday. type: object required: - freq title: RecurrenceConfig description: >- Shape of a recurrence configuration. Fields map directly to dateutil.rrule kwargs. See https://dateutil.readthedocs.io/en/stable/rrule.html for full documentation. The minimum required field is freq. AccessReviewDomainAppOutput: properties: id: type: string title: Id description: UUID of this access review domain app record. domain_app_id: type: string title: Domain App Id description: UUID of the domain app being reviewed. domain_app_name: type: string title: Domain App Name description: Display name of the domain app. domain_app_sources: items: type: string type: array title: Domain App Sources description: List of sources for the domain app. status: type: string enum: - IN_PREPARATION - ASSIGNING_REVIEWERS - IN_PROGRESS - COMPLETED - WAITING_FOR_MANUAL_ACTION - DELETED title: Status description: Status of this app within the review. review_type: anyOf: - $ref: '#/components/schemas/ReviewType' - type: 'null' description: 'What is being reviewed: ENTITLEMENTS or ACCOUNTS.' app_last_synced_at: anyOf: - type: string format: date-time - type: 'null' title: App Last Synced At description: When the app data was last synced. last_synced_at: anyOf: - type: string format: date-time - type: 'null' title: Last Synced At description: When this review's data was last synced. account_count: anyOf: - type: integer - type: 'null' title: Account Count description: Number of accounts in scope for this app. launched_at: anyOf: - type: string format: date-time - type: 'null' title: Launched At description: When this app's review was launched. completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: When this app's review was completed. scope_filters: anyOf: - items: type: object type: array - type: 'null' title: Scope Filters description: Scope filters applied to this app's review. type: object required: - id - domain_app_id - domain_app_name - domain_app_sources - status title: AccessReviewDomainAppOutput PositionalWeekday: properties: weekday: type: integer maximum: 6 minimum: 0 title: Weekday description: 0=Monday, 1=Tuesday, ..., 6=Sunday. 'n': anyOf: - type: integer - type: 'null' title: 'N' description: >- Which occurrence of the weekday within the period (e.g. 1 = first, -1 = last). None means every matching weekday. type: object required: - weekday title: PositionalWeekday description: >- A positional weekday for monthly/yearly recurrences — e.g. "the first Monday of the month" is ``{"weekday": 0, "n": 1}``. Mirrors ``dateutil.rrule.weekday``. A plain integer weekday (0–6) covers the common case; this richer form is only needed when an Nth-occurrence qualifier is present, which a bare int cannot express. ReviewType: type: string enum: - ACCOUNTS - ENTITLEMENTS title: ReviewType securitySchemes: HTTPBearer: type: http scheme: bearer ````