---
title: "List Factory inbox notifications"
method: GET
path: "/factory-inbox"
tags: ["Factories", "Inbox Notifications"]
---

# List Factory inbox notifications

`GET /factory-inbox`

## Request

- Base URL: `https://app.warp.dev/api/v1`
- URL: `https://app.warp.dev/api/v1/factory-inbox`
- Auth: HTTP bearer

List unresolved notifications across factories authorized for the
authenticated principal and active team. The default `mine` scope
preserves the personal Inbox and requires user credentials. The
`team` scope lists notifications assigned to any recipient and
can be used by user or agent credentials. Personal read state
(`is_read`) is included only in `mine` scope and omitted in `team`
scope, including when filtering by recipient.

## Query parameters

- `scope` 'mine' | 'team': Personal or team-wide Factory Inbox visibility.
- `factory_uid` string
- `recipient_uid` string
- `limit` integer
- `cursor` string

## Headers

- `X-Warp-Team-Uid` string

## Response `200`

One page of inbox notifications.

- ListFactoryInboxResponse
  - `items` FactoryInboxItem[], required
    - `notification_uid` string, required: Identifier accepted by the dismiss endpoint.
    - `factory_uid` string, required
    - `factory_task_uid` string, required
    - `title` string, required: Notification headline.
    - `stage` 'TRIAGE' | 'SPEC' | 'IMPLEMENT' | 'REVIEW' | 'COMPLETE' | 'CANCELLED', required: Lifecycle stage of a factory task, mirroring the seeded factory agent roles plus the terminal COMPLETE and CANCELLED states. COMPLETE and CANCELLED are terminal in intent but not enforced: any stage may be written explicitly at any time. CANCELLED is set automatically when the task's current top-level run is cancelled, regardless of that run's agent type.
    - `kind` 'question' | 'answer_question' | 'spec_review' | 'pr_review' | 'blocked' | 'failed', required: The action requested by a Factory notification.
    - `is_read` boolean: Whether the authenticated user has read this notification. Always present in `mine` scope, including when false. Omitted in `team` scope, even when filtering by recipient.
    - `description` string: Notification body, when present.
    - `questions` FactoryAttentionQuestion[]
      - `id` string, required
      - `question` string, required
      - `type` 'single_select' | 'multi_select', required
      - `options` string[], required
      - `recommended_option_index` integer
    - `origin_link` string: Server-derived link back to the task's origin, when present.
    - `url` string: Legacy first artifact URL supplied by a review notification.
    - `urls` string[]: Legacy artifact URLs; prefer artifacts for links and titles.
    - `artifacts` FactoryInboxArtifact[]: Ordered artifact links with optional provider PR/MR titles.
      - `url` string, required: Artifact URL.
      - `title` string: Known provider PR/MR title, when available.
    - `run_id` string: Producing run ID from factory_task_notifications.created_by_run_id. Present when the producing run is known.
    - `created_at` string, date-time, required: Notification declaration time.
    - `recipients` FactoryInboxRecipient[], required: Live, undismissed recipients for this shared notification, sorted deterministically. Slack routing and personal dismissal state are not exposed.
      - `uid` string, required: Public Warp user UID.
      - `email` string, email: Recipient email, when available.
  - `page_info` PageInfo, required
    - `has_next_page` boolean, required: Whether there are more results available
    - `next_cursor` string: Opaque cursor for fetching the next page

## Other responses

- `400`: Invalid scope, limit, cursor, or principal for the requested scope
- `401`: Authentication required
- `403`: Factory access is not enabled for the authenticated principal
- `404`: Factory task APIs are not available
- `500`: Internal server error

## Changes

- **2026-10-21** `7ee3ba55debc`: 2 info
  - api tag `factory-notifications` added
  - api tag `factory` removed
- **2026-10-15** `f4630aae17ba`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/warp/apis/oz-agent-api/changes/factory-inbox/get.md)

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) - [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/warp/apis/oz-agent-api/revisions/4b5d145669be?raw)