{"components":{"schemas":{"AnonymousCtaConfig":{"additionalProperties":false,"description":"Optional research-publication overrides for the signed-out report CTA.","properties":{"banner_message":{"anyOf":[{"maxLength":240,"minLength":1,"type":"string"},{"type":"null"}],"title":"Banner Message"},"button_label":{"anyOf":[{"maxLength":80,"minLength":1,"type":"string"},{"type":"null"}],"deprecated":true,"description":"Deprecated alias for primary_button_label","title":"Button Label"},"default_cadence":{"anyOf":[{"enum":["daily","weekly","monthly"],"type":"string"},{"type":"null"}],"description":"Pre-selected loop cadence for the agent_form variant's embedded form","title":"Default Cadence"},"description":{"anyOf":[{"maxLength":400,"minLength":1,"type":"string"},{"type":"null"}],"title":"Description"},"display_mode":{"anyOf":[{"enum":["on_load","on_scroll"],"type":"string"},{"type":"null"}],"description":"When the CTA opens: on_load shows it immediately (sample-first framing); on_scroll (the default when unset) waits for trigger_scroll_percent","title":"Display Mode"},"display_mode_experiment":{"default":false,"description":"When true and style_variant is agent_form, split signed-out visitors 50/50 between on_load and banner_first CTA timing, sticky per visitor, and emit the assignment on every shell analytics event and CTA handoff URL","title":"Display Mode Experiment","type":"boolean"},"eyebrow":{"anyOf":[{"maxLength":80,"minLength":1,"type":"string"},{"type":"null"}],"title":"Eyebrow"},"indexable":{"default":false,"description":"Allow search engines to index this publication's shell page (robots meta + canonical link). Independent of the admin-only job.is_crawlable gate; either one being true makes the page indexable.","title":"Indexable","type":"boolean"},"primary_button_label":{"anyOf":[{"maxLength":80,"minLength":1,"type":"string"},{"type":"null"}],"title":"Primary Button Label"},"sample_inputs":{"anyOf":[{"items":{"$ref":"#/components/schemas/AnonymousCtaSampleInput"},"maxItems":8,"type":"array"},{"type":"null"}],"description":"Labeled inputs the sample report was produced with, shown by the sample_intro variant","title":"Sample Inputs"},"secondary_button_label":{"anyOf":[{"maxLength":80,"minLength":1,"type":"string"},{"type":"null"}],"title":"Secondary Button Label"},"style_variant":{"anyOf":[{"enum":["editorial_invitation","founders_desk","executive_memo","quiet_sidecar","reading_room_sheet","sample_intro","agent_form"],"type":"string"},{"type":"null"}],"description":"Visual treatment for the signed-out report CTA","title":"Style Variant"},"title":{"anyOf":[{"maxLength":120,"minLength":1,"type":"string"},{"type":"null"}],"title":"Title"},"trigger_scroll_percent":{"anyOf":[{"maximum":75.0,"minimum":5.0,"type":"integer"},{"type":"null"}],"description":"Report scroll depth that opens the CTA","title":"Trigger Scroll Percent"}},"title":"AnonymousCtaConfig","type":"object"},"AnonymousCtaSampleInput":{"additionalProperties":false,"description":"One labeled input shown by the sample_intro CTA (\"with these inputs: …\").","properties":{"label":{"maxLength":80,"minLength":1,"title":"Label","type":"string"},"value":{"maxLength":200,"minLength":1,"title":"Value","type":"string"}},"required":["label","value"],"title":"AnonymousCtaSampleInput","type":"object"},"AttachedFile":{"description":"One uploaded input file.","properties":{"content_type":{"description":"MIME type as reported by the upload, or ``application/octet-stream`` when unknown.","title":"Content Type","type":"string"},"filename":{"description":"Path-safe filename committed to the workspace.","title":"Filename","type":"string"},"size_bytes":{"description":"File size in bytes.","title":"Size Bytes","type":"integer"}},"required":["filename","size_bytes","content_type"],"title":"AttachedFile","type":"object"},"AttachmentImportRequest":{"description":"Create an attachment from a URL the server fetches (SSRF-guarded).","properties":{"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stored filename; inferred from the URL path when omitted.","title":"Filename"},"source_url":{"description":"Public http(s) URL to fetch server-side. Private, loopback, link-local (cloud metadata), and reserved addresses are blocked; redirects are re-validated per hop; downloads are size-capped.","title":"Source Url","type":"string"}},"required":["source_url"],"title":"AttachmentImportRequest","type":"object"},"BatchCreditEstimateResponse":{"properties":{"credits_per_row":{"title":"Credits Per Row","type":"integer"},"downgraded":{"default":false,"title":"Downgraded","type":"boolean"},"effort":{"title":"Effort","type":"string"},"requested_effort":{"title":"Requested Effort","type":"string"},"rows":{"title":"Rows","type":"integer"},"total_credits":{"title":"Total Credits","type":"integer"}},"required":["rows","effort","requested_effort","credits_per_row","total_credits"],"title":"BatchCreditEstimateResponse","type":"object"},"BatchResultsResponse":{"properties":{"agent_key":{"title":"Agent Key","type":"string"},"batch_id":{"title":"Batch Id","type":"string"},"batch_name":{"title":"Batch Name","type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"credits_per_row":{"default":0,"title":"Credits Per Row","type":"integer"},"credits_spent":{"default":0,"title":"Credits Spent","type":"integer"},"paused_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paused Reason"},"processed_rows":{"title":"Processed Rows","type":"integer"},"processing_completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Completed At"},"processing_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Started At"},"processing_status":{"title":"Processing Status","type":"string"},"results":{"items":{"$ref":"#/components/schemas/ResearchBatchRowResult"},"title":"Results","type":"array"},"total_rows":{"title":"Total Rows","type":"integer"}},"required":["batch_id","batch_name","agent_key","total_rows","processed_rows","processing_status","results"],"title":"BatchResultsResponse","type":"object"},"BillingTransactionItem":{"description":"One wallet transaction.","properties":{"amount_cents":{"description":"Dollar amount in cents (positive = credit added, negative = consumed).","title":"Amount Cents","type":"integer"},"balance_after_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Wallet balance immediately after this transaction.","title":"Balance After Cents"},"created_at":{"description":"ISO 8601 — when the transaction posted.","format":"date-time","title":"Created At","type":"string"},"depth_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Effort tier the consumed job ran at, if applicable.","title":"Depth Type"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-form note (e.g. ``Top-up via Stripe``).","title":"Description"},"id":{"description":"Stable transaction identifier.","title":"Id","type":"string"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The research job that consumed credits, if applicable.","title":"Job Id"},"receipt_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stripe-hosted receipt URL for paid deposits.","title":"Receipt Url"},"stripe_payment_intent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stripe payment intent for paid deposits.","title":"Stripe Payment Intent Id"},"type":{"description":"Transaction type: ``deposit``, ``consumption``, ``bonus``, ``refund``, ``expiration``, or ``auto_topup``.","title":"Type","type":"string"}},"required":["id","created_at","type","amount_cents"],"title":"BillingTransactionItem","type":"object"},"BillingUsageByEffort":{"description":"Per-effort spend breakdown for the requested period.","properties":{"cents":{"default":0,"description":"Dollar value of those credits, in cents.","title":"Cents","type":"integer"},"credits":{"default":0,"description":"Credits consumed across those jobs.","title":"Credits","type":"integer"},"jobs":{"default":0,"description":"Number of jobs run at this effort tier.","title":"Jobs","type":"integer"}},"title":"BillingUsageByEffort","type":"object"},"BillingUsageResponse":{"description":"Aggregated credit spend over a billing window.\n\n``low`` (free tier) is omitted from ``by_effort`` because it\ndoesn't produce a wallet transaction. ``cents_spent_paid``\nreports out-of-pocket spend only — it excludes credits that came\nfrom your subscription bundle or referral bonuses.","properties":{"by_effort":{"additionalProperties":{"$ref":"#/components/schemas/BillingUsageByEffort"},"description":"Per-effort breakdown keyed by effort tier (``medium``, ``high``, ``build``).","title":"By Effort","type":"object"},"cents_spent_paid":{"default":0,"description":"Out-of-pocket dollar spend in cents (PAYG wallet draws only).","title":"Cents Spent Paid","type":"integer"},"job_count":{"default":0,"description":"Distinct jobs that consumed credits in the window.","title":"Job Count","type":"integer"},"period_end":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"ISO 8601 — end of the aggregation window.","title":"Period End"},"period_start":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"ISO 8601 — start of the aggregation window.","title":"Period Start"},"projected_period_end_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Linear projection of credits remaining at the end of the period at current burn rate.","title":"Projected Period End Credits"},"total_cents_spent":{"default":0,"description":"Dollar value of those credits, in cents.","title":"Total Cents Spent","type":"integer"},"total_credits_used":{"default":0,"description":"Total credits consumed in the window.","title":"Total Credits Used","type":"integer"}},"title":"BillingUsageResponse","type":"object"},"Body_create_research_attachment_v2":{"properties":{"files":{"description":"One or more files to upload as a reusable research attachment.","items":{"contentMediaType":"application/octet-stream","type":"string"},"title":"Files","type":"array"}},"required":["files"],"title":"Body_create_research_attachment_v2","type":"object"},"Body_upload_expert_context_file_v2":{"properties":{"file":{"contentMediaType":"application/octet-stream","title":"File","type":"string"}},"required":["file"],"title":"Body_upload_expert_context_file_v2","type":"object"},"ContextFileDeleteV2Response":{"properties":{"name":{"title":"Name","type":"string"},"removed_from_mirror":{"title":"Removed From Mirror","type":"boolean"},"removed_from_repository":{"title":"Removed From Repository","type":"boolean"},"success":{"default":true,"title":"Success","type":"boolean"}},"required":["name","removed_from_mirror","removed_from_repository"],"title":"ContextFileDeleteV2Response","type":"object"},"ContextFileImportV2Request":{"description":"Import a context file from a URL or an uploaded research attachment.","properties":{"attachment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Copy a file from this research attachment (you must own it)","title":"Attachment Id"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stored filename. Required when the URL has no usable extension, or to pick one file from a multi-file attachment.","title":"Filename"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public http(s) URL to fetch server-side. Private, loopback, link-local (cloud metadata), and reserved addresses are blocked; redirects are re-validated per hop; downloads are size-capped.","title":"Source Url"}},"title":"ContextFileImportV2Request","type":"object"},"ContextFilePayload":{"description":"Workspace context file uploaded with an expert (name + extracted text).","properties":{"content":{"maxLength":5000000,"title":"Content","type":"string"},"name":{"maxLength":512,"minLength":1,"title":"Name","type":"string"}},"required":["name","content"],"title":"ContextFilePayload","type":"object"},"ContextFileSummaryV2":{"description":"One context file attached to an expert.","properties":{"char_count":{"default":0,"description":"Length of the mirrored text","title":"Char Count","type":"integer"},"in_repository":{"default":false,"description":"Original bytes are stored in the expert repository","title":"In Repository","type":"boolean"},"name":{"title":"Name","type":"string"},"size_bytes":{"default":0,"title":"Size Bytes","type":"integer"},"text_mirrored":{"default":false,"description":"Extracted text is mirrored on the expert record","title":"Text Mirrored","type":"boolean"}},"required":["name"],"title":"ContextFileSummaryV2","type":"object"},"ContextFileUploadV2Response":{"properties":{"char_count":{"default":0,"title":"Char Count","type":"integer"},"commit_sha":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commit Sha"},"name":{"title":"Name","type":"string"},"path":{"description":"Path inside the expert repository (context/<name>)","title":"Path","type":"string"},"size_bytes":{"title":"Size Bytes","type":"integer"},"success":{"default":true,"title":"Success","type":"boolean"},"text_mirrored":{"description":"Extracted text was mirrored onto the expert record","title":"Text Mirrored","type":"boolean"}},"required":["name","path","size_bytes","text_mirrored"],"title":"ContextFileUploadV2Response","type":"object"},"ContextFilesListV2Response":{"properties":{"count":{"default":0,"title":"Count","type":"integer"},"expert_id":{"title":"Expert Id","type":"string"},"files":{"items":{"$ref":"#/components/schemas/ContextFileSummaryV2"},"title":"Files","type":"array"}},"required":["expert_id"],"title":"ContextFilesListV2Response","type":"object"},"CreateExpertV2Request":{"description":"Direct expert create — the public-safe subset of the Builder form.","properties":{"allow_free_tier_use":{"default":false,"description":"Admin-only: let restricted free-tier accounts run this public expert","title":"Allow Free Tier Use","type":"boolean"},"context_files":{"anyOf":[{"items":{"$ref":"#/components/schemas/ContextFilePayload"},"type":"array"},{"type":"null"}],"description":"Text reference documents (name + content). Binary documents go through `POST /api/v2/experts/{expert_id}/context-files` after creation.","title":"Context Files"},"default_depth":{"anyOf":[{"enum":["quick","thorough","ultra_deep"],"type":"string"},{"type":"null"}],"title":"Default Depth"},"default_mode":{"anyOf":[{"enum":["research","build","chat"],"type":"string"},{"type":"null"}],"title":"Default Mode"},"default_model":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SDK model id the expert runs with by default","title":"Default Model"},"default_runtime":{"anyOf":[{"enum":["claude_agents","agentrun"],"type":"string"},{"type":"null"}],"description":"Sandbox harness the expert runs under; omit for the platform default","title":"Default Runtime"},"description":{"default":"","maxLength":5000,"title":"Description","type":"string"},"domain":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"title":"Domain"},"expertise_areas":{"items":{"type":"string"},"title":"Expertise Areas","type":"array"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Lucide icon name (kebab-case)","title":"Icon"},"input_form":{"anyOf":[{"items":{"$ref":"#/components/schemas/ExpertInputField"},"type":"array"},{"type":"null"}],"description":"Input form fields shown when a run is started from the product","title":"Input Form"},"is_public":{"default":false,"description":"Admin-only: publish to the global expert picker","title":"Is Public","type":"boolean"},"max_cost_usd":{"anyOf":[{"maximum":1000.0,"minimum":0.5,"type":"number"},{"type":"null"}],"description":"Ceiling on metered provider spend per run of this expert. Dispatch binds the tighter of this and the caller's max_cost_usd.","title":"Max Cost Usd"},"mcp_tool_names":{"description":"MCP tool names to grant to the expert","items":{"type":"string"},"title":"Mcp Tool Names","type":"array"},"name":{"maxLength":255,"minLength":1,"title":"Name","type":"string"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Default JSON schema for structured output. Runs started with this expert return a `structured_output` matching it unless the caller passes its own `json_schema`. When supplied (or when output_sop is), the server skips the LLM config extractor.","title":"Output Schema"},"output_sop":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Structured SOP (steps, risk criteria, required output fields, recommendation categories) as returned by `POST /api/v2/experts/extract`.","title":"Output Sop"},"output_template":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"HTML output template for html-template types","title":"Output Template"},"output_template_file":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"For file/scaffold output types (spreadsheet/document/pdf/slidedeck): the name of a context file the build agent fills each run. Must match an attached context file.","title":"Output Template File"},"output_template_sample":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Sample structured output used to preview the HTML template","title":"Output Template Sample"},"output_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Output type key (research_report, conversational_answer, dashboard, slidedeck, document, spreadsheet, pdf, website, data_explorer, podcast, video)","title":"Output Type"},"owner_email":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Admin-only: assign the expert to this user email instead of the creator","title":"Owner Email"},"pinned_workflow":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Frozen workflow DSL from `POST /api/v2/experts/generate-workflow`. The ATI runtime runs it verbatim; omit to let the harness author a workflow per run.","title":"Pinned Workflow"},"required_tool_calls":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Tool names that must each return a successful result during a run (observational monitor). Each must be in mcp_tool_names.","title":"Required Tool Calls"},"skill_names":{"description":"Skill names to link to the expert","items":{"type":"string"},"title":"Skill Names","type":"array"},"status":{"default":"active","description":"Create as a draft (building) or immediately usable (active)","enum":["active","building"],"title":"Status","type":"string"},"system_prompt":{"maxLength":500000,"minLength":1,"title":"System Prompt","type":"string"}},"required":["name","system_prompt"],"title":"CreateExpertV2Request","type":"object"},"CreateResearchBatchInput":{"additionalProperties":false,"description":"Create a research batch from a list of questions (one job per question).","properties":{"approach":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional research approach for every row","title":"Approach"},"batch_name":{"description":"Display name for the batch","maxLength":200,"minLength":1,"title":"Batch Name","type":"string"},"effort":{"default":"medium","description":"Effort applied to every row: low|medium|high|build","title":"Effort","type":"string"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Agent applied to every row: a built-in registry id, or the UUID / slug / handle of a custom agent the caller may run. Omit to let the pipeline pick the default.","title":"Expert Id"},"max_concurrent":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Max rows running at once (1-20, default 5)","title":"Max Concurrent"},"max_credits":{"anyOf":[{"minimum":1.0,"type":"integer"},{"type":"null"}],"description":"Credit budget for the whole batch. The dispatcher never launches a row the remaining budget cannot fully cover; when the cap is reached the batch pauses with paused_reason=budget_exhausted. Must cover at least one row at the batch's effort.","title":"Max Credits"},"questions":{"description":"One research question per row (1-100, blanks dropped)","items":{"type":"string"},"title":"Questions","type":"array"},"response_language":{"default":"en","description":"Response language (ISO 639-1) for every row","title":"Response Language","type":"string"},"rows":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"description":"Optional parsed CSV row per question ({header: value}), positionally aligned with `questions`. Stored on each BatchRowStatus.row_data so the detail table can render the input columns. Length must match `questions` when provided.","title":"Rows"}},"required":["batch_name","questions"],"title":"CreateResearchBatchInput","type":"object"},"CreateResearchBatchResponse":{"properties":{"batch_id":{"title":"Batch Id","type":"string"},"downgrade":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Downgrade"},"status":{"title":"Status","type":"string"},"total_rows":{"title":"Total Rows","type":"integer"}},"required":["batch_id","total_rows","status"],"title":"CreateResearchBatchResponse","type":"object"},"CreateSkillV2Request":{"description":"A user-authored skill: SKILL.md content persisted to storage and made selectable.","properties":{"content":{"description":"SKILL.md markdown body. Frontmatter (name/description) is prepended when absent.","maxLength":200000,"minLength":50,"title":"Content","type":"string"},"description":{"maxLength":1000,"minLength":10,"title":"Description","type":"string"},"name":{"description":"kebab-case slug (e.g. credit-memo-writer)","maxLength":100,"minLength":3,"title":"Name","type":"string"}},"required":["name","description","content"],"title":"CreateSkillV2Request","type":"object"},"CreateSkillV2Response":{"properties":{"created":{"description":"False when your existing same-named skill was overwritten in place","title":"Created","type":"boolean"},"name":{"title":"Name","type":"string"},"skill_id":{"title":"Skill Id","type":"string"}},"required":["name","skill_id","created"],"title":"CreateSkillV2Response","type":"object"},"CursorPage_BillingTransactionItem_":{"properties":{"has_more":{"default":false,"title":"Has More","type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/BillingTransactionItem"},"title":"Items","type":"array"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"required":["items"],"title":"CursorPage[BillingTransactionItem]","type":"object"},"CursorPage_ResearchBatchSummary_":{"properties":{"has_more":{"default":false,"title":"Has More","type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/ResearchBatchSummary"},"title":"Items","type":"array"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"required":["items"],"title":"CursorPage[ResearchBatchSummary]","type":"object"},"CursorPage_ResearchJobListItem_":{"properties":{"has_more":{"default":false,"title":"Has More","type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/ResearchJobListItem"},"title":"Items","type":"array"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"required":["items"],"title":"CursorPage[ResearchJobListItem]","type":"object"},"CursorPage_TimelineEvent_":{"properties":{"has_more":{"default":false,"title":"Has More","type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/TimelineEvent"},"title":"Items","type":"array"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"required":["items"],"title":"CursorPage[TimelineEvent]","type":"object"},"CustomExpertSummary":{"description":"One row in the authenticated custom-expert list.","properties":{"allow_free_tier_use":{"default":false,"title":"Allow Free Tier Use","type":"boolean"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"icon":{"default":"brain","title":"Icon","type":"string"},"id":{"title":"Id","type":"string"},"is_owned_by_me":{"default":false,"title":"Is Owned By Me","type":"boolean"},"is_public":{"default":false,"title":"Is Public","type":"boolean"},"name":{"title":"Name","type":"string"},"skill_names":{"items":{"type":"string"},"title":"Skill Names","type":"array"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},"required":["id","name"],"title":"CustomExpertSummary","type":"object"},"CustomExpertsListResponse":{"properties":{"count":{"default":0,"title":"Count","type":"integer"},"experts":{"items":{"$ref":"#/components/schemas/CustomExpertSummary"},"title":"Experts","type":"array"}},"title":"CustomExpertsListResponse","type":"object"},"ExpertAccessGrantV2":{"properties":{"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"granted_by":{"title":"Granted By","type":"string"},"grantee_id":{"title":"Grantee Id","type":"string"},"grantee_type":{"title":"Grantee Type","type":"string"},"id":{"title":"Id","type":"string"},"permission":{"title":"Permission","type":"string"}},"required":["id","grantee_type","grantee_id","permission","granted_by"],"title":"ExpertAccessGrantV2","type":"object"},"ExpertAccessListV2Response":{"properties":{"count":{"default":0,"title":"Count","type":"integer"},"expert_id":{"title":"Expert Id","type":"string"},"grants":{"items":{"$ref":"#/components/schemas/ExpertAccessGrantV2"},"title":"Grants","type":"array"}},"required":["expert_id"],"title":"ExpertAccessListV2Response","type":"object"},"ExpertApplyV2Request":{"description":"Declarative apply: diff the manifest against current state, perform the delta.","properties":{"dry_run":{"default":false,"description":"Compute and return the plan without applying","title":"Dry Run","type":"boolean"},"manifest":{"$ref":"#/components/schemas/ExpertManifest","description":"Desired state of the expert"}},"required":["manifest"],"title":"ExpertApplyV2Request","type":"object"},"ExpertApplyV2Response":{"properties":{"applied":{"description":"Actions performed (empty on dry_run)","items":{"additionalProperties":true,"type":"object"},"title":"Applied","type":"array"},"created":{"default":false,"title":"Created","type":"boolean"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Target expert (null when validation failed pre-create)","title":"Expert Id"},"noop":{"default":false,"description":"True when the manifest already matches current state","title":"Noop","type":"boolean"},"plan":{"description":"Every action the diff calls for","items":{"additionalProperties":true,"type":"object"},"title":"Plan","type":"array"},"validation":{"additionalProperties":true,"description":"The pre-apply validation report","title":"Validation","type":"object"}},"title":"ExpertApplyV2Response","type":"object"},"ExpertBuildCreateRequest":{"description":"Start an async prompt-driven expert build.","properties":{"context":{"anyOf":[{"maxLength":5000,"type":"string"},{"type":"null"}],"description":"Additional build requirements. The builder takes all context up front; there is no clarification round-trip on this surface.","title":"Context"},"depth":{"default":"standard","description":"Build depth (standard: ~3 skills, deep: ~8 skills)","enum":["standard","deep"],"title":"Depth","type":"string"},"domain":{"description":"The domain of expertise to build","maxLength":500,"minLength":3,"title":"Domain","type":"string"}},"required":["domain"],"title":"ExpertBuildCreateRequest","type":"object"},"ExpertBuildResponse":{"description":"Response from starting an expert build.","properties":{"job_id":{"description":"Build job id — poll GET /experts/build/{job_id}","title":"Job Id","type":"string"},"message":{"description":"Response message","title":"Message","type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Human-readable job slug","title":"Slug"},"status":{"description":"Initial job status (queued)","title":"Status","type":"string"}},"required":["job_id","status","message"],"title":"ExpertBuildResponse","type":"object"},"ExpertBuildResult":{"description":"The registered expert, present once the build has succeeded.","properties":{"context_files":{"items":{"additionalProperties":true,"type":"object"},"title":"Context Files","type":"array"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Id"},"expert_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Name"},"expert_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Slug"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon"},"skills_created":{"items":{"additionalProperties":true,"type":"object"},"title":"Skills Created","type":"array"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Expert lifecycle status — builds register a 'building' draft; activate via PATCH /experts/{id}","title":"Status"}},"title":"ExpertBuildResult","type":"object"},"ExpertBuildStatusResponse":{"description":"Status of an async expert build.","properties":{"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"depth":{"default":"standard","title":"Depth","type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"expert":{"anyOf":[{"$ref":"#/components/schemas/ExpertBuildResult"},{"type":"null"}]},"job_id":{"title":"Job Id","type":"string"},"status":{"description":"queued: waiting for a worker · running: the builder agent is working · registering: the sandbox finished and the draft expert is being persisted · succeeded: the expert is registered (see `expert`) · failed: terminal failure (see `error`)","enum":["queued","running","registering","succeeded","failed"],"title":"Status","type":"string"}},"required":["job_id","status"],"title":"ExpertBuildStatusResponse","type":"object"},"ExpertDeleteV2Response":{"properties":{"expert_id":{"title":"Expert Id","type":"string"},"status":{"title":"Status","type":"string"},"success":{"title":"Success","type":"boolean"}},"required":["success","expert_id","status"],"title":"ExpertDeleteV2Response","type":"object"},"ExpertDetailV2Response":{"description":"Full configuration of an expert as the runtime sees it.","properties":{"allow_free_tier_use":{"default":false,"title":"Allow Free Tier Use","type":"boolean"},"built_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Built At"},"can_edit":{"default":false,"title":"Can Edit","type":"boolean"},"context_files":{"items":{"$ref":"#/components/schemas/ContextFileSummaryV2"},"title":"Context Files","type":"array"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"default_depth":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Depth"},"default_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Mode"},"default_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Model"},"default_runtime":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Runtime"},"description":{"title":"Description","type":"string"},"domain":{"title":"Domain","type":"string"},"icon":{"default":"brain","title":"Icon","type":"string"},"id":{"title":"Id","type":"string"},"input_form":{"items":{"additionalProperties":true,"type":"object"},"title":"Input Form","type":"array"},"is_built_in":{"default":false,"description":"True for registry experts (read-only)","title":"Is Built In","type":"boolean"},"is_public":{"default":false,"title":"Is Public","type":"boolean"},"max_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Cost Usd"},"mcp_tool_names":{"items":{"type":"string"},"title":"Mcp Tool Names","type":"array"},"name":{"title":"Name","type":"string"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema"},"output_sop":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Sop"},"output_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Template"},"output_template_file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Template File"},"output_template_sample":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Template Sample"},"output_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Type"},"owner_id":{"default":"","title":"Owner Id","type":"string"},"pinned_workflow":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Pinned Workflow"},"required_tool_calls":{"items":{"type":"string"},"title":"Required Tool Calls","type":"array"},"skill_names":{"items":{"type":"string"},"title":"Skill Names","type":"array"},"slug":{"title":"Slug","type":"string"},"status":{"title":"Status","type":"string"},"system_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Prompt"},"team_tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Team Tenant Id"},"usage_count":{"default":0,"title":"Usage Count","type":"integer"}},"required":["id","name","slug","description","domain","status"],"title":"ExpertDetailV2Response","type":"object"},"ExpertExtractV2Request":{"properties":{"raw_input":{"description":"Pasted config / SOP text","maxLength":500000,"minLength":1,"title":"Raw Input","type":"string"}},"required":["raw_input"],"title":"ExpertExtractV2Request","type":"object"},"ExpertExtractV2Response":{"properties":{"agent_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Description"},"clean_system_prompt":{"title":"Clean System Prompt","type":"string"},"detected_format":{"default":"unknown","title":"Detected Format","type":"string"},"extraction_notes":{"items":{"type":"string"},"title":"Extraction Notes","type":"array"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema"},"output_sop":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Sop"}},"required":["clean_system_prompt"],"title":"ExpertExtractV2Response","type":"object"},"ExpertGenerateWorkflowV2Request":{"properties":{"effort":{"anyOf":[{"enum":["low","medium","high"],"type":"string"},{"type":"null"}],"title":"Effort"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema"},"sample_input":{"anyOf":[{},{"type":"null"}],"description":"A representative input the expert runs on","title":"Sample Input"},"schema_set":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Optional curated {schemaIds, registry} set","title":"Schema Set"},"system_prompt":{"description":"The expert SOP prose","maxLength":500000,"minLength":1,"title":"System Prompt","type":"string"}},"required":["system_prompt"],"title":"ExpertGenerateWorkflowV2Request","type":"object"},"ExpertGenerateWorkflowV2Response":{"properties":{"attempts":{"default":0,"title":"Attempts","type":"integer"},"valid":{"default":false,"title":"Valid","type":"boolean"},"validation_errors":{"items":{"type":"string"},"title":"Validation Errors","type":"array"},"workflow":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Pass as `pinned_workflow` when valid","title":"Workflow"}},"title":"ExpertGenerateWorkflowV2Response","type":"object"},"ExpertInputField":{"description":"One field in an expert's saved ``form.json`` / ``input_form``.","properties":{"label":{"maxLength":255,"minLength":1,"title":"Label","type":"string"},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"required":{"default":false,"title":"Required","type":"boolean"},"selection_mode":{"anyOf":[{"enum":["single","multiple"],"type":"string"},{"type":"null"}],"title":"Selection Mode"},"type":{"default":"text","enum":["text","textarea","number","date","email","url","address","boolean","file","single_select","multi_select","dropdown"],"title":"Type","type":"string"}},"required":["label"],"title":"ExpertInputField","type":"object"},"ExpertManifest":{"additionalProperties":false,"description":"Desired state of one expert. Field names match the create/update surface.","properties":{"context_files":{"items":{"$ref":"#/components/schemas/ManifestContextFile"},"title":"Context Files","type":"array"},"custom_skills":{"description":"Inline custom skill definitions, created/updated during apply","items":{"$ref":"#/components/schemas/ManifestCustomSkill"},"title":"Custom Skills","type":"array"},"default_depth":{"anyOf":[{"enum":["quick","thorough","ultra_deep"],"type":"string"},{"type":"null"}],"title":"Default Depth"},"default_mode":{"anyOf":[{"enum":["research","build","chat"],"type":"string"},{"type":"null"}],"title":"Default Mode"},"default_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Default Model"},"default_runtime":{"anyOf":[{"enum":["claude_agents","agentrun"],"type":"string"},{"type":"null"}],"title":"Default Runtime"},"description":{"default":"","maxLength":5000,"title":"Description","type":"string"},"domain":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"title":"Domain"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Target an existing expert; omit to adopt-by-name or create","title":"Expert Id"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon"},"input_form":{"anyOf":[{"items":{"$ref":"#/components/schemas/ExpertInputField"},"type":"array"},{"type":"null"}],"title":"Input Form"},"max_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Cost Usd"},"mcp_tool_names":{"items":{"type":"string"},"title":"Mcp Tool Names","type":"array"},"name":{"maxLength":255,"minLength":1,"title":"Name","type":"string"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema"},"output_sop":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Sop"},"output_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Template"},"output_template_file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Template File"},"output_template_sample":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Template Sample"},"output_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Type"},"pinned_workflow":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Pinned Workflow"},"prune_context_files":{"default":true,"description":"Treat context_files as the complete set: delete attached files the manifest omits","title":"Prune Context Files","type":"boolean"},"required_tool_calls":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Required Tool Calls"},"skills":{"description":"Catalog or custom skill names to link","items":{"type":"string"},"title":"Skills","type":"array"},"system_prompt":{"maxLength":500000,"minLength":1,"title":"System Prompt","type":"string"}},"required":["name","system_prompt"],"title":"ExpertManifest","type":"object"},"ExpertPlanPreviewV2Request":{"properties":{"context":{"anyOf":[{"maxLength":20000,"type":"string"},{"type":"null"}],"description":"Optional run context","title":"Context"},"depth":{"default":"deep","description":"Planning depth mode to preview","enum":["ultra_fast","deep","ultra_deep"],"title":"Depth","type":"string"},"question":{"description":"A representative research question","maxLength":10000,"minLength":1,"title":"Question","type":"string"}},"required":["question"],"title":"ExpertPlanPreviewV2Request","type":"object"},"ExpertPlanPreviewV2Response":{"properties":{"depth":{"title":"Depth","type":"string"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms"},"expert_id":{"title":"Expert Id","type":"string"},"plan":{"additionalProperties":true,"description":"The plan the research pipeline's planner would produce","title":"Plan","type":"object"},"question":{"title":"Question","type":"string"}},"required":["expert_id","question","depth","plan"],"title":"ExpertPlanPreviewV2Response","type":"object"},"ExpertShareV2Request":{"properties":{"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 expiry (null = permanent)","title":"Expires At"},"grantee_id":{"description":"Email, lowercased email domain, or team tenant id","title":"Grantee Id","type":"string"},"grantee_type":{"description":"user: one email · tenant: everyone in an email domain · team: a team tenant","enum":["user","tenant","team"],"title":"Grantee Type","type":"string"},"permission":{"default":"read","enum":["read","write","admin"],"title":"Permission","type":"string"}},"required":["grantee_type","grantee_id"],"title":"ExpertShareV2Request","type":"object"},"ExpertShareV2Response":{"properties":{"access_id":{"title":"Access Id","type":"string"},"action":{"description":"created | updated | revoked","title":"Action","type":"string"},"message":{"title":"Message","type":"string"},"success":{"title":"Success","type":"boolean"}},"required":["success","access_id","action","message"],"title":"ExpertShareV2Response","type":"object"},"ExpertSummary":{"description":"One entry in the discoverable expert list.\n\nSurfaced on ``GET /mpp/v1/api/experts`` and (curated subset) on\n``GET /mpp/v1/api`` under ``featured_experts``. Stays narrow — no\ninternal mcp_tools / skills / system_prompt plumbing.","properties":{"description":{"description":"Brief description of the expert's specialty.","title":"Description","type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Domain area (e.g., ``Supply Chain Research, Global Trade``).","title":"Domain"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Lucide icon name (UI hint).","title":"Icon"},"id":{"description":"Expert id, used as ``expert_id`` on POST /research.","title":"Id","type":"string"},"name":{"description":"Display name (e.g., ``Patent & IP``).","title":"Name","type":"string"},"output_types":{"description":"What this expert reliably produces. ``report`` = markdown. ``html_app`` / ``slidedeck`` / ``spreadsheet`` for app-builder. ``podcast`` / ``video`` / ``news_broadcast`` for media-producer.","items":{"type":"string"},"title":"Output Types","type":"array"},"sample_questions":{"description":"Example prompts that route well to this expert. Agents can pattern-match against the user's request to pick the right expert without LLM inference.","items":{"type":"string"},"title":"Sample Questions","type":"array"}},"required":["id","name","description"],"title":"ExpertSummary","type":"object"},"ExpertUnshareV2Request":{"properties":{"grantee_id":{"title":"Grantee Id","type":"string"},"grantee_type":{"enum":["user","tenant","team"],"title":"Grantee Type","type":"string"}},"required":["grantee_type","grantee_id"],"title":"ExpertUnshareV2Request","type":"object"},"ExpertV2Response":{"description":"Public projection of a created/updated expert.","properties":{"allow_free_tier_use":{"default":false,"title":"Allow Free Tier Use","type":"boolean"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"description":{"title":"Description","type":"string"},"domain":{"title":"Domain","type":"string"},"icon":{"default":"brain","title":"Icon","type":"string"},"id":{"title":"Id","type":"string"},"is_public":{"default":false,"title":"Is Public","type":"boolean"},"name":{"title":"Name","type":"string"},"owner_id":{"default":"","title":"Owner Id","type":"string"},"skill_names":{"items":{"type":"string"},"title":"Skill Names","type":"array"},"slug":{"title":"Slug","type":"string"},"status":{"title":"Status","type":"string"}},"required":["id","name","slug","description","domain","status"],"title":"ExpertV2Response","type":"object"},"ExpertValidateV2Request":{"description":"Validate an expert config without persisting anything.\n\nPass ``expert_id`` to validate an UPDATE (the checks run against the\nmerged state of that expert); omit it to validate a fresh create. Only\nsupplied fields are checked against/merged over the current state.","properties":{"config":{"$ref":"#/components/schemas/UpdateExpertV2Request","description":"The fields to validate (create- or update-shaped)"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Validate as an update to this expert","title":"Expert Id"}},"required":["config"],"title":"ExpertValidateV2Request","type":"object"},"ExpertValidateV2Response":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/ExpertValidationIssueV2"},"title":"Errors","type":"array"},"valid":{"title":"Valid","type":"boolean"},"warnings":{"description":"Non-blocking issues (e.g. redundantly granting an always-on tool)","items":{"$ref":"#/components/schemas/ExpertValidationIssueV2"},"title":"Warnings","type":"array"}},"required":["valid"],"title":"ExpertValidateV2Response","type":"object"},"ExpertValidationIssueV2":{"properties":{"field":{"title":"Field","type":"string"},"message":{"title":"Message","type":"string"}},"required":["field","message"],"title":"ExpertValidationIssueV2","type":"object"},"ExpertVersionDetailV2Response":{"properties":{"config_snapshot":{"additionalProperties":true,"title":"Config Snapshot","type":"object"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"created_by":{"default":"","title":"Created By","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"improver_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Improver Job Id"},"mcp_tool_names":{"items":{"type":"string"},"title":"Mcp Tool Names","type":"array"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema"},"output_sop":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Sop"},"skill_names":{"items":{"type":"string"},"title":"Skill Names","type":"array"},"source":{"description":"manual | improver | restore","title":"Source","type":"string"},"system_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Prompt"},"version_num":{"title":"Version Num","type":"integer"}},"required":["version_num","source"],"title":"ExpertVersionDetailV2Response","type":"object"},"ExpertVersionRestoreV2Response":{"properties":{"new_version_num":{"description":"Snapshot of the pre-restore config, so the restore is reversible","title":"New Version Num","type":"integer"},"restored_version_num":{"title":"Restored Version Num","type":"integer"}},"required":["restored_version_num","new_version_num"],"title":"ExpertVersionRestoreV2Response","type":"object"},"ExpertVersionV2":{"properties":{"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"created_by":{"default":"","title":"Created By","type":"string"},"improver_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Improver Job Id"},"source":{"description":"manual | improver | restore","title":"Source","type":"string"},"version_num":{"title":"Version Num","type":"integer"}},"required":["version_num","source"],"title":"ExpertVersionV2","type":"object"},"ExpertVersionsListV2Response":{"properties":{"count":{"default":0,"title":"Count","type":"integer"},"expert_id":{"title":"Expert Id","type":"string"},"versions":{"items":{"$ref":"#/components/schemas/ExpertVersionV2"},"title":"Versions","type":"array"}},"required":["expert_id"],"title":"ExpertVersionsListV2Response","type":"object"},"ExpertVisibilityV2Request":{"properties":{"is_public":{"description":"true is Parcha-admin-only; owners may set false","title":"Is Public","type":"boolean"}},"required":["is_public"],"title":"ExpertVisibilityV2Request","type":"object"},"ExpertVisibilityV2Response":{"properties":{"expert_id":{"title":"Expert Id","type":"string"},"is_public":{"title":"Is Public","type":"boolean"},"message":{"title":"Message","type":"string"}},"required":["expert_id","is_public","message"],"title":"ExpertVisibilityV2Response","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"KeyCreateV2Request":{"additionalProperties":false,"properties":{"expires_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Optional ISO-8601 expiry. Omit for a non-expiring key.","title":"Expires At"},"label":{"description":"Human-friendly name for the key","maxLength":100,"minLength":1,"title":"Label","type":"string"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Scopes for the new key. Must be a subset of the OAuth token's scopes; omit to inherit exactly the caller's scopes.","title":"Scopes"}},"required":["label"],"title":"KeyCreateV2Request","type":"object"},"KeyCreateV2Response":{"properties":{"api_key":{"description":"The full secret. Shown ONLY here — store it now.","title":"Api Key","type":"string"},"key":{"$ref":"#/components/schemas/KeySummaryV2"}},"required":["key","api_key"],"title":"KeyCreateV2Response","type":"object"},"KeyRevokeV2Response":{"properties":{"key":{"$ref":"#/components/schemas/KeySummaryV2"},"revoked":{"description":"True — revocation is idempotent, re-revoking is not an error","title":"Revoked","type":"boolean"}},"required":["key","revoked"],"title":"KeyRevokeV2Response","type":"object"},"KeySummaryV2":{"description":"Key metadata. The secret is returned once, at creation, and never again.","properties":{"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"display_prefix":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First characters of the key, for recognition","title":"Display Prefix"},"display_suffix":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last characters of the key, for recognition","title":"Display Suffix"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"id":{"title":"Id","type":"string"},"is_active":{"default":true,"title":"Is Active","type":"boolean"},"label":{"title":"Label","type":"string"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At"},"revoked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revoked At"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Scopes granted to the key (null on legacy pre-scope keys)","title":"Scopes"}},"required":["id","label"],"title":"KeySummaryV2","type":"object"},"KeysListV2Response":{"properties":{"count":{"default":0,"title":"Count","type":"integer"},"keys":{"items":{"$ref":"#/components/schemas/KeySummaryV2"},"title":"Keys","type":"array"}},"title":"KeysListV2Response","type":"object"},"ManifestContextFile":{"additionalProperties":false,"description":"One desired context file. Exactly one source: content, source_url, or attachment_id.","properties":{"attachment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Copy from a research attachment you own","title":"Attachment Id"},"content":{"anyOf":[{"maxLength":5000000,"type":"string"},{"type":"null"}],"description":"Inline text content","title":"Content"},"name":{"maxLength":512,"minLength":1,"title":"Name","type":"string"},"replace":{"default":"missing","description":"missing: keep an existing file with this name (inline text still re-uploads when it differs from the stored mirror) · always: re-upload every apply","enum":["missing","always"],"title":"Replace","type":"string"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Public http(s) URL fetched server-side (SSRF-guarded)","title":"Source Url"}},"required":["name"],"title":"ManifestContextFile","type":"object"},"ManifestCustomSkill":{"additionalProperties":false,"description":"A custom skill defined inline; created or re-uploaded as part of apply.","properties":{"content":{"description":"SKILL.md markdown body","maxLength":200000,"minLength":50,"title":"Content","type":"string"},"description":{"maxLength":1000,"minLength":10,"title":"Description","type":"string"},"name":{"description":"kebab-case skill slug","maxLength":100,"minLength":3,"title":"Name","type":"string"}},"required":["name","description","content"],"title":"ManifestCustomSkill","type":"object"},"McpToolV2":{"description":"An MCP tool an expert can be granted.","properties":{"always_on":{"default":false,"description":"Every research run carries this tool regardless of expert configuration; it need not (and should not) appear in mcp_tool_names.","title":"Always On","type":"boolean"},"category":{"title":"Category","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"is_default":{"default":false,"description":"Included in the research defaults","title":"Is Default","type":"boolean"},"name":{"description":"Full tool name — pass it in `mcp_tool_names`","title":"Name","type":"string"},"server":{"title":"Server","type":"string"},"short_name":{"title":"Short Name","type":"string"}},"required":["name","short_name","server","category"],"title":"McpToolV2","type":"object"},"McpToolsListV2Response":{"properties":{"count":{"default":0,"description":"Rows returned (after any limit)","title":"Count","type":"integer"},"servers":{"description":"All catalog servers, unaffected by filters","items":{"type":"string"},"title":"Servers","type":"array"},"tools":{"items":{"$ref":"#/components/schemas/McpToolV2"},"title":"Tools","type":"array"},"total":{"default":0,"description":"Rows matching the filters, before the limit","title":"Total","type":"integer"}},"title":"McpToolsListV2Response","type":"object"},"PreviousResearchJob":{"description":"Public-safe link metadata for a recurring job's previous run.","properties":{"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"job_id":{"title":"Job Id","type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"}},"required":["job_id"],"title":"PreviousResearchJob","type":"object"},"QuotaCheckResponse":{"description":"Result of a non-consuming quota pre-flight.","properties":{"allowed":{"description":"True if the caller has enough credits to run at this effort.","title":"Allowed","type":"boolean"},"credits_remaining":{"description":"Credits the caller has right now.","title":"Credits Remaining","type":"integer"},"credits_required":{"description":"How many credits this effort would cost.","title":"Credits Required","type":"integer"},"effort":{"description":"Echo of the requested effort tier.","title":"Effort","type":"string"},"pool":{"default":"personal","description":"Which wallet these numbers describe: ``personal`` or ``team``. A team-bound API key always reports its team's pool.","title":"Pool","type":"string"},"pool_tenant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The team whose pool would be charged, when ``pool`` is ``team``.","title":"Pool Tenant Id"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When ``allowed=false``, a short reason (e.g. ``insufficient_credits``).","title":"Reason"}},"required":["allowed","effort","credits_required","credits_remaining"],"title":"QuotaCheckResponse","type":"object"},"QuotaResponse":{"description":"Caller's current quota and credit balance.","properties":{"bonus_credits":{"default":0,"description":"Credits from referrals or promos (consumed first).","title":"Bonus Credits","type":"integer"},"credit_quota":{"description":"Total credits granted in the current period.","title":"Credit Quota","type":"integer"},"credits_remaining":{"description":"Credits available to spend right now.","title":"Credits Remaining","type":"integer"},"credits_required_for_effort":{"additionalProperties":{"type":"integer"},"description":"Credit cost of one ``POST /research`` call at each effort tier.","title":"Credits Required For Effort","type":"object"},"credits_used_this_period":{"default":0,"description":"Credits consumed since the period start.","title":"Credits Used This Period","type":"integer"},"current_period_end":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"ISO 8601 — when the period resets.","title":"Current Period End"},"current_period_start":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"ISO 8601 — start of the current billing period.","title":"Current Period Start"},"tier":{"description":"Subscription tier the caller is on (e.g. ``free``, ``pro``, ``team``).","title":"Tier","type":"string"}},"required":["tier","credits_remaining","credit_quota"],"title":"QuotaResponse","type":"object"},"ResearchAppArtifact":{"description":"Deployed app produced by a build-mode research job.","properties":{"anonymous_cta_config":{"anyOf":[{"$ref":"#/components/schemas/AnonymousCtaConfig"},{"type":"null"}],"description":"Optional per-app CTA copy and scroll-trigger overrides."},"anonymous_cta_enabled":{"default":false,"description":"Whether signed-out viewers see the optional GREP.AI CTA after engaging.","title":"Anonymous Cta Enabled","type":"boolean"},"anonymous_cta_variant":{"default":"product","description":"Which CTA experience signed-out viewers receive.","enum":["product","enterprise"],"title":"Anonymous Cta Variant","type":"string"},"app_id":{"description":"Stable UUID identity of the deployed app.","title":"App Id","type":"string"},"is_public":{"default":false,"description":"Whether anonymous viewers can open the app.","title":"Is Public","type":"boolean"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stable GREP app viewer URL.","title":"Public Url"},"status":{"description":"App deployment status.","title":"Status","type":"string"}},"required":["app_id","status"],"title":"ResearchAppArtifact","type":"object"},"ResearchAttachmentDeleteResponse":{"description":"Response from ``DELETE /attachments/{attachment_id}``.","properties":{"attachment_id":{"description":"Stable attachment UUID.","format":"uuid","title":"Attachment Id","type":"string"},"status":{"description":"Always ``deleted`` after a successful delete.","title":"Status","type":"string"}},"required":["attachment_id","status"],"title":"ResearchAttachmentDeleteResponse","type":"object"},"ResearchAttachmentResponse":{"description":"Response from public v2 attachment endpoints.","properties":{"attachment_id":{"description":"Stable attachment UUID.","format":"uuid","title":"Attachment Id","type":"string"},"expires_at":{"description":"ISO 8601 expiration timestamp.","title":"Expires At","type":"string"},"files":{"description":"Uploaded files in this attachment.","items":{"$ref":"#/components/schemas/AttachedFile"},"title":"Files","type":"array"},"status":{"description":"Attachment lifecycle status.","title":"Status","type":"string"}},"required":["attachment_id","status","expires_at"],"title":"ResearchAttachmentResponse","type":"object"},"ResearchBatchDetail":{"properties":{"agent_key":{"title":"Agent Key","type":"string"},"batch_id":{"title":"Batch Id","type":"string"},"batch_name":{"title":"Batch Name","type":"string"},"config":{"additionalProperties":true,"title":"Config","type":"object"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"credits_per_row":{"default":0,"title":"Credits Per Row","type":"integer"},"credits_spent":{"default":0,"title":"Credits Spent","type":"integer"},"paused_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paused Reason"},"processed_rows":{"title":"Processed Rows","type":"integer"},"processing_completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Completed At"},"processing_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Started At"},"processing_status":{"title":"Processing Status","type":"string"},"rows":{"items":{"$ref":"#/components/schemas/ResearchBatchRow"},"title":"Rows","type":"array"},"stalled":{"default":false,"title":"Stalled","type":"boolean"},"total_rows":{"title":"Total Rows","type":"integer"}},"required":["batch_id","batch_name","agent_key","total_rows","processed_rows","processing_status","config","rows"],"title":"ResearchBatchDetail","type":"object"},"ResearchBatchRow":{"properties":{"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"has_report":{"default":false,"title":"Has Report","type":"boolean"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id"},"job_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Slug"},"job_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Status"},"question":{"title":"Question","type":"string"},"row_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Row Data"},"row_number":{"title":"Row Number","type":"integer"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"status":{"title":"Status","type":"string"}},"required":["row_number","question","status"],"title":"ResearchBatchRow","type":"object"},"ResearchBatchRowResult":{"description":"One row's outcome, self-contained: enough to read, link, or branch on\nthe result without a follow-up call per row.","properties":{"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"excerpt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Excerpt"},"headline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headline"},"is_public":{"default":false,"title":"Is Public","type":"boolean"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id"},"job_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Slug"},"report_link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Link"},"row_number":{"title":"Row Number","type":"integer"},"status":{"title":"Status","type":"string"},"structured_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Structured Output"}},"required":["row_number","status"],"title":"ResearchBatchRowResult","type":"object"},"ResearchBatchSummary":{"properties":{"agent_key":{"title":"Agent Key","type":"string"},"batch_id":{"title":"Batch Id","type":"string"},"batch_name":{"title":"Batch Name","type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"paused_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paused Reason"},"processed_rows":{"title":"Processed Rows","type":"integer"},"processing_completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Completed At"},"processing_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Started At"},"processing_status":{"title":"Processing Status","type":"string"},"total_rows":{"title":"Total Rows","type":"integer"}},"required":["batch_id","batch_name","agent_key","total_rows","processed_rows","processing_status"],"title":"ResearchBatchSummary","type":"object"},"ResearchCancelResponse":{"description":"Response from ``POST /research/{id}/cancel``.","properties":{"already_terminal":{"default":false,"description":"True when the job was already terminal and no new cancel signal was sent.","title":"Already Terminal","type":"boolean"},"interrupted_check_result_ids":{"description":"CheckResult IDs moved to ``interrupted`` by this request.","items":{"type":"string"},"title":"Interrupted Check Result Ids","type":"array"},"job_id":{"description":"Stable UUID identity for the cancelled job.","title":"Job Id","type":"string"},"previous_status":{"description":"Status before this cancellation request.","title":"Previous Status","type":"string"},"signaled_keys":{"description":"Redis job/check-result keys that received a cancel signal.","items":{"type":"string"},"title":"Signaled Keys","type":"array"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL-friendly handle, if available.","title":"Slug"},"status":{"description":"Current terminal status. Usually ``cancelled``.","title":"Status","type":"string"}},"required":["job_id","status","previous_status"],"title":"ResearchCancelResponse","type":"object"},"ResearchContinuationCreate":{"additionalProperties":false,"description":"Request body for continuing a completed research job.","properties":{"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Additional context for this continuation turn.","title":"Context"},"effort":{"default":"low","description":"Effort tier for the continuation turn.","enum":["low","medium","high","build"],"title":"Effort","type":"string"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional body-level idempotency key. The ``Idempotency-Key`` header takes precedence when both are supplied.","title":"Idempotency Key"},"instructions":{"description":"Instructions for the continuation turn. The agent resumes the completed job's Claude session and updates the existing research workspace/report in place.","title":"Instructions","type":"string"},"json_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Optional structured-output schema for the updated report.","title":"Json Schema"},"referenceJobs":{"description":"Optional Grep research job UUIDs or slugs to make available as read-only code.storage workspace references for this continuation.","items":{"type":"string"},"title":"Reference Jobs","type":"array"},"render_rich_report":{"default":false,"description":"Render the report with widget:html visualisations (cover page, charts, diagrams, callouts). Default false produces a clean markdown report (headings, prose, markdown tables, inline citations) suitable for API/MCP consumers piping the output into their own pipelines. The Parcha UI sends true to get the rich rendered experience.","title":"Render Rich Report","type":"boolean"},"response_language":{"default":"en","description":"ISO 639-1 language code for the updated report.","title":"Response Language","type":"string"},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Webhook URL POSTed when the continued job reaches a terminal state. API-key authentication only.","title":"Webhook Url"}},"required":["instructions"],"title":"ResearchContinuationCreate","type":"object"},"ResearchContinuationResponse":{"description":"Response from ``POST /research/{id}/continue``.","properties":{"continuation_id":{"description":"CheckResult UUID for this continuation turn.","title":"Continuation Id","type":"string"},"created_at":{"description":"ISO 8601 timestamp for the continuation row.","title":"Created At","type":"string"},"idempotent_replay":{"default":false,"description":"True when this response replays a previous request with the same idempotency key.","title":"Idempotent Replay","type":"boolean"},"job_id":{"description":"Stable UUID identity for the continued job.","title":"Job Id","type":"string"},"previous_status":{"description":"Status before the continuation request.","title":"Previous Status","type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL-friendly handle, if available.","title":"Slug"},"status":{"description":"Current job status after enqueueing continuation.","title":"Status","type":"string"}},"required":["job_id","status","previous_status","continuation_id","created_at"],"title":"ResearchContinuationResponse","type":"object"},"ResearchFileEntry":{"description":"One file in a research job's workspace.","properties":{"can_preview":{"default":false,"description":"Whether the file can be rendered inline.","title":"Can Preview","type":"boolean"},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"MIME type.","title":"Content Type"},"extension":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"File extension (e.g. ``md``, ``json``).","title":"Extension"},"file_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"High-level file type (e.g. ``text``, ``image``, ``data``).","title":"File Type"},"modified_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 — last commit that touched this file.","title":"Modified At"},"path":{"description":"Slash-separated path relative to the job's workspace root.","title":"Path","type":"string"},"size_bytes":{"description":"File size in bytes.","title":"Size Bytes","type":"integer"}},"required":["path","size_bytes"],"title":"ResearchFileEntry","type":"object"},"ResearchFilesList":{"description":"Response from ``GET /research/{id}/files`` — the file listing.","properties":{"files":{"description":"All files in the workspace.","items":{"$ref":"#/components/schemas/ResearchFileEntry"},"title":"Files","type":"array"},"job_id":{"description":"Job UUID the listing is for.","title":"Job Id","type":"string"}},"required":["job_id"],"title":"ResearchFilesList","type":"object"},"ResearchJobCreate":{"additionalProperties":false,"description":"Request body for starting a research job.","properties":{"attachment_ids":{"description":"Attachment UUIDs returned by ``POST /attachments``. The server copies those files into the job workspace so the agent can read them from ``./input_files/``.","items":{"format":"uuid","type":"string"},"maxItems":10,"title":"Attachment Ids","type":"array"},"benchmark_mode":{"default":false,"description":"PARCHA-ADMIN ONLY. Evaluation switch: returns raw markdown/artifacts for scoring and DISABLES content moderation so an eval harness is never blocked (e.g. build pre-dispatch planner failing-closed on a Cerebras outage). Non-admin callers are rejected. start_research_job_internal already auto-skips moderation for admins; this flag also suppresses the HTML reporter.","title":"Benchmark Mode","type":"boolean"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Additional context for the research — gets passed through to the planner as background info on the question.","title":"Context"},"effort":{"default":"low","description":"How deeply to research. ``low`` returns a quick answer (~10–20 s), ``medium`` produces a structured report (~2–3 min), ``high`` runs an in-depth multi-phase investigation (~8–15 min), and ``build`` produces a creative artefact (HTML app, dataset, slides, …).","enum":["low","medium","high","build"],"title":"Effort","type":"string"},"expert_id":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"description":"Pin a specific research expert. Accepts: (a) a built-in registry id (e.g. ``individual-aml-compliance-expert``); (b) a custom expert UUID you own (or have been granted access to via expert sharing); (c) a custom expert slug. When omitted, an expert is auto-selected based on the question. Access is checked at request-validate time against the same rule the chat surface uses — if you can view the expert, you can dispatch against it.","title":"Expert Id"},"harness_sha":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Vendored ATI-harness variant to run this job on (advanced/experimental). Names a directory under the deployment's harness-variants root. Omit to use the deployment's default pinned harness. Ignored by the ``claude_agents`` runtime.","title":"Harness Sha"},"json_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Optional JSON Schema describing structured fields you want the agent to populate in addition to the prose report. When supplied, the agent treats the schema as a checklist and researches every field — the result lands under ``structured_output`` on the detail response. The body must be a JSON object and a valid draft-07 JSON Schema (``type``, ``properties``, etc.): the request 422s with the reason when the schema cannot be compiled — an unresolvable ``$ref``, an invalid ``pattern``, or a meta-schema violation. Annotation keywords outside the draft-07 vocabulary (``example``, ``x-*`` extensions, 2020-12 keywords) are dropped before dispatch. ``$defs``/``$ref`` are supported.","title":"Json Schema"},"max_cost_usd":{"anyOf":[{"maximum":1000.0,"minimum":0.5,"type":"number"},{"type":"null"}],"description":"Optional maximum metered provider spend for each logical run. The minimum depends on ``effort``, because a run pays for its prompt/skill preamble before it can issue a tool call: ``low`` $0.50, ``medium`` and ``build`` $2.50, ``high`` $5.00. The normal billing margin still applies when provider cost is converted to credits.","title":"Max Cost Usd"},"model":{"anyOf":[{"enum":["opus","sonnet","haiku"],"type":"string"},{"type":"null"}],"title":"Model"},"question":{"description":"The research question to investigate.","title":"Question","type":"string"},"referenceJobs":{"description":"Optional Grep research job UUIDs or slugs to make available as read-only code.storage workspace references for this run.","items":{"type":"string"},"title":"Reference Jobs","type":"array"},"render_rich_report":{"default":false,"description":"Render the report with widget:html visualisations (cover page, charts, diagrams, callouts). Default false produces a clean markdown report (headings, prose, markdown tables, inline citations) suitable for API/MCP consumers piping the output into their own pipelines. The Parcha UI sends true to get the rich rendered experience.","title":"Render Rich Report","type":"boolean"},"response_language":{"default":"en","description":"ISO 639-1 language code for the rendered report.","title":"Response Language","type":"string"},"runtime":{"anyOf":[{"enum":["claude_agents","agentrun"],"type":"string"},{"type":"null"}],"description":"Agent runtime harness. ``claude_agents`` uses the default Claude agent sandbox runner. ``agentrun`` uses the vendored ATI harness runner. When omitted, resolves to the GREP_DEFAULT_RESEARCH_HARNESS env for research efforts (``claude_agents`` if unset) and always to ``claude_agents`` for ``effort=build``.","title":"Runtime"},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Webhook URL POSTed when the job reaches a terminal state.","title":"Webhook Url"}},"required":["question"],"title":"ResearchJobCreate","type":"object"},"ResearchJobDetail":{"description":"Single-job detail returned by ``GET /api/v2/research/{job_id_or_slug}``.\n\nStrict shape (no ``extra=\"allow\"`` catch-all). What you see is the\ncontract; nothing else leaks through. Job IDs accept either a UUID\nor a slug — see ``resolve_job_id`` in v1 for the lookup logic.","properties":{"app":{"anyOf":[{"$ref":"#/components/schemas/ResearchAppArtifact"},{"type":"null"}],"description":"Newest deployed app produced by this build job, when available."},"attachments":{"description":"Input attachments copied into ``./input_files/`` for this job.","items":{"$ref":"#/components/schemas/ResearchAttachmentResponse"},"title":"Attachments","type":"array"},"budget_exhausted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether the final logical run ended through the budget wrap-up path.","title":"Budget Exhausted"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 — when execution ended.","title":"Completed At"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Caller-supplied context.","title":"Context"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601.","title":"Created At"},"effort":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Effort level the job was created with (matches ``POST /research``).","title":"Effort"},"error_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Machine-readable failure category, when present. ``moderated`` means the input was refused by content moderation before any work ran; reword and resend.","title":"Error Kind"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Plain-language reason for a failure, when the platform can name one.","title":"Error Message"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pinned expert ID, if the caller specified one. Empty when the expert was auto-selected from the question.","title":"Expert Id"},"is_public":{"default":false,"description":"If true, the job is publicly viewable.","title":"Is Public","type":"boolean"},"job_id":{"description":"Stable UUID identity.","title":"Job Id","type":"string"},"json_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Echo of the JSON Schema the caller supplied at job start, if any. ``None`` when the job was created without a ``json_schema`` field on the request body.","title":"Json Schema"},"max_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Caller-supplied provider-spend cap for each logical run.","title":"Max Cost Usd"},"previous_job":{"anyOf":[{"$ref":"#/components/schemas/PreviousResearchJob"},{"type":"null"}],"description":"Previous completed run for the same schedule or monitor."},"question":{"description":"The research question.","title":"Question","type":"string"},"report":{"anyOf":[{"$ref":"#/components/schemas/ResearchReport"},{"type":"null"}],"description":"The rendered ``report.md`` content + the commit it was read from. ``None`` for queued/running jobs (no report yet). Read at the head of ``main`` at request time."},"response_language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Report language (ISO 639-1 code).","title":"Response Language"},"revisions":{"description":"Published revisions of the report, newest first. Pass a ``commit_sha`` from this list as ``?revision=<sha>`` on this endpoint to read the report at that historical revision.","items":{"$ref":"#/components/schemas/ResearchRevision"},"title":"Revisions","type":"array"},"runtime":{"anyOf":[{"enum":["claude_agents","agentrun"],"type":"string"},{"type":"null"}],"description":"Agent runtime harness used for this job.","title":"Runtime"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL-friendly handle.","title":"Slug"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 — when execution began.","title":"Started At"},"status":{"description":"Job lifecycle status.","title":"Status","type":"string"},"structured_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Agent-populated structured output conforming to ``json_schema``. Present only when (a) the job supplied a schema at start and (b) the agent has finished and filled it. ``None`` for queued / running / failed jobs and for jobs that never asked for structured output.","title":"Structured Output"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 — last server-side mutation.","title":"Updated At"}},"required":["job_id","status","question"],"title":"ResearchJobDetail","type":"object"},"ResearchJobListItem":{"description":"Single row in ``GET /api/v2/research`` — the lean list view.\n\nCarries enough to render a list, decide whether to drill in, and\nlink by slug. Everything else (approach, effort, file listing,\nreport content) zooms in via ``GET /api/v2/research/{id}``.","properties":{"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 — when the job finished.","title":"Completed At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 — when the job was created.","title":"Created At"},"effort":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Effort tier the job ran at: ``ultra_fast``, ``deep``, ``ultra_deep``, ``low``, ``medium``, ``high``, or ``build``.","title":"Effort"},"job_id":{"description":"Stable UUID identity for the job.","title":"Job Id","type":"string"},"question":{"description":"The research question the job is answering.","title":"Question","type":"string"},"runtime":{"anyOf":[{"enum":["claude_agents","agentrun"],"type":"string"},{"type":"null"}],"description":"Agent runtime harness used for the job.","title":"Runtime"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL-friendly handle. May be null for very old jobs.","title":"Slug"},"status":{"description":"Lifecycle: ``queued``, ``moderation``, ``planning``, ``running``, ``completed``, ``failed``, ``cancelled``, ``blocked``.","title":"Status","type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601 — last server-side mutation (status change, slug assignment, etc).","title":"Updated At"}},"required":["job_id","status","question"],"title":"ResearchJobListItem","type":"object"},"ResearchJobResponse":{"description":"Response from starting a research job.","properties":{"downgrade":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Downgrade"},"job_id":{"title":"Job Id","type":"string"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"status":{"title":"Status","type":"string"}},"required":["job_id","status"],"title":"ResearchJobResponse","type":"object"},"ResearchReport":{"description":"The rendered ``report.md`` payload inlined on detail responses.","properties":{"markdown":{"description":"Raw Markdown content of the current report.","title":"Markdown","type":"string"},"revision_sha":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Commit SHA the report was read from. ``None`` when the job has not produced a checkpoint yet (the report was read from the default branch tip but no revision metadata exists).","title":"Revision Sha"},"widgets":{"anyOf":[{"items":{"$ref":"#/components/schemas/ResearchWidget"},"type":"array"},{"type":"null"}],"description":"Widgets keyed to section anchors in ``markdown``. The frontend overlays each widget onto its section. ``None`` for old reports that pre-date the decoupled architecture (their widgets are still inlined as ``widget:html`` fences in ``markdown``).","title":"Widgets"}},"required":["markdown"],"title":"ResearchReport","type":"object"},"ResearchRevision":{"description":"One published revision of the research report.\n\nPass the ``commit_sha`` to ``GET /research/{id}?revision=<sha>``\nto re-read the report at that point in time.","properties":{"actor_label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Which agent wrote the revision (e.g. ``research-agent``).","title":"Actor Label"},"checkpoint_type":{"description":"``new_subjob`` (root revision) or ``continuation`` (incremental update).","title":"Checkpoint Type","type":"string"},"commit_message":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Author-provided revision notes, if any.","title":"Commit Message"},"commit_sha":{"description":"Full git commit SHA.","title":"Commit Sha","type":"string"},"created_at":{"description":"ISO 8601 — when this revision was published.","title":"Created At","type":"string"}},"required":["commit_sha","created_at","checkpoint_type"],"title":"ResearchRevision","type":"object"},"ResearchVisibilityResponse":{"description":"Response body for ``PATCH /api/v2/research/{job_id_or_slug}``.","properties":{"app":{"anyOf":[{"$ref":"#/components/schemas/ResearchAppArtifact"},{"type":"null"}],"description":"Newest deployed app updated with the job visibility change, when available."},"is_public":{"description":"The new visibility state after the update.","title":"Is Public","type":"boolean"},"job_id":{"description":"Stable UUID identity of the job.","title":"Job Id","type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"URL-friendly handle, if any.","title":"Slug"},"updated_at":{"description":"ISO 8601 timestamp of the mutation.","title":"Updated At","type":"string"}},"required":["job_id","is_public","updated_at"],"title":"ResearchVisibilityResponse","type":"object"},"ResearchVisibilityUpdate":{"additionalProperties":false,"description":"Request body for ``PATCH /api/v2/research/{job_id_or_slug}``.\n\nJob visibility is required. Build jobs may also update the research-owned\nviewer CTA state and variant in the same atomic mutation.","properties":{"anonymous_cta_config":{"anyOf":[{"$ref":"#/components/schemas/AnonymousCtaConfig"},{"type":"null"}],"description":"Optional CTA copy and scroll-trigger overrides for the published research. Send null explicitly to clear existing overrides."},"anonymous_cta_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Optional viewer setting for the published research. When omitted, existing research CTA settings are preserved.","title":"Anonymous Cta Enabled"},"anonymous_cta_variant":{"anyOf":[{"enum":["product","enterprise"],"type":"string"},{"type":"null"}],"description":"Optional CTA experience for the published research. When omitted, existing research CTA settings are preserved.","title":"Anonymous Cta Variant"},"is_public":{"description":"When ``true``, the job is publicly viewable without authentication (capability reads of the report, files, and timeline succeed). When ``false``, the job reverts to owner/admin-only access.","title":"Is Public","type":"boolean"}},"required":["is_public"],"title":"ResearchVisibilityUpdate","type":"object"},"ResearchWidget":{"description":"One renderable widget keyed to a section anchor in ``report.md``.\n\nThe frontend overlays each widget onto the section whose H2 carries\n``{#<section_anchor>}`` — widget always wins. Prose remains as fallback\nwhen ``widgets`` is empty or anchors don't match.","properties":{"html":{"description":"Widget HTML — rendered verbatim, no further sanitisation.","title":"Html","type":"string"},"section_anchor":{"description":"4-letter code matching the H2 anchor in ``report.md`` (e.g. ``cvr1``).","title":"Section Anchor","type":"string"},"sources":{"anyOf":[{"items":{"$ref":"#/components/schemas/ResearchWidgetSource"},"type":"array"},{"type":"null"}],"description":"Optional source chips rendered beneath the widget.","title":"Sources"},"widget_id":{"description":"Unique ID within the report (e.g. ``w1_cover``).","title":"Widget Id","type":"string"}},"required":["widget_id","section_anchor","html"],"title":"ResearchWidget","type":"object"},"ResearchWidgetSource":{"description":"One source citation chip rendered beneath a widget.","properties":{"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bare hostname (no www. prefix). Derived if absent.","title":"Domain"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Source title; OG-fetched on the client if absent.","title":"Title"},"url":{"description":"Canonical URL of the source.","title":"Url","type":"string"}},"required":["url"],"title":"ResearchWidgetSource","type":"object"},"RetryFailedRowsResponse":{"properties":{"agent_key":{"title":"Agent Key","type":"string"},"batch_id":{"title":"Batch Id","type":"string"},"batch_name":{"title":"Batch Name","type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"paused_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paused Reason"},"processed_rows":{"title":"Processed Rows","type":"integer"},"processing_completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Completed At"},"processing_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Started At"},"processing_status":{"title":"Processing Status","type":"string"},"retried_rows":{"default":0,"title":"Retried Rows","type":"integer"},"total_rows":{"title":"Total Rows","type":"integer"}},"required":["batch_id","batch_name","agent_key","total_rows","processed_rows","processing_status"],"title":"RetryFailedRowsResponse","type":"object"},"SkillContentV2Response":{"properties":{"content":{"description":"Full SKILL.md content (with frontmatter)","title":"Content","type":"string"},"is_custom":{"title":"Is Custom","type":"boolean"},"name":{"title":"Name","type":"string"},"source":{"enum":["catalog","custom"],"title":"Source","type":"string"}},"required":["name","content","is_custom","source"],"title":"SkillContentV2Response","type":"object"},"SkillSummaryV2":{"description":"A skill an expert can be linked to.","properties":{"category":{"title":"Category","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"is_custom":{"default":false,"description":"True for a skill you authored (private to you)","title":"Is Custom","type":"boolean"},"name":{"description":"Skill name — pass it in `skill_names`","title":"Name","type":"string"},"suggested_tools":{"description":"MCP tool names the skill typically needs","items":{"type":"string"},"title":"Suggested Tools","type":"array"},"tags":{"items":{"type":"string"},"title":"Tags","type":"array"}},"required":["name","category"],"title":"SkillSummaryV2","type":"object"},"SkillsListV2Response":{"properties":{"categories":{"description":"All catalog categories, unaffected by filters","items":{"type":"string"},"title":"Categories","type":"array"},"count":{"default":0,"description":"Rows returned (after any limit)","title":"Count","type":"integer"},"skills":{"items":{"$ref":"#/components/schemas/SkillSummaryV2"},"title":"Skills","type":"array"},"total":{"default":0,"description":"Rows matching the filters, before the limit","title":"Total","type":"integer"}},"title":"SkillsListV2Response","type":"object"},"TimelineEvent":{"description":"One event in a research job's execution timeline.\n\nReturned in DESC order (newest first) by ``GET\n/research/{job_id_or_slug}/timeline``. Customers drive a\n\"what's the agent doing right now?\" UI off this without our\nSDK content shape becoming a public contract.","properties":{"agent_label":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The actor that emitted the event. For a workflow run this is the unit doing the work — a node such as ``decide:Judge MCC Selection`` or the engine's ``frozen-workflow:<pin>`` — so events group per node; when a row names no actor it falls back to the runtime key (e.g. ``grep-research-v2``).","title":"Agent Label"},"created_at":{"description":"DB-write time, ISO 8601. The keyset cursor encodes this column.","title":"Created At","type":"string"},"id":{"description":"Stable event UUID — also the keyset cursor anchor.","title":"Id","type":"string"},"kind":{"description":"Event type. One of ``thinking``, ``text_block``, ``tool_use``, ``tool_result``, ``phase``, ``subagent_started``, ``subagent_progress``, ``subagent_completed``, ``final_answer``, ``error``. Unknown / internal event kinds are filtered out before the response is built.","title":"Kind","type":"string"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Human-readable one-liner describing what happened (e.g. ``Using tool: Bash``, ``Subagent working: Search for Stripe`` — the same string the dashboard shows). Truncated to 500 characters. ``None`` for events that have no narratable status.","title":"Summary"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Human-readable text the agent produced. For ``kind=text_block`` this is the response chunk; for ``kind=thinking`` this is the reasoning trace. Truncated to 2000 characters.","title":"Text"},"timestamp":{"description":"Worker-side wall-clock when the event happened, ISO 8601. May be slightly behind ``created_at`` for events that queue before being persisted.","title":"Timestamp","type":"string"},"tool_input_preview":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"For ``kind=tool_use``: a short, sanitized rendering of the tool input (typically the description plus the first characters of the command). Env-var values are redacted and absolute paths obfuscated. Truncated to 500 characters.","title":"Tool Input Preview"},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tool name when ``kind`` is ``tool_use`` or ``tool_result`` (e.g. ``Read``, ``Bash``, ``WebSearch``).","title":"Tool Name"},"tool_result_preview":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"For ``kind=tool_result``: first 500 characters of the tool output, sanitized. Use ``tool_result_size_bytes`` to detect truncation.","title":"Tool Result Preview"},"tool_result_size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"For ``kind=tool_result``: byte length of the FULL tool output (before truncation). When this exceeds the preview length, fetch the workspace file via ``GET /research/{id}/files/{path}`` for the full content.","title":"Tool Result Size Bytes"},"tool_status":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"For ``kind=tool_result``: ``\"success\"`` or ``\"failed\"``. ``None`` for non-result events.","title":"Tool Status"},"tool_use_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stable tool-call identifier. The same value appears on the matching ``tool_use`` and ``tool_result`` events; use it to pair them in client code.","title":"Tool Use Id"}},"required":["id","timestamp","created_at","kind"],"title":"TimelineEvent","type":"object"},"UpdateExpertV2Request":{"description":"Partial update. Omitted fields are unchanged.\n\nLists replace the stored list (an empty list clears it); ``output_template_file``\naccepts an empty string to clear; ``pinned_workflow`` and ``max_cost_usd``\naccept an explicit ``null`` to clear.","properties":{"allow_free_tier_use":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Admin-only; requires is_public","title":"Allow Free Tier Use"},"context_files":{"anyOf":[{"items":{"$ref":"#/components/schemas/ContextFilePayload"},"type":"array"},{"type":"null"}],"description":"Replaces the text context-file mirror (name + content)","title":"Context Files"},"default_depth":{"anyOf":[{"enum":["quick","thorough","ultra_deep"],"type":"string"},{"type":"null"}],"title":"Default Depth"},"default_mode":{"anyOf":[{"enum":["research","build","chat"],"type":"string"},{"type":"null"}],"title":"Default Mode"},"default_model":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SDK model id; empty string clears","title":"Default Model"},"default_runtime":{"anyOf":[{"enum":["claude_agents","agentrun",""],"type":"string"},{"type":"null"}],"description":"Sandbox harness; empty string clears the pin","title":"Default Runtime"},"description":{"anyOf":[{"maxLength":5000,"type":"string"},{"type":"null"}],"title":"Description"},"domain":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"title":"Domain"},"expertise_areas":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Expertise Areas"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Icon"},"input_form":{"anyOf":[{"items":{"$ref":"#/components/schemas/ExpertInputField"},"type":"array"},{"type":"null"}],"title":"Input Form"},"is_public":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Admin-only to set true; owners may set false","title":"Is Public"},"max_cost_usd":{"anyOf":[{"maximum":1000.0,"minimum":0.5,"type":"number"},{"type":"null"}],"description":"Per-run spend ceiling; explicit null clears it","title":"Max Cost Usd"},"mcp_tool_names":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Replaces the expert's granted MCP tools","title":"Mcp Tool Names"},"name":{"anyOf":[{"maxLength":255,"minLength":1,"type":"string"},{"type":"null"}],"title":"Name"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Default structured-output JSON schema","title":"Output Schema"},"output_sop":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Structured SOP (see POST /experts/extract)","title":"Output Sop"},"output_template":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"HTML template; empty string clears","title":"Output Template"},"output_template_file":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Context file used as the output scaffold; empty string clears","title":"Output Template File"},"output_template_sample":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Template Sample"},"output_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Output Type"},"owner_email":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Admin-only: reassign ownership","title":"Owner Email"},"pinned_workflow":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Frozen workflow DSL; explicit null or {} clears the pin","title":"Pinned Workflow"},"required_tool_calls":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Replaces the required-tool monitor; each tool must be granted","title":"Required Tool Calls"},"skill_names":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Replaces the expert's linked skills","title":"Skill Names"},"status":{"anyOf":[{"enum":["active","building"],"type":"string"},{"type":"null"}],"description":"building → active finalizes a draft; active → building is allowed only together with context_files (staging a binary re-upload)","title":"Status"},"system_prompt":{"anyOf":[{"maxLength":500000,"type":"string"},{"type":"null"}],"title":"System Prompt"}},"title":"UpdateExpertV2Request","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}},"securitySchemes":{"GrepApiKeyBearer":{"bearerFormat":"Grep API key","description":"Use a Grep API key in the Authorization header: Bearer parcha-...","scheme":"bearer","type":"http"},"GrepOAuth2":{"description":"Use a Descope-issued OAuth access token minted for the Grep Public API v2 resource.","flows":{"authorizationCode":{"authorizationUrl":"https://api.descope.com/oauth2/v1/apps/authorize","scopes":{"billing:read":"Read billing and usage information.","experts:read":"Read custom experts, their configuration, context files, versions, skills, and tool catalogs.","experts:write":"Create, build, update, share, and manage custom experts, their context files, and custom skills.","research:read":"Read research jobs, reports, files, timelines, quota, and usage.","research:write":"Start research and manage research attachments."},"tokenUrl":"https://api.descope.com/oauth2/v1/apps/token"},"clientCredentials":{"scopes":{"billing:read":"Read billing and usage information.","experts:read":"Read custom experts, their configuration, context files, versions, skills, and tool catalogs.","experts:write":"Create, build, update, share, and manage custom experts, their context files, and custom skills.","research:read":"Read research resources.","research:write":"Create research resources."},"tokenUrl":"https://api.descope.com/oauth2/v1/apps/token"}},"type":"oauth2"}}},"info":{"description":"Programmatic access to Grep — kick off research jobs, fetch their reports and files, and check your credit balance. All endpoints accept either a UUID or a slug for ``{job_id_or_slug}``.","title":"Grep API","version":"1.0"},"openapi":"3.1.0","paths":{"/api/v2/a2a":{"post":{"description":"A2A JSON-RPC endpoint for Grep research tasks.","operationId":"a2a_jsonrpc_api_v2_a2a_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"title":"Envelope","type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"A2A Jsonrpc","tags":["Agent-to-Agent"]}},"/api/v2/agents":{"get":{"description":"Alias of ``GET /api/v2/experts``. Returns the canonical list of public agents that v2 and the MPP gateway both accept on the ``expert_id`` field. Public — no auth required.","operationId":"list_agents_v2","responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ExpertSummary"},"title":"Response List Agents V2","type":"array"}}},"description":"Successful Response"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"List public agents","tags":["Experts"]}},"/api/v2/attachments":{"post":{"description":"Upload files and receive an ``attachment_id`` for ``POST /research``.\n\nThe upload is independent of any job. Pass the returned\n``attachment_id`` in ``attachment_ids`` when creating research and\nthe server will copy these files into that job's ``./input_files/``.","operationId":"create_research_attachment_v2","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_research_attachment_v2"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchAttachmentResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Create Research Attachment","tags":["Attachments"]}},"/api/v2/attachments/import":{"post":{"description":"JSON alternative to the multipart upload: the server fetches `source_url` (public http(s) only — private, loopback, link-local/cloud-metadata, and reserved addresses are blocked, redirects re-validated per hop, size-capped) and stores the result exactly like an uploaded file.","operationId":"import_research_attachment_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentImportRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchAttachmentResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Create an attachment from a URL","tags":["Attachments"]}},"/api/v2/attachments/{attachment_id}":{"delete":{"description":"Delete an attachment so it cannot be used by future jobs.","operationId":"delete_research_attachment_v2","parameters":[{"in":"path","name":"attachment_id","required":true,"schema":{"format":"uuid","title":"Attachment Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchAttachmentDeleteResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Delete Research Attachment","tags":["Attachments"]},"get":{"description":"Return attachment metadata for the authenticated owner.","operationId":"get_research_attachment_v2","parameters":[{"in":"path","name":"attachment_id","required":true,"schema":{"format":"uuid","title":"Attachment Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchAttachmentResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Get Research Attachment","tags":["Attachments"]}},"/api/v2/batches":{"get":{"description":"List your research batches, newest first. `query` filters by batch name (case-insensitive substring); `status` filters by batch status (e.g. `PENDING`, `PROCESSING`, `PROCESSED_SUCCESSFULLY`, `PROCESSED_WITH_ERRORS`, `CANCELLED`). Page with `cursor` from the previous response.","operationId":"list_batches_v2","parameters":[{"description":"Filter by batch name (case-insensitive substring).","in":"query","name":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by batch name (case-insensitive substring).","title":"Query"}},{"description":"Filter by batch status name.","in":"query","name":"status","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by batch status name.","title":"Status"}},{"description":"Opaque pagination cursor.","in":"query","name":"cursor","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque pagination cursor.","title":"Cursor"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_ResearchBatchSummary_"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"List your research batches","tags":["Batches"]},"post":{"description":"Create a batch that runs one research job per question (up to 100 rows). Config — expert, effort, approach, response language, concurrency — is chosen once for the whole batch. The create only persists intent; a dispatcher launches rows within ~30 seconds, respecting `max_concurrent`. Poll `GET /batches/{batch_id}` for progress; each row links to a normal research job readable via `GET /research/{job_id}`. Rows are metered like ordinary research at dispatch time — if credits run out mid-batch the batch pauses with `paused_reason: quota_exhausted` and resumes when credits return. `max_credits` caps total spend: the dispatcher never launches a row the remaining budget cannot cover and pauses the batch (`budget_exhausted`) at the cap; `credits_spent` on the detail response tracks consumption. An optional `Idempotency-Key` header makes the create replay-safe.","operationId":"create_batch_v2","parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateResearchBatchInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateResearchBatchResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Create a research batch","tags":["Batches"]}},"/api/v2/batches/estimate":{"get":{"description":"Preflight credit estimate for a batch, before creating it. Uses the same cost table the dispatcher bills from and applies the same account-tier clamp creation applies, so the quoted total matches what a batch you create will actually run and bill (`requested_effort`/`downgraded` surface any clamp). There is no upfront reservation: rows are metered as they dispatch.","operationId":"estimate_batch_v2","parameters":[{"in":"query","name":"rows","required":true,"schema":{"maximum":100,"minimum":1,"title":"Rows","type":"integer"}},{"in":"query","name":"effort","required":false,"schema":{"default":"medium","title":"Effort","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCreditEstimateResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Estimate a batch's credit cost","tags":["Batches"]}},"/api/v2/batches/{batch_id}":{"get":{"description":"Batch status, progress counters, config, and (by default) every row with its question, per-row status, and linked research job id — read a finished row's report via `GET /research/{job_id}`. Pass `include_rows=false` for a cheap status poll.","operationId":"get_batch_v2","parameters":[{"in":"path","name":"batch_id","required":true,"schema":{"title":"Batch Id","type":"string"}},{"description":"Include the per-row breakdown.","in":"query","name":"include_rows","required":false,"schema":{"default":true,"description":"Include the per-row breakdown.","title":"Include Rows","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchBatchDetail"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Get a research batch","tags":["Batches"]}},"/api/v2/batches/{batch_id}/cancel":{"post":{"description":"Stop launching new rows: still-pending rows are marked failed, rows already running settle on their own. Cancelling an already-terminal batch is a no-op that returns the batch unchanged.","operationId":"cancel_batch_v2","parameters":[{"in":"path","name":"batch_id","required":true,"schema":{"title":"Batch Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchBatchSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Cancel a research batch","tags":["Batches"]}},"/api/v2/batches/{batch_id}/results":{"get":{"description":"The batch's return path: per row — status, `error_code`, the linked research job id and report link, the structured output (when the run produced one), and a short answer (`headline` or `excerpt`). Assembled in two database queries with no per-row fetches, so one call replaces reading each row's job individually. The full report body is not inlined (it can be hundreds of KB per row) — follow `report_link` or `GET /research/{job_id}` for a specific row. Filter with `row_status` (e.g. `SUCCESS`, `FAILED`).","operationId":"get_batch_results_v2","parameters":[{"in":"path","name":"batch_id","required":true,"schema":{"title":"Batch Id","type":"string"}},{"description":"Filter rows by state (e.g. SUCCESS, FAILED).","in":"query","name":"row_status","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter rows by state (e.g. SUCCESS, FAILED).","title":"Row Status"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResultsResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Get every batch row's result in one call","tags":["Batches"]}},"/api/v2/batches/{batch_id}/retry-failed":{"post":{"description":"Re-run every FAILED row in one call: retryable rows reset to pending, the batch reopens, and the dispatcher launches fresh research jobs for them. Returns `retried_rows` — zero means nothing was retryable, which is a successful no-op. Rows on a cancelled batch are not retryable (409). Use each row's `error_code` to decide whether retrying is rational (`quota_exhausted` clears when credits return; `timed_out` and `dispatch_error` are worth retrying).","operationId":"retry_batch_failed_rows_v2","parameters":[{"in":"path","name":"batch_id","required":true,"schema":{"title":"Batch Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryFailedRowsResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Retry every failed batch row","tags":["Batches"]}},"/api/v2/batches/{batch_id}/rows/{row_number}/retry":{"post":{"description":"Re-run one FAILED row: the row resets to pending, the batch reopens, and the dispatcher launches a fresh research job for it within ~30 seconds. Rows on a cancelled batch are not retryable (409).","operationId":"retry_batch_row_v2","parameters":[{"in":"path","name":"batch_id","required":true,"schema":{"title":"Batch Id","type":"string"}},{"in":"path","name":"row_number","required":true,"schema":{"title":"Row Number","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchBatchSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Retry one failed batch row","tags":["Batches"]}},"/api/v2/billing/transactions":{"get":{"description":"List the caller's wallet transactions, newest first.\n\nCursor-paginated. Each entry has the transaction type\n(``deposit``, ``consumption``, ``bonus``, ``refund``,\n``expiration``, ``auto_topup``), credit amount, balance after,\noptional ``job_id`` for consumption tied to a research job, and\nStripe metadata for paid deposits.","operationId":"get_billing_transactions_v2","parameters":[{"description":"Opaque pagination cursor.","in":"query","name":"cursor","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque pagination cursor.","title":"Cursor"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"title":"Limit","type":"integer"}},{"description":"Filter to a single transaction type.","in":"query","name":"type","required":false,"schema":{"anyOf":[{"enum":["deposit","consumption","bonus_consumption","base_consumption","refund","expiration","auto_topup"],"type":"string"},{"type":"null"}],"description":"Filter to a single transaction type.","title":"Type"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_BillingTransactionItem_"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["billing:read"]}],"summary":"Get Billing Transactions","tags":["Billing"]}},"/api/v2/billing/usage":{"get":{"description":"Aggregate credit spend over the requested period.\n\nReturns total credits used, dollars spent (paid credits only —\nbonus credits are excluded from the cents fields), per-effort\nbreakdown, and a projection of where the period will end at\ncurrent burn rate. Defaults to the current billing period;\npass ``period=last_30d`` for a rolling 30-day window or\n``period=custom`` with ``from`` + ``to`` for an explicit range.","operationId":"get_billing_usage_v2","parameters":[{"description":"Aggregation window. ``custom`` requires ``from`` and ``to``.","in":"query","name":"period","required":false,"schema":{"default":"current_billing","description":"Aggregation window. ``custom`` requires ``from`` and ``to``.","enum":["current_billing","last_30d","custom"],"title":"Period","type":"string"}},{"description":"Custom-period lower bound (ISO 8601).","in":"query","name":"from","required":false,"schema":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Custom-period lower bound (ISO 8601).","title":"From"}},{"description":"Custom-period upper bound (ISO 8601).","in":"query","name":"to","required":false,"schema":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Custom-period upper bound (ISO 8601).","title":"To"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingUsageResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["billing:read"]}],"summary":"Get Billing Usage","tags":["Billing"]}},"/api/v2/experts":{"get":{"description":"Returns the canonical list of public research experts that v2 accepts on the ``expert_id`` field. Use this to pick an ``expert_id`` for ``POST /api/v2/research``. Public — no auth required.","operationId":"list_experts_v2","responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ExpertSummary"},"title":"Response List Experts V2","type":"array"}}},"description":"Successful Response"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"List public research experts","tags":["Experts"]},"post":{"description":"Create a custom expert directly from a full configuration (name, system prompt, skills, tools). The expert is immediately usable with `POST /api/v2/research` via its `expert_id` unless created as a `building` draft.","operationId":"create_expert_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExpertV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Create a custom expert","tags":["Experts"]}},"/api/v2/experts/apply":{"post":{"description":"Diff a full desired-state manifest against the current expert (targeted by `expert_id`, adopted by exact caller-owned name, or created fresh) and perform the minimal create/update/upload/delete set — custom skills included. Idempotent: re-applying an unchanged manifest is a no-op. `dry_run` returns the plan without applying; validation runs before any mutation and an invalid manifest applies nothing. `context_files` is the complete set (omitted names are pruned unless `prune_context_files` is false).","operationId":"apply_expert_manifest_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertApplyV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertApplyV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Apply a declarative expert manifest","tags":["Experts"]}},"/api/v2/experts/build":{"post":{"description":"Start the prompt-driven expert builder: describe a domain and the builder agent designs the expert (system prompt, skills, tools) in a sandbox. Poll `GET /api/v2/experts/build/{job_id}` for progress; on success the expert registers as a `building` draft — activate it with `PATCH /api/v2/experts/{expert_id}`.","operationId":"start_expert_build_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertBuildCreateRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertBuildResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Start an async expert build","tags":["Experts"]}},"/api/v2/experts/build/{job_id}":{"get":{"description":"Poll the status of an async expert build. Terminal states are `succeeded` (the `expert` field carries the registered draft) and `failed` (see `error`).","operationId":"get_expert_build_v2","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"title":"Job Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertBuildStatusResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"Get expert build status","tags":["Experts"]}},"/api/v2/experts/custom":{"get":{"description":"List custom experts you own or can access. Distinct from the unauthenticated `GET /api/v2/experts` registry list: this returns user-created experts, including `building` drafts.","operationId":"list_custom_experts_v2","parameters":[{"in":"query","name":"include_public","required":false,"schema":{"default":true,"title":"Include Public","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomExpertsListResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"List your custom experts","tags":["Experts"]}},"/api/v2/experts/extract":{"post":{"description":"Run the config extractor on a pasted SOP / agent config and return the clean system prompt, structured `output_sop` and `output_schema` without saving anything. Pass the results to `POST /api/v2/experts` or `PATCH /api/v2/experts/{expert_id}`.","operationId":"extract_expert_config_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertExtractV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertExtractV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Preview config extraction from pasted text","tags":["Experts"]}},"/api/v2/experts/generate-workflow":{"post":{"description":"Author and validate a workflow DSL from an SOP (and optional sample input / output schema) without saving. When `valid`, pass `workflow` as `pinned_workflow`. Available only on deployments with workflow authoring enabled (404 otherwise); rate limited per caller.","operationId":"generate_expert_workflow_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertGenerateWorkflowV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertGenerateWorkflowV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Preview a generated workflow for an SOP","tags":["Experts"]}},"/api/v2/experts/mcp-tools":{"get":{"description":"The tools an expert can be granted via `mcp_tool_names` (and required via `required_tool_calls`). Filter with `query`, `server`, `category`, `limit`. Entries flagged `always_on` ride along with every research run and need not be granted.","operationId":"list_expert_mcp_tools_v2","parameters":[{"in":"query","name":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"}},{"in":"query","name":"server","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Server"}},{"in":"query","name":"category","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},{"in":"query","name":"limit","required":false,"schema":{"default":200,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolsListV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"List MCP tools available to experts","tags":["Experts"]}},"/api/v2/experts/skills":{"get":{"description":"The skill catalog an expert can be linked to via `skill_names`, plus the custom skills you authored with `POST /api/v2/experts/skills`. Filter server-side with `query` (keyword match over name/description/tags), `category`, and `limit` (default 50); `total` reports the filtered match count so a capped response is recognizable.","operationId":"list_expert_skills_v2","parameters":[{"in":"query","name":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"}},{"in":"query","name":"category","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillsListV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"List skills available to experts","tags":["Experts"]},"post":{"description":"Author a custom skill (SKILL.md) that any of your experts can link via `skill_names`. Re-posting the same name overwrites your own skill in place (`created: false`).","operationId":"create_expert_skill_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkillV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkillV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Create a custom skill","tags":["Experts"]}},"/api/v2/experts/skills/{skill_name}":{"get":{"description":"Full SKILL.md content of a catalog skill or one of your custom skills.","operationId":"get_expert_skill_v2","parameters":[{"in":"path","name":"skill_name","required":true,"schema":{"title":"Skill Name","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillContentV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"Read a skill's SKILL.md","tags":["Experts"]}},"/api/v2/experts/validate":{"post":{"description":"Run every persistence-side validation — skill/tool names against the catalogs, required_tool_calls availability, output_schema JSON-Schema validity, output_template_file existence, pinned_workflow structure — and return ok/errors/warnings without persisting anything. Pass `expert_id` to validate an update against that expert's merged state; omit it to validate a fresh create.","operationId":"validate_expert_config_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertValidateV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertValidateV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Validate an expert config without saving","tags":["Experts"]}},"/api/v2/experts/{expert_id}":{"delete":{"description":"Archive a custom expert you own. The expert disappears from pickers and can no longer be run; its configuration and version history are kept. Idempotent.","operationId":"delete_expert_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertDeleteV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Archive a custom expert","tags":["Experts"]},"get":{"description":"Read the full configuration of a custom expert (by id or slug) or a built-in registry expert: system prompt, skills, tools, output type/schema/SOP, template, input form, context files, defaults, cost cap and sharing flags.","operationId":"get_expert_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertDetailV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"Get an expert's configuration","tags":["Experts"]},"patch":{"description":"Partial update: omitted fields are unchanged; lists replace; `output_template_file` accepts an empty string to clear; `pinned_workflow` and `max_cost_usd` accept an explicit `null` to clear. `status: active` finalizes a `building` draft. Publishing (`is_public`), `allow_free_tier_use` and `owner_email` are Parcha-admin-only. Every change is snapshotted as a restorable version.","operationId":"update_expert_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateExpertV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertDetailV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Update a custom expert","tags":["Experts"]}},"/api/v2/experts/{expert_id}/context-files":{"get":{"description":"Context files attached to an expert, merged from the expert repository and the text mirror.","operationId":"list_expert_context_files_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextFilesListV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"List context files","tags":["Experts"]},"post":{"description":"Upload a reference document (multipart `file`). Accepted: pdf, docx, pptx, xlsx, png, jpg, jpeg, gif, webp, and text formats (md, txt, json, yaml, csv, …). Archives (.zip) are rejected — expand them and upload the members. The original bytes are committed to the expert repository and the extracted text is mirrored onto the expert so runs, search and the output-template scaffold can use it. Re-uploading a name replaces it.","operationId":"upload_expert_context_file_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_expert_context_file_v2"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextFileUploadV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Attach a context file","tags":["Experts"]}},"/api/v2/experts/{expert_id}/context-files/import":{"post":{"description":"JSON alternative to the multipart upload for callers where inline bytes are impractical (MCP base64 puts the file through the agent's context window). Provide exactly one of `source_url` (server-side SSRF-guarded fetch: http(s) only, public addresses only, size-capped, redirects re-validated) or `attachment_id` (copy from a research attachment you own). The fetched bytes run the same admission as a direct upload — extension allowlist, archive rejection, binary magic-byte validation.","operationId":"import_expert_context_file_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextFileImportV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextFileUploadV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Import a context file by URL or from an attachment","tags":["Experts"]}},"/api/v2/experts/{expert_id}/context-files/{name}":{"delete":{"description":"Detach a context file: removes the text mirror entry and the repository copy. A file that is the current `output_template_file` must be cleared from that setting first.","operationId":"delete_expert_context_file_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}},{"in":"path","name":"name","required":true,"schema":{"title":"Name","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextFileDeleteV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Remove a context file","tags":["Experts"]},"get":{"description":"Raw bytes of one context file (original upload when present, otherwise the mirrored text).","operationId":"get_expert_context_file_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}},{"in":"path","name":"name","required":true,"schema":{"title":"Name","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}},"application/octet-stream":{}},"description":"The file bytes"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"Download a context file","tags":["Experts"]}},"/api/v2/experts/{expert_id}/plan-preview":{"post":{"description":"Run ONLY the planning phase with this expert attached — no sandbox, no research run — and return the plan the pipeline's planner would execute. Costs one cheap model call (rate limited per caller), so SOP edits can be iterated for cents instead of full runs. The preview covers the expert's planning contract (SOP, skills, tools, optional `context`); per-run inputs a real job adds — uploaded workspace files, connected customer tools — are not simulated.","operationId":"preview_expert_plan_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertPlanPreviewV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertPlanPreviewV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Preview the research plan for a question","tags":["Experts"]}},"/api/v2/experts/{expert_id}/share":{"delete":{"description":"Revoke a previously granted user, tenant, or team access.","operationId":"unshare_expert_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertUnshareV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertShareV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Revoke a share","tags":["Experts"]},"get":{"description":"Access grants on the expert (owner, Parcha admins, team admins, ACL admins).","operationId":"list_expert_shares_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertAccessListV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"List shares","tags":["Experts"]},"post":{"description":"Grant a user (email), an email-domain tenant, or a team access to the expert. Owners and ACL admins may share within their own email domain; Parcha admins may share anywhere.","operationId":"share_expert_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertShareV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertShareV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Share an expert","tags":["Experts"]}},"/api/v2/experts/{expert_id}/versions":{"get":{"description":"Version history of the expert's configuration, newest first (editors only).","operationId":"list_expert_versions_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertVersionsListV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"List configuration versions","tags":["Experts"]}},"/api/v2/experts/{expert_id}/versions/{version_num}":{"get":{"description":"The full configuration snapshot stored for a version.","operationId":"get_expert_version_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}},{"in":"path","name":"version_num","required":true,"schema":{"title":"Version Num","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertVersionDetailV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"Get one configuration version","tags":["Experts"]}},"/api/v2/experts/{expert_id}/versions/{version_num}/restore":{"post":{"description":"Roll the expert's configuration back to a version. The current configuration is snapshotted first (`new_version_num`) so the restore is itself reversible.","operationId":"restore_expert_version_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}},{"in":"path","name":"version_num","required":true,"schema":{"title":"Version Num","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertVersionRestoreV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Restore a configuration version","tags":["Experts"]}},"/api/v2/experts/{expert_id}/visibility":{"post":{"description":"Owner-only. Making an expert public (visible to everyone in the picker) is Parcha-admin-only; owners may always make it private again.","operationId":"set_expert_visibility_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertVisibilityV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertVisibilityV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:write"]}],"summary":"Set public/private visibility","tags":["Experts"]}},"/api/v2/keys":{"get":{"description":"Metadata only (label, display fragments, scopes, timestamps) — never the secret.","operationId":"list_keys_v2","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeysListV2Response"}}},"description":"Successful Response"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":[]}],"summary":"List your API keys","tags":["API Keys"]},"post":{"description":"Mint a `parcha-` API key for your own identity (OAuth authentication required — an API key cannot mint another key). Scopes must be a subset of the OAuth token's; omit to inherit them exactly. The secret is returned only in this response.","operationId":"create_key_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCreateV2Request"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCreateV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":[]}],"summary":"Create an API key","tags":["API Keys"]}},"/api/v2/keys/{key_id}":{"delete":{"description":"Revoke one of your keys. Idempotent — re-revoking an already-revoked key succeeds.","operationId":"revoke_key_v2","parameters":[{"in":"path","name":"key_id","required":true,"schema":{"title":"Key Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRevokeV2Response"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":[]}],"summary":"Revoke an API key","tags":["API Keys"]}},"/api/v2/quota":{"get":{"description":"Current quota for the authenticated caller.\n\nReturns the caller's subscription tier, remaining credits, and the\ncost in credits of each effort tier. To answer \"will my next call\nsucceed?\", compare ``credits_remaining`` against\n``credits_required_for_effort[<effort>]`` — or use\n``GET /quota/check?effort=<effort>`` for the same check in one\ncall.","operationId":"get_quota_v2","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotaResponse"}}},"description":"Successful Response"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["billing:read"]}],"summary":"Get Quota","tags":["Billing"]}},"/api/v2/quota/check":{"get":{"description":"Non-consuming quota check for a specific effort tier.\n\nReturns whether the caller has enough credits to run ``POST\n/research`` at the requested ``effort`` without actually starting\na job. Use this to gate UX (disable a \"Run\" button when the\nresponse says ``allowed=false``) instead of catching a 402 after\nsubmitting.","operationId":"check_quota_v2","parameters":[{"description":"Effort tier to pre-flight. Accepts the four public tiers (``low``, ``medium``, ``high``, ``build``) and the legacy aliases (``ultra_fast``, ``deep``, ``ultra_deep``) — same values the create endpoint accepts. The response echoes the value you sent.","in":"query","name":"effort","required":true,"schema":{"description":"Effort tier to pre-flight. Accepts the four public tiers (``low``, ``medium``, ``high``, ``build``) and the legacy aliases (``ultra_fast``, ``deep``, ``ultra_deep``) — same values the create endpoint accepts. The response echoes the value you sent.","enum":["low","medium","high","build","ultra_fast","deep","ultra_deep"],"title":"Effort","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotaCheckResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["billing:read"]}],"summary":"Check Quota","tags":["Billing"]}},"/api/v2/research":{"get":{"description":"List the caller's research jobs, newest first.\n\nCursor-paginated. Each row carries the minimum needed to render a\nlist and link to the detail view: ``job_id``, ``slug``, ``status``,\n``question``, ``effort``, and timestamps. Use ``GET\n/research/{job_id_or_slug}`` to fetch the full job — including the\nrendered report and revision history — for any row you want to\ninspect.","operationId":"list_research_jobs_v2","parameters":[{"description":"Opaque pagination cursor.","in":"query","name":"cursor","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque pagination cursor.","title":"Cursor"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_ResearchJobListItem_"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"List Research Jobs","tags":["Research"]},"post":{"description":"Start a research job.","operationId":"create_research_job_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchJobCreate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchJobResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Create Research Job","tags":["Research"]}},"/api/v2/research/{job_id_or_slug}":{"get":{"description":"Fetch a single research job by UUID or slug.\n\nReturns identity, lifecycle status, original request echo, timing\nmetadata, the rendered Markdown report (for completed jobs), and\nthe list of published revisions. The path parameter accepts either\na UUID or a human-readable slug.\n\nPass ``?revision=<sha>`` to read the report at a specific commit;\notherwise the latest report is returned.","operationId":"get_research_job_v2","parameters":[{"in":"path","name":"job_id_or_slug","required":true,"schema":{"title":"Job Id Or Slug","type":"string"}},{"description":"Optional commit SHA. When set, ``report.markdown`` is read from that revision instead of the current report. Use a ``commit_sha`` from the ``revisions`` array of an earlier call. ``404 revision_not_found`` if the SHA doesn't exist for this job.","in":"query","name":"revision","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional commit SHA. When set, ``report.markdown`` is read from that revision instead of the current report. Use a ``commit_sha`` from the ``revisions`` array of an earlier call. ``404 revision_not_found`` if the SHA doesn't exist for this job.","title":"Revision"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchJobDetail"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Get Research Job With Auth Context","tags":["Research"]},"patch":{"description":"Update mutable fields on a research job.\n\nSet ``is_public`` to ``true`` to make the job and its linked apps\npublicly viewable without authentication; set it to ``false`` to\nrevert them to owner/admin-only access. Jobs with linked apps can\nalso set ``anonymous_cta_enabled`` and ``anonymous_cta_variant`` in the same call.\n\nOnly the job's owner or a Parcha admin can change visibility.\nLocked jobs (content moderation) reject the call.","operationId":"update_research_job_v2","parameters":[{"in":"path","name":"job_id_or_slug","required":true,"schema":{"title":"Job Id Or Slug","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchVisibilityUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchVisibilityResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Update Research Job","tags":["Research"]}},"/api/v2/research/{job_id_or_slug}/cancel":{"post":{"description":"Cancel a queued or running research job.\n\nCancellation is terminal. The job status becomes ``cancelled`` and\nrunning check results are marked ``interrupted``. Repeating the call\nfor a terminal job is safe and returns the current terminal status.","operationId":"cancel_research_job_v2","parameters":[{"in":"path","name":"job_id_or_slug","required":true,"schema":{"title":"Job Id Or Slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchCancelResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Cancel Research Job Endpoint","tags":["Research"]}},"/api/v2/research/{job_id_or_slug}/continue":{"post":{"description":"Continue a completed research job in place.\n\nOnly successfully completed jobs can be continued. Active, paused,\nfailed, locked, and cancelled jobs return ``409`` with a stable\nmachine-readable error code.\n\nREST keeps the same Grep job id/slug and adds a new continuation\ncheck result. A2A uses this same service but returns the\ncontinuation check result as a new A2A task id so terminal A2A\ntasks are not restarted.","operationId":"continue_research_job_v2","parameters":[{"in":"path","name":"job_id_or_slug","required":true,"schema":{"title":"Job Id Or Slug","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchContinuationCreate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchContinuationResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Continue Research Job Endpoint","tags":["Research"]}},"/api/v2/research/{job_id_or_slug}/files":{"get":{"description":"List files in a research job's workspace.\n\nReturns every file the agent produced or modified during the run,\nwith sizes, MIME types, and last-commit timestamps. Use ``GET\n/research/{job_id_or_slug}/files/{file_path}`` to download individual\nfile contents.","operationId":"list_research_files_v2","parameters":[{"in":"path","name":"job_id_or_slug","required":true,"schema":{"title":"Job Id Or Slug","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchFilesList"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"List Research Files","tags":["Research"]}},"/api/v2/research/{job_id_or_slug}/files/{file_path}":{"get":{"description":"Download a single file from a research job's workspace.\n\nReturns the raw file bytes with a matching ``Content-Type``\nheader. ``file_path`` is the slash-separated path from any entry\nin the ``GET /research/{job_id_or_slug}/files`` listing.","operationId":"read_research_file_v2","parameters":[{"in":"path","name":"job_id_or_slug","required":true,"schema":{"title":"Job Id Or Slug","type":"string"}},{"in":"path","name":"file_path","required":true,"schema":{"title":"File Path","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Read Research File","tags":["Research"]}},"/api/v2/research/{job_id_or_slug}/timeline":{"get":{"description":"Paginated, recent-first execution timeline for a research job.\n\nReturns the events the agent emitted while working on the job —\ntool calls, sub-agent progress, thinking traces, text outputs.\nNewest first; walk older pages with the returned ``next_cursor``.\n\nEach event is a flat projection of the internal status-message\nlog (see ``TimelineEvent``). The full SDK content shape is\nintentionally not exposed; secrets, raw shell commands, and\ncost/token fields are stripped or redacted before the response\nis built.\n\nUse this to drive a \"what's the agent doing right now?\" UI by\npolling every few seconds while ``status`` is ``in_progress``.","operationId":"get_research_timeline_v2","parameters":[{"in":"path","name":"job_id_or_slug","required":true,"schema":{"title":"Job Id Or Slug","type":"string"}},{"description":"Opaque cursor from a previous response's ``next_cursor`` field.","in":"query","name":"cursor","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous response's ``next_cursor`` field.","title":"Cursor"}},{"description":"Maximum number of events to return per page (default 50, max 200).","in":"query","name":"limit","required":false,"schema":{"default":50,"description":"Maximum number of events to return per page (default 50, max 200).","maximum":200,"minimum":1,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_TimelineEvent_"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Get Research Timeline With Auth Context","tags":["Research"]}},"/api/v2/run":{"get":{"description":"List the caller's research jobs, newest first.\n\nCursor-paginated. Each row carries the minimum needed to render a\nlist and link to the detail view: ``job_id``, ``slug``, ``status``,\n``question``, ``effort``, and timestamps. Use ``GET\n/research/{job_id_or_slug}`` to fetch the full job — including the\nrendered report and revision history — for any row you want to\ninspect.","operationId":"list_runs_v2","parameters":[{"description":"Opaque pagination cursor.","in":"query","name":"cursor","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque pagination cursor.","title":"Cursor"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_ResearchJobListItem_"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"List Research Jobs","tags":["Research"]},"post":{"description":"Start a research job.","operationId":"create_run_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchJobCreate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchJobResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Create Research Job","tags":["Research"]}},"/api/v2/run/{job_id_or_slug}":{"get":{"description":"Fetch a single research job by UUID or slug.\n\nReturns identity, lifecycle status, original request echo, timing\nmetadata, the rendered Markdown report (for completed jobs), and\nthe list of published revisions. The path parameter accepts either\na UUID or a human-readable slug.\n\nPass ``?revision=<sha>`` to read the report at a specific commit;\notherwise the latest report is returned.","operationId":"get_run_v2","parameters":[{"in":"path","name":"job_id_or_slug","required":true,"schema":{"title":"Job Id Or Slug","type":"string"}},{"description":"Optional commit SHA. When set, ``report.markdown`` is read from that revision instead of the current report. Use a ``commit_sha`` from the ``revisions`` array of an earlier call. ``404 revision_not_found`` if the SHA doesn't exist for this job.","in":"query","name":"revision","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional commit SHA. When set, ``report.markdown`` is read from that revision instead of the current report. Use a ``commit_sha`` from the ``revisions`` array of an earlier call. ``404 revision_not_found`` if the SHA doesn't exist for this job.","title":"Revision"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchJobDetail"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Get Research Job With Auth Context","tags":["Research"]}}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"tags":[{"name":"Research"},{"name":"Attachments"},{"name":"Billing"},{"name":"Agent-to-Agent"}]}