---
title: "Run Focus Mode"
method: POST
path: "/api/focused/tools/run_focus_mode"
tags: ["focused-tools"]
---

# Run Focus Mode

`POST /api/focused/tools/run_focus_mode`

Activate or deactivate Apple Focus Mode via iOS Shortcuts URL scheme.

This endpoint:
- Generates a shortcut:// URL for the ChatGPT client to open
- Updates database state (actual_start, actual_end)
- Schedules auto-deactivation via Celery (when duration_minutes provided)

The backend generates shortcut_url but does NOT invoke it.
ChatGPT client opens the URL on user's device.

MVP1 Constraint:
    - Manual activation only supports "start now", not "start later"
    - Future-scheduled activations must be handled via calendar blocks
    - SDK layer is responsible for intercepting future-time intents

Identity Source (Increment 7D):
    - Primary: X-User-ID header (from MCP after JWT validation)
    - No fallback (user_id is required for focus mode)

Request Body:
    - action: "on" or "off"
    - trigger_source: "calendar" or "user"
    - session_id: UUID (required for calendar-triggered activation)
    - session_title: Session title (optional, default "Focus Session")
    - duration_minutes: Session duration in minutes (1-480)
        * For manual activation (trigger_source="user"): REQUIRED
        * For calendar-triggered activation: optional (uses event end time)
    - user_confirmation: Required for action="on"

Returns:
    {
        "success": True,
        "data": {
            "shortcut_status": "success" | "failed" | "already_active" | "already_inactive",
            "shortcut_url": "shortcuts://...",
            "session_title": "Focus Session",
            "start_time": "2025-11-26T10:00:00Z",
            "end_time": "2025-11-26T12:00:00Z" | null,
            "message": "Focus Mode activated successfully.",
            "error_details": null | "missing_duration"
        }
    }

## Request body

- RunFocusModeRequest — Request model for run_focus_mode endpoint (Increment 11). Activates or deactivates Apple Focus Mode via iOS Shortcuts URL scheme.
  - `action` string, required — 'on' to activate Focus Mode, 'off' to deactivate
  - `trigger_source` string, required — 'calendar' (from detected event) or 'user' (manual)
  - `session_id` string, nullable — Focus session UUID (required for calendar-triggered activation)
  - `session_title` string, nullable — Session title (e.g., 'Work', 'Do Not Disturb'). Default: 'Work'
  - `duration_minutes` integer, nullable — Auto-deactivate after this many minutes (1-480)
  - `user_confirmation` boolean, nullable — User confirmed activation. Required when action='on'

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/priority-guard/apis/priority-guardian.md) · [All operations](https://skmtc.dev/priority-guard/apis/priority-guardian/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/priority-guard/priority-guardian/revisions/8579218b716d/schema)