Sign in

v1

OpenAPI 3.1.02026-07-13632897.9 KB
Priority Guardian Priorities

Create Priority

Create a new priority with optional keyword choice.

If calendar_keyword is provided and available, uses it. If not provided, auto-assigns deterministically (P1 → P2 → P3).

Transactional Safety:

  • Uses SELECT FOR UPDATE to lock user's active priorities
  • Counts active priorities and rejects if >= 3
  • Assigns first available keyword from [P1, P2, P3]
  • Catches IntegrityError from partial unique index as fallback

Args: request: Validated priority creation request user_id: User ID from validated JWT (via X-User-ID header) session: Database session

Returns: 201 Created: Priority created successfully 401 Unauthorized: Missing/invalid X-User-ID 409 Conflict: MAX_PRIORITIES_REACHED or KEYWORD_CONFLICT 422 Validation Error: Invalid request data

Response format: { "success": true, "data": { "priority": { ... }, "active_priority_count": 1, "available_keywords": ["P2", "P3"] } }

post/api/priority-guardian/priorities

Headers

X-Internal-Secretstring nullable
X-User-IDstring nullable

Request body

namestring required

Priority name exactly as stated by user. Max 100 chars.

calendar_keyword'P1' | 'P2' | 'P3' nullable

Preferred keyword (P1/P2/P3). If not provided, auto-assigns first available.

type'deadline' | 'flexible' required

Priority type: deadline (hard end date) or flexible (ongoing time investment)

deadlinestring date nullable

Hard end date. Required when type=deadline. Must be in the future.

checkpoint_datestring date nullable

Evaluation checkpoint ~1 month out. Required when type=flexible.

initial_goal_textstring nullable

Initial goal text. Required when type=flexible. Max 200 chars. Creates first goal.

Example request

{
  "deadline": "2026-03-15",
  "name": "Launch marketing site",
  "type": "deadline"
}

Response

Successful Response

{"stackTrail":"paths:/api/priority-guardian/priorities:post:responses:201:content:application/json:schema","oasType":"schema","type":"unknown"}