{"openapi":"3.1.0","info":{"title":"quik.md API","version":"1.0.0","description":"REST endpoints for capture, search, projects, tags, voice, bulk operations, and webhooks. Open to free + Pro users; per-user rate limits (free: 60/min & 1000/day, Pro: 300/min & 10000/day) and a 402 pro_required gate on AI/voice/webhook routes."},"servers":[{"url":"https://quik.md"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"qk_"}},"responses":{"RateLimited":{"description":"Per-user rate limit hit. Includes Retry-After header. Free: 60/min, 1000/day. Pro: 300/min, 10000/day.","headers":{"Retry-After":{"description":"Seconds until the limit window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"rate_limited"},"message":{"type":"string"},"scope":{"type":"string","enum":["minute","day"]},"retry_after":{"type":"integer"},"limit_per_minute":{"type":"integer"},"limit_per_day":{"type":"integer"}}}}}},"ProRequired":{"description":"The endpoint requires a Pro plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"pro_required","message":"This feature requires quik.md Pro"}}}}},"schemas":{"Item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["note","todo"]},"title":{"type":"string"},"content_md":{"type":"string"},"is_completed":{"type":"boolean"},"status":{"type":"string","enum":["backlog","todo","doing","done","archived"]},"due_at":{"type":["string","null"],"format":"date-time"},"parent_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","project_id","type","is_completed","status"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}},"security":[{"bearerAuth":[]}],"paths":{"/api/v1/me":{"get":{"summary":"Current user","responses":{"200":{"description":"OK"}}}},"/api/v1/capture":{"post":{"summary":"Capture a free-form item","description":"Stores the item as-is. AI organizer is OFF by default — opt in with organize:true (Pro only). Agents that already parsed the input should leave organize unset.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"project_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["note","todo"],"default":"todo"},"organize":{"type":"boolean","default":false,"description":"Run the server AI organizer (auto-classify, route to project, parse due date). Pro-only. Counts against daily AI quota. Leave false if your agent already did this work."},"client_id":{"type":"string","format":"uuid"}},"required":["text"]}}}},"responses":{"200":{"description":"OK"}}}},"/api/v1/items":{"get":{"summary":"List items (cursor + since)","parameters":[{"in":"query","name":"since","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"limit","schema":{"type":"integer"}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/items/search":{"get":{"summary":"Search items","parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string"}},{"in":"query","name":"type","schema":{"type":"string"}},{"in":"query","name":"tag","schema":{"type":"string"}},{"in":"query","name":"project_id","schema":{"type":"string"}},{"in":"query","name":"is_completed","schema":{"type":"boolean"}},{"in":"query","name":"due_before","schema":{"type":"string"}},{"in":"query","name":"due_after","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"type":"integer"}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/v1/items/bulk":{"post":{"summary":"Bulk operations","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"op":{"type":"string","enum":["toggle","archive","unarchive","delete","move"]},"ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100},"payload":{"type":"object"}},"required":["op","ids"]}}}},"responses":{"200":{"description":"OK"}}}},"/api/v1/items/{id}":{"get":{"summary":"Read item","responses":{"200":{"description":"OK"}}},"patch":{"summary":"Update item","responses":{"200":{"description":"OK"}}},"delete":{"summary":"Delete item","responses":{"200":{"description":"OK"}}}},"/api/v1/items/{id}/toggle":{"post":{"summary":"Toggle completion","responses":{"200":{"description":"OK"}}}},"/api/v1/items/{id}/archive":{"post":{"summary":"Archive","responses":{"200":{"description":"OK"}}}},"/api/v1/items/{id}/unarchive":{"post":{"summary":"Unarchive","responses":{"200":{"description":"OK"}}}},"/api/v1/items/{id}/children":{"get":{"summary":"List subtasks","responses":{"200":{"description":"OK"}}}},"/api/v1/projects":{"get":{"summary":"List projects","responses":{"200":{"description":"OK"}}},"post":{"summary":"Create project","responses":{"200":{"description":"OK"}}}},"/api/v1/projects/{id}":{"get":{"responses":{"200":{"description":"OK"}}},"patch":{"responses":{"200":{"description":"OK"}}},"delete":{"responses":{"200":{"description":"OK"}}}},"/api/v1/projects/{id}/items":{"get":{"responses":{"200":{"description":"OK"}}}},"/api/v1/tags":{"get":{"summary":"List tags","responses":{"200":{"description":"OK"}}}},"/api/v1/voice/transcribe":{"post":{"summary":"Transcribe audio (Whisper) — Pro only","description":"multipart/form-data with `file` field (max 10 MB). Optional `language` field (BCP-47). Pro plan required.","responses":{"200":{"description":"OK"},"402":{"$ref":"#/components/responses/ProRequired"},"413":{"description":"Audio exceeds 10 MB limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/items/{id}/organize":{"post":{"summary":"Run AI organizer on an item — Pro only","responses":{"200":{"description":"OK"},"402":{"$ref":"#/components/responses/ProRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/webhooks":{"get":{"summary":"List webhooks","responses":{"200":{"description":"OK"}}},"post":{"summary":"Create webhook — Pro only","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["item.created","item.updated","item.completed","item.uncompleted","item.archived","item.deleted"]}},"description":{"type":"string"}},"required":["url","events"]}}}},"responses":{"201":{"description":"Created"},"400":{"description":"Invalid webhook URL. Must be public HTTPS; localhost / private CIDR / .local hostnames rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"$ref":"#/components/responses/ProRequired"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/webhooks/{id}":{"delete":{"responses":{"200":{"description":"OK"}}}}}}