{"openapi":"3.1.0","info":{"title":"GET /api/v1/attention","version":"1.0.0","description":"List attention items"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/attention":{"get":{"tags":["attention"],"summary":"List attention items","description":"Get the merged list of inbox messages and live alerts. Items are sorted with action-required first, then by priority, then newest first. Inbox messages support cursor pagination; live alerts are always returned in full on the first page.","operationId":"list_attention","parameters":[{"name":"action_required","in":"query","required":false,"schema":{"type":"boolean","description":"Only show items requiring user action.","default":false,"title":"Action Required"},"description":"Only show items requiring user action."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by category.","title":"Category"},"description":"Filter by category."},{"name":"priority","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by priority.","title":"Priority"},"description":"Filter by priority."},{"name":"entity_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by entity type.","title":"Entity Type"},"description":"Filter by entity type."},{"name":"unread_only","in":"query","required":false,"schema":{"type":"boolean","description":"Hide read inbox messages and dismissed live alerts.","default":false,"title":"Unread Only"},"description":"Hide read inbox messages and dismissed live alerts."},{"name":"include_live","in":"query","required":false,"schema":{"type":"boolean","description":"Include live (computed) alerts alongside inbox rows.","default":true,"title":"Include Live"},"description":"Include live (computed) alerts alongside inbox rows."},{"name":"client_view","in":"query","required":false,"schema":{"type":"boolean","description":"If true, action URLs use the ``/client`` shell prefix instead of ``/books``.","default":false,"title":"Client View"},"description":"If true, action URLs use the ``/client`` shell prefix instead of ``/books``."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Inbox pagination cursor.","title":"Cursor"},"description":"Inbox pagination cursor."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Max inbox items per page.","default":20,"title":"Limit"},"description":"Max inbox items per page."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_AttentionListResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"list_attention_api_v1_attention_get"}}},"components":{"schemas":{"AttentionCategory":{"type":"string","enum":["action_required","alert","info","announcement","system"],"title":"AttentionCategory","description":"Functional category of an attention item."},"AttentionItem":{"properties":{"id":{"type":"string","title":"Id","description":"Opaque identifier. Format: ``inbox:<uuid>`` for persistent messages or ``live:<alert_id>`` for computed signals."},"source":{"$ref":"#/components/schemas/AttentionSource"},"category":{"$ref":"#/components/schemas/AttentionCategory"},"priority":{"$ref":"#/components/schemas/AttentionPriority"},"title":{"type":"string","title":"Title"},"body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Body","description":"Optional longer description of the item."},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon","description":"Icon hint for the frontend (CSS icon name)."},"action_required":{"type":"boolean","title":"Action Required","description":"Whether resolving this item requires user action. Items with ``action_required=True`` appear in the Action Items dashboard card; all items appear in the notification bell.","default":false},"action_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action Url","description":"In-app deep link the user should follow to resolve."},"action_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action Label","description":"Short label for the action button (e.g. 'Review')."},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type","description":"Related entity kind, e.g. ``invoices``, ``bills``."},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id","description":"Related entity ID if applicable."},"created_at":{"type":"string","format":"date-time","title":"Created At"},"read":{"type":"boolean","title":"Read","description":"True if the item is read (inbox) or has been dismissed by the user (live).","default":false},"starred":{"type":"boolean","title":"Starred","description":"Inbox-only star state.","default":false},"dismissible":{"type":"boolean","title":"Dismissible","description":"Whether the user can mark this read/dismiss. Always true for inbox; live items are dismissible per-user via user.props.","default":true},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Optional source-specific extra data."}},"type":"object","required":["id","source","category","priority","title","created_at"],"title":"AttentionItem","description":"A single thing the user should pay attention to.\n\nThe ``source`` field tells the client whether the item is a real inbox row\n(``inbox``) — which supports archive/star/delete — or a computed live\nsignal (``live``) which can only be read or dismissed."},"AttentionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/AttentionItem"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Inbox cursor for the next page (live items are not paginated)."},"has_more":{"type":"boolean","title":"Has More","description":"True if more inbox messages exist.","default":false}},"type":"object","required":["items"],"title":"AttentionListResponse","description":"Paginated list of attention items."},"AttentionPriority":{"type":"string","enum":["urgent","high","normal","low"],"title":"AttentionPriority","description":"Priority level. Sort order is urgent > high > normal > low."},"AttentionSource":{"type":"string","enum":["inbox","live"],"title":"AttentionSource","description":"Where an attention item came from."},"SuccessEnvelope_AttentionListResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/AttentionListResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[AttentionListResponse]"},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}