{"openapi":"3.1.0","info":{"title":"DeeCee.ai Agentic API","version":"1.0.0-lean","description":"Structured decision intelligence for AI agents — turn scattered information into a defensible decision brief using DACI, SPADE, or helix frameworks."},"servers":[{"url":"https://api.deecee.ai"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Decisions","description":"Create, list, and develop decision briefs."},{"name":"Frameworks","description":"Decision frameworks (DACI, SPADE, helix)."},{"name":"Use Cases","description":"Optional guided-interview templates."},{"name":"Jobs","description":"Poll async job status for interview/analysis calls."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key in dc_live_... / dc_test_... format, from /settings/api-keys."}},"schemas":{"DecisionSummary":{"type":"object","properties":{"decision_id":{"type":"string"},"title":{"type":"string"},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["decision_id","title","framework","status","created_at"]},"DecisionDetail":{"type":"object","properties":{"decision_id":{"type":"string"},"title":{"type":"string"},"context":{"type":"string"},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"complexity":{"type":"string"},"status":{"type":"string"},"stages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"content":{"type":"string"}},"required":["name","content"]}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["decision_id","title","context","framework","complexity","status","stages","created_at","updated_at"]},"Recommendation":{"type":"object","properties":{"decision_id":{"type":"string"},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"stage_name":{"type":"string","description":"Name of the framework's final stage (e.g. SPADE's 'Explain')."},"recommendation":{"type":"string"}},"required":["decision_id","framework","stage_name","recommendation"]},"Framework":{"type":"object","properties":{"id":{"type":"string","enum":["DACI","SPADE","helix"]},"name":{"type":"string"},"description":{"type":"string"}},"required":["id","name","description"]},"UseCase":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["free","pro"]}},"required":["id","title","description","tags","tier"]},"Job":{"type":"object","properties":{"job_id":{"type":"string"},"tool_name":{"type":"string","enum":["interview_next_question","generate_framework_analysis","advance_stage","synthesize_context","assess_decision","attach_document","refine_stage","export_brief"]},"status":{"type":"string","enum":["pending","running","completed","failed"]},"output":{"description":"Present once status is 'completed'. Shape depends on tool_name — interview_next_question returns { response, credits_used, credits_remaining }; generate_framework_analysis returns { stage_count }; advance_stage returns { stage_name, stage_content, stage_index, total_stages, is_complete, tokens_used }; synthesize_context returns { context, matched_use_case }; assess_decision returns { complexity, framework, suggested_title, reasoning, confidence, overall_score }; attach_document returns { upload_id, file_name, file_size, mime_type, processing_status }; refine_stage returns { stage_index, stage_title, original_content, revised_content }; export_brief returns { format, file_name, content } for markdown or { format, file_name, url } for docx/pdf."},"error":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}},"required":["job_id","tool_name","status","created_at"]},"StageAdvance":{"type":"object","properties":{"stage_name":{"type":"string","description":"Present unless is_complete is true with no new stage run."},"stage_content":{"type":"string"},"stage_index":{"type":"integer","description":"0-based index of the stage just run (or total_stages if already complete)."},"total_stages":{"type":"integer"},"is_complete":{"type":"boolean","description":"True once this was the framework's final stage."},"tokens_used":{"type":"integer"},"job_id":{"type":"string","description":"Present on the initial 202 response only — poll GET /v1/jobs/{id} for the fields above."}},"required":["is_complete"]},"SynthesizedContext":{"type":"object","properties":{"context":{"type":"string"},"matched_use_case":{"type":"string","nullable":true,"description":"Matched use-case template id from the existing catalog, or null if none fit well."},"job_id":{"type":"string","description":"Present on the initial 202 response only — poll GET /v1/jobs/{id} for the fields above."}},"required":[]},"DecisionAssessment":{"type":"object","properties":{"complexity":{"type":"string","enum":["simple","moderate","complex"]},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"suggested_title":{"type":"string"},"reasoning":{"type":"string"},"confidence":{"type":"string","enum":["high","medium","low"]},"overall_score":{"type":"integer","description":"Weighted complexity score, 1-100."},"job_id":{"type":"string","description":"Present on the initial 202 response only — poll GET /v1/jobs/{id} for the fields above."}},"required":[]},"DecisionSetup":{"type":"object","properties":{"title":{"type":"string"},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"complexity":{"type":"string","enum":["simple","moderate","complex"]}},"required":[]},"DocumentAttachment":{"type":"object","properties":{"upload_id":{"type":"string"},"file_name":{"type":"string"},"file_size":{"type":"integer"},"mime_type":{"type":"string"},"processing_status":{"type":"string","enum":["completed","failed"]}},"required":["upload_id","file_name","file_size","mime_type","processing_status"]},"StageRefinement":{"type":"object","properties":{"stage_index":{"type":"integer"},"stage_title":{"type":"string"},"original_content":{"type":"string"},"revised_content":{"type":"string"}},"required":["stage_index","stage_title","original_content","revised_content"]},"StageRevisionApplied":{"type":"object","properties":{"stage_index":{"type":"integer"},"stage_title":{"type":"string"},"version":{"type":"string","description":"New stage version, e.g. \"1.2\"."}},"required":["stage_index","stage_title","version"]},"BriefExport":{"type":"object","properties":{"format":{"type":"string","enum":["markdown","docx","pdf"]},"file_name":{"type":"string"},"content":{"type":"string","description":"Markdown only — the full brief inline."},"url":{"type":"string","description":"DOCX/PDF only — download URL. Treat as sensitive."}},"required":["format","file_name"]},"Error":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}},"paths":{"/v1/decisions":{"post":{"operationId":"start_decision_brief","tags":["Decisions"],"summary":"Create a new decision","description":"Use this when a user says: 'help me decide whether to...' or 'I need to make a decision about...'. Creates a new decision brief that can then be developed via /interview and /analyze.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"decision_title":{"description":"A short, clear title for the decision being made (5-10 words).","type":"string","minLength":1,"maxLength":200},"decision_context":{"description":"The full background for this decision: what's being decided, why, and any constraints or stakeholders already known. Optional — if the context isn't known yet, omit this and use interview_next_question followed by synthesize_context to build it up conversationally instead.","type":"string","maxLength":20000},"framework_hint":{"description":"Optional. If omitted, the caller should use list_frameworks/GET /v1/frameworks guidance to pick one, or default to DACI for simple tactical decisions.","type":"string","enum":["DACI","SPADE","helix"]},"use_case_id":{"description":"Optional. An id from list_use_cases/GET /v1/use-cases. When set, interview_next_question uses that use case's guiding questions instead of a generic prompt for a more targeted conversation. Some use cases require a Pro/Beta subscription.","type":"string"}},"required":["decision_title"],"additionalProperties":false}}}},"responses":{"201":{"description":"Decision created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"decision_id":{"type":"string"},"title":{"type":"string"},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["decision_id","title","framework","status","created_at"]}},"required":["success","data"]}}}},"400":{"description":"Validation error, or unknown use_case_id","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"403":{"description":"use_case_id requires a Pro or Beta subscription","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}},"get":{"operationId":"list_decisions","tags":["Decisions"],"summary":"List past decisions","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum number of decisions to return (1-100, default 20)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque pagination cursor from a previous response's next_cursor field."}],"responses":{"200":{"description":"Paginated list of decisions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"decision_id":{"type":"string"},"title":{"type":"string"},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["decision_id","title","framework","status","created_at"]}},"next_cursor":{"type":"string","nullable":true}},"required":["success","data"]}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}":{"get":{"operationId":"get_decision","tags":["Decisions"],"summary":"Fetch a decision's current state and any completed analysis","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"responses":{"200":{"description":"Decision detail","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"decision_id":{"type":"string"},"title":{"type":"string"},"context":{"type":"string"},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"complexity":{"type":"string"},"status":{"type":"string"},"stages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"content":{"type":"string"}},"required":["name","content"]}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["decision_id","title","context","framework","complexity","status","stages","created_at","updated_at"]}},"required":["success","data"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/recommendation":{"get":{"operationId":"get_recommendation","tags":["Decisions"],"summary":"Get the framework's final-stage recommendation content","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"responses":{"200":{"description":"Recommendation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"decision_id":{"type":"string"},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"stage_name":{"type":"string","description":"Name of the framework's final stage (e.g. SPADE's 'Explain')."},"recommendation":{"type":"string"}},"required":["decision_id","framework","stage_name","recommendation"]}},"required":["success","data"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Not found or analysis not complete","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/interview":{"post":{"operationId":"interview_next_question","tags":["Decisions"],"summary":"Submit an answer, get the next interview question","description":"Use this when a user wants to talk through a decision conversationally rather than provide all context up front.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"message":{"description":"The user's latest answer or message in the interview. On the first call, this can be an initial statement of the problem.","type":"string","minLength":1,"maxLength":10000}},"required":["message"],"additionalProperties":false}}}},"responses":{"202":{"description":"Job accepted — poll GET /v1/jobs/{id}","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"job_id":{"type":"string"}},"required":["job_id"]}},"required":["success","data"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/synthesize-context":{"post":{"operationId":"synthesize_context","tags":["Decisions"],"summary":"Synthesize a decision context from the interview conversation","description":"Call once interview_next_question has gathered enough signal. Synthesizes a coherent context from the conversation and saves it to the decision. Also attempts to classify the conversation against the existing use-case catalog for parity/analytics — falls back to a synthetic id if nothing matches well, without forcing the interview into that template's shape.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"responses":{"202":{"description":"Job accepted — poll GET /v1/jobs/{id}","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"context":{"type":"string"},"matched_use_case":{"type":"string","nullable":true,"description":"Matched use-case template id from the existing catalog, or null if none fit well."},"job_id":{"type":"string","description":"Present on the initial 202 response only — poll GET /v1/jobs/{id} for the fields above."}},"required":[]}},"required":["success","data"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/context":{"post":{"operationId":"update_decision_context","tags":["Decisions"],"summary":"Directly replace a decision's context","description":"E.g. after reviewing/editing the output of synthesize_context. Synchronous, no LLM call.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"context":{"description":"Replacement decision context, e.g. after reviewing/editing the output of synthesize_context.","type":"string","minLength":1,"maxLength":20000}},"required":["context"],"additionalProperties":false}}}},"responses":{"200":{"description":"Context updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"context":{"type":"string"}},"required":["context"]}},"required":["success","data"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/assess":{"post":{"operationId":"assess_decision","tags":["Decisions"],"summary":"Assess a decision's context and recommend complexity/framework/title","description":"Read-only — does not modify the decision. Show the recommendation to the user and get their explicit confirmation (or overrides) before committing it via POST /v1/decisions/{id}/setup — do not apply it or start analysis unconfirmed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"responses":{"202":{"description":"Job accepted — poll GET /v1/jobs/{id}","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"complexity":{"type":"string","enum":["simple","moderate","complex"]},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"suggested_title":{"type":"string"},"reasoning":{"type":"string"},"confidence":{"type":"string","enum":["high","medium","low"]},"overall_score":{"type":"integer","description":"Weighted complexity score, 1-100."},"job_id":{"type":"string","description":"Present on the initial 202 response only — poll GET /v1/jobs/{id} for the fields above."}},"required":[]}},"required":["success","data"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/setup":{"post":{"operationId":"apply_decision_setup","tags":["Decisions"],"summary":"Commit a decision's title/framework/complexity","description":"Typically the recommendation from POST /v1/decisions/{id}/assess, as-is or with overrides — only call this after the user has confirmed it. Synchronous, no LLM call. Once applied, ask the user whether they want stage-by-stage (/advance) or all-at-once (/analyze) analysis before starting it.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"title":{"description":"Final title — typically from assess_decision's suggested_title, or a user override.","type":"string","minLength":1,"maxLength":200},"framework":{"description":"Final framework — typically from assess_decision's recommendation, or a user override.","type":"string","enum":["DACI","SPADE","helix"]},"complexity":{"description":"Final complexity level — typically from assess_decision's recommendation, or a user override.","type":"string","enum":["simple","moderate","complex"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Setup applied","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"title":{"type":"string"},"framework":{"type":"string","enum":["DACI","SPADE","helix"]},"complexity":{"type":"string","enum":["simple","moderate","complex"]}},"required":[]}},"required":["success","data"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/documents":{"post":{"operationId":"attach_document","tags":["Decisions"],"summary":"Attach a document to a decision","description":"Downloads the file from file_url, runs the same security validation and storage-quota checks as the web app's upload flow, then extracts text and generates embeddings for retrieval during analysis. Returns a job_id — poll GET /v1/jobs/{id}. Free (no LLM call), subject to storage quota.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"file_url":{"description":"A URL the server can fetch the file from (must be publicly reachable, or at least reachable by the server — e.g. a signed URL). Direct base64 upload isn't supported; host the file somewhere fetchable first.","type":"string","format":"uri"},"file_name":{"description":"Original file name, including extension.","type":"string","minLength":1,"maxLength":255},"mime_type":{"description":"The file's MIME type, e.g. application/pdf. Supported: PDF, DOCX, PPTX, XLSX, CSV, TXT, and JPEG/PNG/GIF/WebP images. Max 25MB.","type":"string"}},"required":["file_url","file_name","mime_type"],"additionalProperties":false}}}},"responses":{"202":{"description":"Job accepted — poll GET /v1/jobs/{id}","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"upload_id":{"type":"string"},"file_name":{"type":"string"},"file_size":{"type":"integer"},"mime_type":{"type":"string"},"processing_status":{"type":"string","enum":["completed","failed"]}},"required":["upload_id","file_name","file_size","mime_type","processing_status"]}},"required":["success","data"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/refine":{"post":{"operationId":"refine_stage","tags":["Decisions"],"summary":"Ask the AI to revise a completed stage (does not save)","description":"Returns a job_id — poll GET /v1/jobs/{id} for original_content and revised_content. Does NOT modify the decision: show the revision to the user, then commit it (as-is or edited) via POST /v1/decisions/{id}/refine/apply.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"stage_index":{"description":"Zero-based index of the completed stage to refine (see get_decision for stages).","type":"integer","minimum":0,"maximum":9007199254740991},"instructions":{"description":"How to revise the stage, e.g. \"Make it more concise\" or \"Add a risk analysis\".","type":"string","minLength":1,"maxLength":5000}},"required":["stage_index","instructions"],"additionalProperties":false}}}},"responses":{"202":{"description":"Job accepted — poll GET /v1/jobs/{id}","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"stage_index":{"type":"integer"},"stage_title":{"type":"string"},"original_content":{"type":"string"},"revised_content":{"type":"string"}},"required":["stage_index","stage_title","original_content","revised_content"]}},"required":["success","data"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/refine/apply":{"post":{"operationId":"apply_stage_revision","tags":["Decisions"],"summary":"Commit revised content to a stage","description":"Typically revised_content from POST /v1/decisions/{id}/refine, as-is or edited — only call after the user approves it. Overwrites the stage and records a new version in its history. Synchronous, no LLM call.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"stage_index":{"description":"Zero-based index of the stage to overwrite.","type":"integer","minimum":0,"maximum":9007199254740991},"content":{"description":"The revised stage content to save — typically revised_content from refine_stage, as-is or edited by the user.","type":"string","minLength":1,"maxLength":100000}},"required":["stage_index","content"],"additionalProperties":false}}}},"responses":{"200":{"description":"Revision applied","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"stage_index":{"type":"integer"},"stage_title":{"type":"string"},"version":{"type":"string","description":"New stage version, e.g. \"1.2\"."}},"required":["stage_index","stage_title","version"]}},"required":["success","data"]}}}},"400":{"description":"Validation error, or invalid stage_index","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/export":{"post":{"operationId":"export_brief","tags":["Decisions"],"summary":"Export a decision brief as Markdown, DOCX, or PDF","description":"Returns a job_id — poll GET /v1/jobs/{id}. Markdown comes back inline as content; DOCX/PDF as a download url (treat the URL as sensitive). PDF is available on every plan (Free users get a branded footer); Markdown and DOCX require Pro, Beta, or Admin. Free (no LLM call).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"format":{"description":"Export format. Requires a Pro, Beta, or Admin subscription.","type":"string","enum":["markdown","docx","pdf"]}},"required":["format"],"additionalProperties":false}}}},"responses":{"202":{"description":"Job accepted — poll GET /v1/jobs/{id}","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"format":{"type":"string","enum":["markdown","docx","pdf"]},"file_name":{"type":"string"},"content":{"type":"string","description":"Markdown only — the full brief inline."},"url":{"type":"string","description":"DOCX/PDF only — download URL. Treat as sensitive."}},"required":["format","file_name"]}},"required":["success","data"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"403":{"description":"Format requires a Pro, Beta, or Admin subscription","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/advance":{"post":{"operationId":"advance_stage","tags":["Decisions"],"summary":"Run exactly the next framework stage for a decision","description":"The recommended way to run analysis: call this repeatedly (checking is_complete) to work through a decision one stage at a time. The stage index and prior-stage context are derived server-side — no request body needed. Prefer this over /analyze, which runs every stage in one request and can silently exceed the request time limit on longer frameworks.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"responses":{"200":{"description":"Already complete — no stage was run","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"stage_name":{"type":"string","description":"Present unless is_complete is true with no new stage run."},"stage_content":{"type":"string"},"stage_index":{"type":"integer","description":"0-based index of the stage just run (or total_stages if already complete)."},"total_stages":{"type":"integer"},"is_complete":{"type":"boolean","description":"True once this was the framework's final stage."},"tokens_used":{"type":"integer"},"job_id":{"type":"string","description":"Present on the initial 202 response only — poll GET /v1/jobs/{id} for the fields above."}},"required":["is_complete"]}},"required":["success","data"]}}}},"202":{"description":"Job accepted — poll GET /v1/jobs/{id}","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"stage_name":{"type":"string","description":"Present unless is_complete is true with no new stage run."},"stage_content":{"type":"string"},"stage_index":{"type":"integer","description":"0-based index of the stage just run (or total_stages if already complete)."},"total_stages":{"type":"integer"},"is_complete":{"type":"boolean","description":"True once this was the framework's final stage."},"tokens_used":{"type":"integer"},"job_id":{"type":"string","description":"Present on the initial 202 response only — poll GET /v1/jobs/{id} for the fields above."}},"required":["is_complete"]}},"required":["success","data"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/decisions/{id}/analyze":{"post":{"operationId":"generate_framework_analysis","tags":["Decisions"],"summary":"Run the full framework analysis for a decision in one request","description":"Prefer POST /v1/decisions/{id}/advance instead — it runs one stage at a time and won't silently stall on longer frameworks. Use this only for short frameworks where a single request comfortably fits the time limit.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"responses":{"202":{"description":"Job accepted — poll GET /v1/jobs/{id}","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"job_id":{"type":"string"}},"required":["job_id"]}},"required":["success","data"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Decision not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/frameworks":{"get":{"operationId":"list_frameworks","tags":["Frameworks"],"summary":"List available decision frameworks (DACI, SPADE, helix)","responses":{"200":{"description":"Framework metadata","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["DACI","SPADE","helix"]},"name":{"type":"string"},"description":{"type":"string"}},"required":["id","name","description"]}}},"required":["success","data"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/use-cases":{"get":{"operationId":"list_use_cases","tags":["Use Cases"],"summary":"List use-case templates for start_decision_brief's optional use_case_id","responses":{"200":{"description":"Use case metadata","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["free","pro"]}},"required":["id","title","description","tags","tier"]}}},"required":["success","data"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}},"/v1/jobs/{id}":{"get":{"operationId":"get_job","tags":["Jobs"],"summary":"Poll an async job's status and result","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Decision or job ID."}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"job_id":{"type":"string"},"tool_name":{"type":"string","enum":["interview_next_question","generate_framework_analysis","advance_stage","synthesize_context","assess_decision","attach_document","refine_stage","export_brief"]},"status":{"type":"string","enum":["pending","running","completed","failed"]},"output":{"description":"Present once status is 'completed'. Shape depends on tool_name — interview_next_question returns { response, credits_used, credits_remaining }; generate_framework_analysis returns { stage_count }; advance_stage returns { stage_name, stage_content, stage_index, total_stages, is_complete, tokens_used }; synthesize_context returns { context, matched_use_case }; assess_decision returns { complexity, framework, suggested_title, reasoning, confidence, overall_score }; attach_document returns { upload_id, file_name, file_size, mime_type, processing_status }; refine_stage returns { stage_index, stage_title, original_content, revised_content }; export_brief returns { format, file_name, content } for markdown or { format, file_name, url } for docx/pdf."},"error":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}},"required":["job_id","tool_name","status","created_at"]}},"required":["success","data"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","description":"Machine-readable error code (e.g. VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED, PAYMENT_REQUIRED)."}},"required":["success","error","code"]}}}}}}}},"x-list-decisions-query-schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"limit":{"description":"Maximum number of decisions to return (1-100, default 20).","default":20,"type":"integer","minimum":1,"maximum":100},"cursor":{"description":"Opaque pagination cursor from a previous response's next_cursor field.","type":"string"}},"required":["limit"],"additionalProperties":false}}