{"components":{"schemas":{"ExpertBuilderInput":{"description":"Request body for starting an expert builder job.","properties":{"context":{"anyOf":[{"maxLength":5000,"type":"string"},{"type":"null"}],"description":"Additional context for the expert","title":"Context"},"depth":{"default":"standard","description":"Depth of expert (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":"ExpertBuilderInput","type":"object"},"ExpertInfo":{"description":"Information about an available research expert.","properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What this expert specializes in","title":"Description"},"entity_type":{"description":"Primary entity type (company, person, patent, etc.)","title":"Entity Type","type":"string"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Lucide icon name for UI","title":"Icon"},"id":{"description":"Expert ID to use in 'expert_id' parameter","title":"Id","type":"string"},"is_default":{"default":false,"description":"True if this is the default fallback expert","title":"Is Default","type":"boolean"},"mcp_tools":{"description":"MCP tools included with this expert","items":{"type":"string"},"title":"Mcp Tools","type":"array"},"name":{"description":"Display name","title":"Name","type":"string"},"skills":{"description":"Skills included with this expert","items":{"type":"string"},"title":"Skills","type":"array"}},"required":["id","name","entity_type"],"title":"ExpertInfo","type":"object"},"ExpertJobResponse":{"description":"Response from expert builder job creation.","properties":{"job_id":{"description":"Job ID for tracking","title":"Job Id","type":"string"},"message":{"description":"Response message","title":"Message","type":"string"},"status":{"description":"Job status","title":"Status","type":"string"}},"required":["job_id","status","message"],"title":"ExpertJobResponse","type":"object"},"ExpertsListResponse":{"description":"Available research experts.","properties":{"experts":{"items":{"$ref":"#/components/schemas/ExpertInfo"},"title":"Experts","type":"array"},"total_count":{"title":"Total Count","type":"integer"}},"required":["experts","total_count"],"title":"ExpertsListResponse","type":"object"},"GetResearchJobResponse":{"additionalProperties":true,"description":"Response shape for `GET /research/{job_id}`.\n\nDocuments the fields that are stable and part of the public contract.\nAdditional fields may be present — we use ``extra=\"allow\"`` so internal\nenrichment (status_messages, paused_context, clarification, input_payload,\netc.) does not break the OpenAPI contract. Customers should only rely on\nfields declared here; everything else may change without notice.","properties":{"browser_intervention_kind":{"anyOf":[{"enum":["authentication","user_action","managed_sign_in"],"type":"string"},{"type":"null"}],"description":"The kind of owner wait behind browser_intervention_state; managed_sign_in asks the owner to sign in.","title":"Browser Intervention Kind"},"browser_intervention_state":{"anyOf":[{"enum":["pending","recovery_required"],"type":"string"},{"type":"null"}],"description":"Whether browser work is waiting for the owner or needs recovery. Does not grant browser access.","title":"Browser Intervention State"},"budget_exhausted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether the final logical run ended through the budget wrap-up path.","title":"Budget Exhausted"},"can_edit":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether the caller can modify this job (owner or admin only).","title":"Can Edit"},"can_view_activity":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether the caller may read the job's agent activity (status messages): the owner, a Parcha admin, or a reader granted access to the job's expert.","title":"Can View Activity"},"check_results":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"description":"Agent output tree, including the final report under ``grep.open_research``. Each item has ``command_id``, ``status``, ``answer`` (rendered report), and ``payload`` (sources, confidence, structured_output when json_schema was supplied).","title":"Check Results"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the job reached a terminal state.","title":"Completed At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the job was created.","title":"Created At"},"error_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Machine-readable failure category, when present: a capped run's failure category, or ``agent_not_runnable``, ``needs_connection``, ``needs_reconnect`` or ``connection_revoked`` when the Agent's connections stopped the run before any work ran (``error_message`` says what to do).","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"},"failure_code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Machine-readable reason a job was rejected before execution, when present.","title":"Failure Code"},"failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Human-readable explanation of a pre-execution rejection, when present.","title":"Failure Reason"},"is_public":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether this job is publicly viewable without authentication.","title":"Is Public"},"job_id":{"description":"Job UUID.","title":"Job Id","type":"string"},"max_cost_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Caller-supplied provider-spend cap for each logical run.","title":"Max Cost Usd"},"run_completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Completed At"},"run_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Started At"},"session":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Claude session handle for continuing the conversation.","title":"Session"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Human-readable URL slug.","title":"Slug"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the job began executing.","title":"Started At"},"status":{"description":"Lifecycle status: queued, moderation, planning, running, completed, failed, blocked.","title":"Status","type":"string"},"status_messages":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"description":"Full status message stream emitted by the agent. Large.","title":"Status Messages"}},"required":["job_id","status"],"title":"GetResearchJobResponse","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"JobListItem":{"description":"Single job in list response.","properties":{"approach":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Approach"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"depth":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Depth"},"file_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"File Count"},"has_workspace":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Workspace"},"job_id":{"title":"Job Id","type":"string"},"question":{"title":"Question","type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"status":{"title":"Status","type":"string"}},"required":["job_id","status","question"],"title":"JobListItem","type":"object"},"JobListResponse":{"description":"Response from listing jobs.","properties":{"jobs":{"items":{"$ref":"#/components/schemas/JobListItem"},"title":"Jobs","type":"array"},"total":{"title":"Total","type":"integer"}},"required":["jobs","total"],"title":"JobListResponse","type":"object"},"MCPToolInfo":{"description":"Information about an available MCP tool.","properties":{"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Category: search, scraping, enrichment, screening, etc.","title":"Category"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Brief description of tool functionality","title":"Description"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Friendly label for the picker (e.g., 'web search v1beta search post').","title":"Display Name"},"is_default":{"description":"True if already included in research defaults","title":"Is Default","type":"boolean"},"name":{"description":"Full tool name (e.g., 'parallel:web_search_v1beta_search_post')","title":"Name","type":"string"},"server":{"description":"MCP server / provider name (e.g., 'brightdata', 'middesk')","title":"Server","type":"string"},"short_name":{"description":"Short name for display (e.g., 'web_search_v1beta_search_post')","title":"Short Name","type":"string"}},"required":["name","short_name","server","is_default"],"title":"MCPToolInfo","type":"object"},"MCPToolsListResponse":{"description":"Response for listing available MCP tools.","properties":{"servers":{"items":{"type":"string"},"title":"Servers","type":"array"},"tools":{"items":{"$ref":"#/components/schemas/MCPToolInfo"},"title":"Tools","type":"array"},"total_count":{"title":"Total Count","type":"integer"}},"required":["tools","servers","total_count"],"title":"MCPToolsListResponse","type":"object"},"ReportVersionListResponse":{"properties":{"versions":{"items":{"$ref":"#/components/schemas/ReportVersionSummary"},"title":"Versions","type":"array"}},"title":"ReportVersionListResponse","type":"object"},"ReportVersionSummary":{"properties":{"actor_label":{"title":"Actor Label","type":"string"},"actor_type":{"title":"Actor Type","type":"string"},"checkpoint_type":{"title":"Checkpoint Type","type":"string"},"commit_message":{"title":"Commit Message","type":"string"},"commit_sha":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commit Sha"},"created_at":{"format":"date-time","title":"Created At","type":"string"},"id":{"title":"Id","type":"string"},"job_id":{"title":"Job Id","type":"string"},"previous_commit_sha":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Previous Commit Sha"},"status":{"title":"Status","type":"string"},"updated_at":{"format":"date-time","title":"Updated At","type":"string"}},"required":["id","job_id","checkpoint_type","status","commit_message","actor_type","actor_label","created_at","updated_at"],"title":"ReportVersionSummary","type":"object"},"ResearchJobInput":{"description":"Input for starting a research job.","properties":{"action_mode":{"default":false,"description":"If True, implement changes (write code, create PRs) instead of producing a research report.","title":"Action Mode","type":"boolean"},"additional_thesis":{"anyOf":[{"maxLength":500000,"type":"string"},{"type":"null"}],"description":"Additional thesis to explore","title":"Additional Thesis"},"api_mode":{"default":true,"description":"If True (default for API), produce pure markdown without widget:html blocks. Set to False for widget:html blocks.","title":"Api Mode","type":"boolean"},"approach":{"anyOf":[{"enum":["scientific","technical","creative","general"],"type":"string"},{"type":"null"}],"description":"Research approach. If not provided, auto-determined from question.","title":"Approach"},"benchmark_mode":{"default":false,"description":"If True, skip HTML reporter and return raw markdown + structured sources for benchmark evaluation.","title":"Benchmark Mode","type":"boolean"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Additional context for the research","title":"Context"},"custom_mcp_tools":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Custom MCP tools to use","title":"Custom Mcp Tools"},"custom_skills":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Custom skills to use","title":"Custom Skills"},"effort":{"default":"ultra_fast","description":"Research effort level. When omitted, uses the agent default depth, or low if none is configured. New values: 'low' (~10-20s, Haiku), 'medium' (~2-3 min), 'high' (~8-15 min), 'build' (Opus 4.6, creative/app building). Legacy values: 'ultra_fast'→low, 'deep'→medium, 'ultra_deep'→high.","enum":["ultra_fast","deep","ultra_deep","low","medium","high","build"],"title":"Effort","type":"string"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Expert ID from registry (e.g., 'patent-expert', 'medical-expert'). Overrides auto-detection.","title":"Expert Id"},"from_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start date for content filtering (YYYY-MM-DD)","title":"From Date"},"from_suggested_topic":{"default":false,"description":"If True, job originated from an agent-suggested topic card. Bypasses the person-search private_individual gate (only). Does NOT bypass tier2_strike moderation.","title":"From Suggested Topic","type":"boolean"},"harness_sha":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Vendored agentrun harness variant for this job (advanced/experimental). Omit to use the deployment default. Ignored by the ``claude_agents`` runtime.","title":"Harness Sha"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional pre-generated job ID. Use this when workspace files have been uploaded.","title":"Job Id"},"json_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Custom output JSON Schema (draft-07). The request 422s with the reason when the schema cannot be compiled; annotation keywords outside the draft-07 vocabulary are dropped.","title":"Json Schema"},"max_cost_usd":{"anyOf":[{"maximum":1000.0,"minimum":0.5,"type":"number"},{"type":"null"}],"description":"Leave unset unless the user explicitly asks for a spending cap; never estimate one. 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``/``ultra_fast`` $0.50, ``medium``/``deep`` and ``build`` $2.50, ``high``/``ultra_deep`` $5.00. The normal billing margin still applies when provider cost is converted to credits.","title":"Max Cost Usd"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Override the AI model used for research. If provided, bypasses automatic tier-based model selection. Accepts a concrete model id (e.g., 'claude-opus-4-6', 'gpt-5.6-luna', 'deepseek-v4-pro') or a registry alias (e.g., 'luna', 'glm', 'deepseek'). Internal/benchmark use only.","title":"Model"},"model_config_profile":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Research model config profile name from RESEARCH_MODEL_CONFIGS (e.g., 'opus46_full', 'opus46_haiku_searcher', 'haiku_full')","title":"Model Config Profile"},"output_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Output type: 'report' (default) for a markdown report, 'data_explorer' for a tabular data app, 'structured_output' to return ONLY the structured JSON payload — no report and no artifact is written, so a run whose result is consumed by code skips the write-up entirely. Pair it with `json_schema` to shape the payload.","title":"Output Type"},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Workspace directory path (e.g. 'experts/flutterwave_mcc'). If set, reads instructions.md from this directory and uses it as the agent's system prompt. The job runs under a dedicated project brain.","title":"Project"},"question":{"description":"The research question to investigate","title":"Question","type":"string"},"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":"Language for research report (ISO 639-1 code: en, es, fr, de, pt, ja, ko, zh-CN, it, nl)","title":"Response Language","type":"string"},"runtime":{"anyOf":[{"enum":["claude_agents","agentrun"],"type":"string"},{"type":"null"}],"description":"Agent runtime harness. When omitted, resolves to the server default (GREP_DEFAULT_RESEARCH_HARNESS, else claude_agents) — see default_research_harness(). An explicit value always wins.","title":"Runtime"},"search_tool_override":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search tool variant for eval: 'anthropic_native_websearch', 'parallel_mcp_native', 'custom_wrapped_parallel'","title":"Search Tool Override"},"skip_clarification":{"default":false,"description":"If True, skip clarification questions even if the planner requests them. Useful for automated/webhook jobs.","title":"Skip Clarification","type":"boolean"},"skip_moderation_block":{"default":false,"description":"If True, run moderation but don't block job on violations. Parcha admins may auto-enable this.","title":"Skip Moderation Block","type":"boolean"},"status_webhook_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Optional filter for message types to send. E.g., ['Thinking', 'UserMessage', 'status']. If None, sends ALL messages.","title":"Status Webhook Filter"},"status_webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Webhook URL to receive ALL status messages in real-time. Each message POSTed with: job_id, message, message_type, timestamp, metadata","title":"Status Webhook Url"},"structured_input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Raw structured (JSON object) input, persisted to the job so the agent can read it.","title":"Structured Input"},"to_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End date for content filtering (YYYY-MM-DD)","title":"To Date"},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Webhook URL for completion notification","title":"Webhook Url"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Website URL for enriched context","title":"Website"}},"required":["question"],"title":"ResearchJobInput","type":"object"},"ResearchJobResponse":{"description":"Response from starting a run.","properties":{"downgrade":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Downgrade"},"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":{"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"},"RunInput":{"description":"Input for ``POST /run`` — the agent-run shadow of ``POST /research``.\n\nSlice B (additive): ``/run`` is a thin alias over ``/research`` that\naccepts a single polymorphic ``input`` field instead of ``question``:\n\n* ``input`` is a **string**  → used verbatim as the run question.\n* ``input`` is a **JSON object** → JSON-serialized into the question and\n  the raw object persisted to ``Job.input_payload['structured_input']``\n  so the agent can read the original structure back.\n\nEvery OTHER field is inherited unchanged from ``ResearchJobInput``\n(``effort``/``depth``, ``approach``, ``expert_id``, ``response_language``,\n``webhook_url``, etc.) so a ``/run`` call has the full ``/research``\nsurface. ``question`` and ``structured_input`` are inherited internals\nthat callers do NOT set directly — ``input`` drives both. They are kept\nout of the request schema via ``exclude``/``Field(exclude=...)`` so the\npublic OpenAPI for ``/run`` advertises ``input`` as the one entrypoint.","properties":{"action_mode":{"default":false,"description":"If True, implement changes (write code, create PRs) instead of producing a research report.","title":"Action Mode","type":"boolean"},"additional_thesis":{"anyOf":[{"maxLength":500000,"type":"string"},{"type":"null"}],"description":"Additional thesis to explore","title":"Additional Thesis"},"api_mode":{"default":true,"description":"If True (default for API), produce pure markdown without widget:html blocks. Set to False for widget:html blocks.","title":"Api Mode","type":"boolean"},"approach":{"anyOf":[{"enum":["scientific","technical","creative","general"],"type":"string"},{"type":"null"}],"description":"Research approach. If not provided, auto-determined from question.","title":"Approach"},"benchmark_mode":{"default":false,"description":"If True, skip HTML reporter and return raw markdown + structured sources for benchmark evaluation.","title":"Benchmark Mode","type":"boolean"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Additional context for the research","title":"Context"},"custom_mcp_tools":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Custom MCP tools to use","title":"Custom Mcp Tools"},"custom_skills":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Custom skills to use","title":"Custom Skills"},"effort":{"default":"ultra_fast","description":"Research effort level. When omitted, uses the agent default depth, or low if none is configured. New values: 'low' (~10-20s, Haiku), 'medium' (~2-3 min), 'high' (~8-15 min), 'build' (Opus 4.6, creative/app building). Legacy values: 'ultra_fast'→low, 'deep'→medium, 'ultra_deep'→high.","enum":["ultra_fast","deep","ultra_deep","low","medium","high","build"],"title":"Effort","type":"string"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Expert ID from registry (e.g., 'patent-expert', 'medical-expert'). Overrides auto-detection.","title":"Expert Id"},"from_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start date for content filtering (YYYY-MM-DD)","title":"From Date"},"from_suggested_topic":{"default":false,"description":"If True, job originated from an agent-suggested topic card. Bypasses the person-search private_individual gate (only). Does NOT bypass tier2_strike moderation.","title":"From Suggested Topic","type":"boolean"},"harness_sha":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Vendored agentrun harness variant for this job (advanced/experimental). Omit to use the deployment default. Ignored by the ``claude_agents`` runtime.","title":"Harness Sha"},"input":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"}],"description":"The run input. Either a plain string (used as the question) or a JSON object (serialized into the question and persisted raw so the agent can read the structured input).","title":"Input"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional pre-generated job ID. Use this when workspace files have been uploaded.","title":"Job Id"},"json_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Custom output JSON Schema (draft-07). The request 422s with the reason when the schema cannot be compiled; annotation keywords outside the draft-07 vocabulary are dropped.","title":"Json Schema"},"max_cost_usd":{"anyOf":[{"maximum":1000.0,"minimum":0.5,"type":"number"},{"type":"null"}],"description":"Leave unset unless the user explicitly asks for a spending cap; never estimate one. 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``/``ultra_fast`` $0.50, ``medium``/``deep`` and ``build`` $2.50, ``high``/``ultra_deep`` $5.00. The normal billing margin still applies when provider cost is converted to credits.","title":"Max Cost Usd"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Override the AI model used for research. If provided, bypasses automatic tier-based model selection. Accepts a concrete model id (e.g., 'claude-opus-4-6', 'gpt-5.6-luna', 'deepseek-v4-pro') or a registry alias (e.g., 'luna', 'glm', 'deepseek'). Internal/benchmark use only.","title":"Model"},"model_config_profile":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Research model config profile name from RESEARCH_MODEL_CONFIGS (e.g., 'opus46_full', 'opus46_haiku_searcher', 'haiku_full')","title":"Model Config Profile"},"output_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Output type: 'report' (default) for a markdown report, 'data_explorer' for a tabular data app, 'structured_output' to return ONLY the structured JSON payload — no report and no artifact is written, so a run whose result is consumed by code skips the write-up entirely. Pair it with `json_schema` to shape the payload.","title":"Output Type"},"project":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Workspace directory path (e.g. 'experts/flutterwave_mcc'). If set, reads instructions.md from this directory and uses it as the agent's system prompt. The job runs under a dedicated project brain.","title":"Project"},"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":"Language for research report (ISO 639-1 code: en, es, fr, de, pt, ja, ko, zh-CN, it, nl)","title":"Response Language","type":"string"},"runtime":{"anyOf":[{"enum":["claude_agents","agentrun"],"type":"string"},{"type":"null"}],"description":"Agent runtime harness. When omitted, resolves to the server default (GREP_DEFAULT_RESEARCH_HARNESS, else claude_agents) — see default_research_harness(). An explicit value always wins.","title":"Runtime"},"search_tool_override":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search tool variant for eval: 'anthropic_native_websearch', 'parallel_mcp_native', 'custom_wrapped_parallel'","title":"Search Tool Override"},"skip_clarification":{"default":false,"description":"If True, skip clarification questions even if the planner requests them. Useful for automated/webhook jobs.","title":"Skip Clarification","type":"boolean"},"skip_moderation_block":{"default":false,"description":"If True, run moderation but don't block job on violations. Parcha admins may auto-enable this.","title":"Skip Moderation Block","type":"boolean"},"status_webhook_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Optional filter for message types to send. E.g., ['Thinking', 'UserMessage', 'status']. If None, sends ALL messages.","title":"Status Webhook Filter"},"status_webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Webhook URL to receive ALL status messages in real-time. Each message POSTed with: job_id, message, message_type, timestamp, metadata","title":"Status Webhook Url"},"to_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End date for content filtering (YYYY-MM-DD)","title":"To Date"},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Webhook URL for completion notification","title":"Webhook Url"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Website URL for enriched context","title":"Website"}},"required":["input"],"title":"RunInput","type":"object"},"SkillInfo":{"description":"Information about an available skill.","properties":{"can_edit":{"default":false,"description":"True when the caller may edit this skill","title":"Can Edit","type":"boolean"},"can_publish":{"default":false,"description":"True only for Parcha admins","title":"Can Publish","type":"boolean"},"can_share":{"default":false,"description":"True when the caller may manage this skill's access list","title":"Can Share","type":"boolean"},"category":{"description":"Category: research, business, person, ui, other","title":"Category","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description extracted from SKILL.md","title":"Description"},"granted_to_me":{"default":false,"description":"True when the caller sees this skill through an ACL grant","title":"Granted To Me","type":"boolean"},"is_custom":{"default":false,"description":"True if the skill is a user/agent-builder-created skill not in the static catalog","title":"Is Custom","type":"boolean"},"is_owned_by_me":{"default":false,"description":"True when the caller owns this custom skill","title":"Is Owned By Me","type":"boolean"},"is_owner":{"default":false,"description":"Compatibility alias for is_owned_by_me","title":"Is Owner","type":"boolean"},"is_public":{"default":false,"description":"Readable and usable by all signed-in users","title":"Is Public","type":"boolean"},"is_shared":{"default":false,"description":"True when the caller sees this skill through an ACL grant","title":"Is Shared","type":"boolean"},"name":{"description":"Skill directory name (e.g., 'research-scientific-literature')","title":"Name","type":"string"},"owner_email":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Compatibility alias for the custom skill owner","title":"Owner Email"},"owner_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Owner email or user ID for a custom skill","title":"Owner Id"},"searchable_text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Concatenated text (name + description + tags + body excerpt) the picker uses for free-text search so the user can find skills by content, not just title.","title":"Searchable Text"},"skill_files":{"description":"Files stored in the custom skill directory, relative to its root","items":{"type":"string"},"title":"Skill Files","type":"array"},"skill_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stable database ID for a custom skill","title":"Skill Id"},"suggested_tools":{"description":"MCP tool names (full mcp__server__tool identifier) the skill typically needs","items":{"type":"string"},"title":"Suggested Tools","type":"array"},"tags":{"description":"Optional frontmatter tags / keywords surfaced for filtering and search","items":{"type":"string"},"title":"Tags","type":"array"}},"required":["name","category"],"title":"SkillInfo","type":"object"},"SkillsListResponse":{"description":"Response for listing available skills.","properties":{"categories":{"items":{"type":"string"},"title":"Categories","type":"array"},"skills":{"items":{"$ref":"#/components/schemas/SkillInfo"},"title":"Skills","type":"array"},"total_count":{"title":"Total Count","type":"integer"}},"required":["skills","categories","total_count"],"title":"SkillsListResponse","type":"object"},"UnstickJobRequest":{"description":"Request body for unstick endpoint.","properties":{"expected_lifecycle_generation":{"anyOf":[{"minimum":1.0,"type":"integer"},{"type":"null"}],"title":"Expected Lifecycle Generation"},"restart_run_store":{"default":false,"description":"Start the job's check result over under a new AgentRun run store instead of resuming the refused one. Use it when the unstick is refused because the harness will not open the run's store (binding mismatch, outdated schema, or run id mismatch): the refused store is moved aside to `<key>.refused-<utc timestamp>` beside where it was, where it stays readable, and the successor runs on a fresh sandbox with the same owner, expert and inputs. AgentRun runs only.","title":"Restart Run Store","type":"boolean"},"steering_message":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional override guidance injected into Claude's prompt on the resumed turn. Mirrors the `guidance` arg of `brain_job_manager.continue_managed_run`. Omit to resume without any extra instruction — the agent continues from its existing claude_session_id as if nothing happened.","title":"Steering Message"}},"title":"UnstickJobRequest","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"}}},"info":{"description":"> ⚠️ **v1 is deprecated.** New integrations should use [v2](/api/v2/openapi.json). v1 will continue to work for existing callers but no new features will be added.\n\nProgrammatic 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","x-deprecated":true},"openapi":"3.1.0","paths":{"/api/v1/agents":{"get":{"description":"List available research experts (also served at ``/agents`` and ``/run/agents``).\n\nUse these expert IDs in the 'expert_id' parameter when starting research\nto get specialized research behavior for specific domains.\n\nExample expert IDs:\n- 'patent-expert' - Patent research with USPTO, EPO, Google Patents\n- 'medical-expert' - Medical research with PubMed, clinical trials\n- 'legal-expert' - Legal research with CourtListener, case law\n- 'supply-chain-expert' - Supply chain with World Bank trade data","operationId":"list_available_experts_api_v1_agents_get","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertsListResponse"}}},"description":"Successful Response"}},"summary":"List Available Experts","tags":["grep-public-api"]}},"/api/v1/apps":{"get":{"description":"List app artifacts for the authenticated user.","operationId":"list_apps_api_v1_apps_get","parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"title":"Limit","type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"title":"Offset","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"title":"Response List Apps Api V1 Apps Get","type":"object"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Apps","tags":["grep-public-api"]}},"/api/v1/apps/{app_id}":{"get":{"description":"Get app artifact detail.","operationId":"get_app_api_v1_apps__app_id__get","parameters":[{"in":"path","name":"app_id","required":true,"schema":{"title":"App Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"title":"Response Get App Api V1 Apps  App Id  Get","type":"object"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get App","tags":["grep-public-api"]}},"/api/v1/expert/start":{"post":{"description":"Start a new expert builder job.\n\nThis endpoint initiates an expert building pipeline with 3 phases:\n1. Expert Planning - Analyze domain, identify expertise areas, generate clarification questions\n2. Skill Creation - Create skills based on depth (standard: ~3, deep: ~8)\n3. Expert Registration - Register expert in DB and GCS\n\nRequires USER or API_KEY authentication with expert access.\n\nArgs:\n    input_data: Expert parameters including domain, depth, and optional context\n\nReturns:\n    ExpertJobResponse with job_id for tracking\n\nExample:\n    POST /api/v1/expert/start\n    {\n        \"domain\": \"Machine learning for fraud detection in payments\",\n        \"depth\": \"deep\",\n        \"context\": \"Focus on real-time detection techniques\"\n    }","operationId":"start_expert_builder_job_api_v1_expert_start_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertBuilderInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertJobResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Start Expert Builder Job","tags":["grep-public-api"]}},"/api/v1/jobs":{"get":{"deprecated":true,"description":"**Deprecated**. Use `GET /research` instead.\n\nForwards to the same handler; response body is identical.","operationId":"list_jobs_deprecated_api_v1_jobs_get","parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"title":"Limit","type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"title":"Offset","type":"integer"}},{"in":"query","name":"include_workspace_status","required":false,"schema":{"default":false,"title":"Include Workspace Status","type":"boolean"}},{"in":"query","name":"team_scope","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Team Scope"}},{"in":"query","name":"billing_tenant_id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Tenant Id"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobListResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Jobs Deprecated","tags":["grep-public-api"]}},"/api/v1/jobs/{job_id}":{"get":{"deprecated":true,"description":"**Deprecated**. Use `GET /research/{job_id}` instead.\n\nForwards to the same handler; response body is identical. Sets the\n`Deprecation: true` response header so automated clients can detect\nthe transition.","operationId":"get_job_by_id_deprecated_api_v1_jobs__job_id__get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"string"}],"title":"Job Id"}},{"in":"query","name":"include_check_results","required":false,"schema":{"default":false,"title":"Include Check Results","type":"boolean"}},{"in":"query","name":"include_status_messages","required":false,"schema":{"default":false,"title":"Include Status Messages","type":"boolean"}},{"in":"query","name":"include_session","required":false,"schema":{"default":false,"title":"Include Session","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResearchJobResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get Job By Id Deprecated","tags":["grep-public-api"]}},"/api/v1/jobs/{job_id}/checkpoints":{"get":{"description":"List report version checkpoints for a job.","operationId":"job_checkpoints_api_v1_jobs__job_id__checkpoints_get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"title":"Job Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportVersionListResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Job Checkpoints","tags":["grep-public-api"]}},"/api/v1/jobs/{job_id}/files":{"get":{"description":"List files in a job's code.storage workspace. Owner/admin only — the\nworkspace is private even when the report is public.","operationId":"job_list_files_api_v1_jobs__job_id__files_get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"title":"Job Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"title":"Response Job List Files Api V1 Jobs  Job Id  Files Get","type":"object"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Job List Files","tags":["grep-public-api"]}},"/api/v1/jobs/{job_id}/files/{file_path}":{"get":{"description":"Read a file from a job's code.storage workspace. Owner/admin only.","operationId":"job_read_file_api_v1_jobs__job_id__files__file_path__get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"title":"Job Id","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"}},"summary":"Job Read File","tags":["grep-public-api"]}},"/api/v1/jobs/{job_id}/report":{"get":{"description":"Get the report.md for a job (shortcut for /jobs/{id}/files/report.md).","operationId":"job_report_api_v1_jobs__job_id__report_get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"title":"Job Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Job Report","tags":["grep-public-api"]}},"/api/v1/mcp-tools/available":{"get":{"description":"List all MCP tools the Expert Builder can attach to an expert.\n\nSource of truth: the tool manifests in the backend tool registry. Each\nmanifest's static `[[tools]]` is enumerated; OpenAPI-handler manifests fall\nback to canonical entries in TOOL_TO_KEY_MAP (the dispatcher's allow-list).\nDynamic-MCP providers with no static tools emit a single provider-level\nbundle so users can attach the whole server. The parcha-tools\ndocument-verification tools are appended statically — they are native MCP\ntools served by the parcha-tools sibling service, not registry providers.","operationId":"list_available_mcp_tools_api_v1_mcp_tools_available_get","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPToolsListResponse"}}},"description":"Successful Response"}},"summary":"List Available Mcp Tools","tags":["grep-public-api"]}},"/api/v1/research":{"get":{"description":"List research jobs for the authenticated user.\n\nRequires USER or API_KEY authentication (not capability-based).\n\nArgs:\n    include_workspace_status: If true, includes has_workspace and file_count per job.","operationId":"list_research_jobs_api_v1_research_get","parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"title":"Limit","type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"title":"Offset","type":"integer"}},{"in":"query","name":"include_workspace_status","required":false,"schema":{"default":false,"title":"Include Workspace Status","type":"boolean"}},{"description":"Scope the listing by billing team: 'active' (the caller's current team, personal when none), 'personal', or an explicit team tenant id. Omit for the unscoped legacy listing.","in":"query","name":"team_scope","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Scope the listing by billing team: 'active' (the caller's current team, personal when none), 'personal', or an explicit team tenant id. Omit for the unscoped legacy listing.","title":"Team Scope"}},{"description":"The client's active-team hint, forwarded exactly as job submission sends it so 'active' scoping resolves the same pool admission would bill. Ignored unless team_scope='active'.","in":"query","name":"billing_tenant_id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The client's active-team hint, forwarded exactly as job submission sends it so 'active' scoping resolves the same pool admission would bill. Ignored unless team_scope='active'.","title":"Billing Tenant Id"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobListResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Research Jobs","tags":["grep-public-api"]},"post":{"description":"Start a new research job.\n\nRequires USER or API_KEY authentication (not capability-based).\n\nExpert ACL is validated upstream by ``_validate_research_expert_acl``\n— by the time we get here, the caller is guaranteed to be entitled\nto dispatch against ``input_data.expert_id`` (or it's None / a\npublic registry id).\n\nReturns:\n    ResearchJobResponse with job_id for tracking","operationId":"start_research_api_v1_research_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchJobInput"}}},"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"}},"summary":"Start Research","tags":["grep-public-api"]}},"/api/v1/research/experts":{"get":{"description":"List available research experts (also served at ``/agents`` and ``/run/agents``).\n\nUse these expert IDs in the 'expert_id' parameter when starting research\nto get specialized research behavior for specific domains.\n\nExample expert IDs:\n- 'patent-expert' - Patent research with USPTO, EPO, Google Patents\n- 'medical-expert' - Medical research with PubMed, clinical trials\n- 'legal-expert' - Legal research with CourtListener, case law\n- 'supply-chain-expert' - Supply chain with World Bank trade data","operationId":"list_available_experts_api_v1_research_experts_get","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertsListResponse"}}},"description":"Successful Response"}},"summary":"List Available Experts","tags":["grep-public-api"]}},"/api/v1/research/{job_id}":{"get":{"description":"Get details of a research job by ID or slug.\n\nAccepts either a UUID (e.g., /research/550e8400-...) or a human-readable\nslug (e.g., /research/what-is-stripe). Backward-compatible: UUID URLs\nkeep working with zero DB overhead.\n\nAll auth modes supported. Public jobs can be read in capability mode with only the job_id.","operationId":"get_research_job_api_v1_research__job_id__get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"string"}],"title":"Job Id"}},{"in":"query","name":"include_check_results","required":false,"schema":{"default":false,"title":"Include Check Results","type":"boolean"}},{"in":"query","name":"include_status_messages","required":false,"schema":{"default":false,"title":"Include Status Messages","type":"boolean"}},{"in":"query","name":"include_session","required":false,"schema":{"default":false,"title":"Include Session","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResearchJobResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get Research Job","tags":["grep-public-api"]}},"/api/v1/research/{job_id}/cached-image":{"get":{"description":"Serve a report-embedded image from the Redis cache.\n\nUsed by the PDF export pipeline to short-circuit slow third-party CDNs.\nOn cache miss, falls back to a live fetch and warms the cache so the\nnext request hits.\n\nACL: same as the parent job — public job, owner, or admin.","operationId":"get_cached_report_image_api_v1_research__job_id__cached_image_get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"string"}],"title":"Job Id"}},{"description":"URL-safe base64 of the original image URL","in":"query","name":"u","required":true,"schema":{"description":"URL-safe base64 of the original image URL","title":"U","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get Cached Report Image","tags":["grep-public-api"]}},"/api/v1/research/{job_id}/clarify":{"post":{"description":"Submit answers to clarification questions for a paused research job.\n\nAll auth modes supported with write access.","operationId":"submit_clarification_api_v1_research__job_id__clarify_post","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"string"}],"title":"Job Id"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"title":"Body","type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"title":"Response Submit Clarification Api V1 Research  Job Id  Clarify Post","type":"object"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Submit Clarification","tags":["grep-public-api"]}},"/api/v1/research/{job_id}/pdf":{"get":{"description":"Export a research job's report as a PDF.\n\nBuilds the same body the UI renders. The set of check_results considered\ndepends on the job's agent:\n  - Default research jobs: ``grep.open_research``, ``grep.research_follow_up``,\n    ``grep.report_revision``.\n  - ``grep-brain`` parent jobs: also pulls sub-jobs' check_results\n    (``grep.expert_chat``, ``grep.research_fork_chat``) plus the\n    scheduled/recurring/user-edit revision command_ids.\n  - Brain sub-jobs (``grep-expert-chat-v1`` / ``grep-research-fork-chat``):\n    same expanded set scoped to the sub-job itself.\n\nFrom those rows, ``_select_primary_and_followups`` picks one primary\nreport (mirroring ``ResearchJob.tsx`` — latest completed revision wins,\nfalling back to a running revision with body, then ``open_research``,\nthen the first non-followup) and a list of appended sections\n(``grep.research_follow_up`` and non-revision brain sub-reports). The\nprimary's body comes from ``payload.report`` (preferred) or ``answer``.\nBrowserbase renders the resulting markdown via ``build_pdf_html`` →\n``generate_pdf_from_html``, with a basic ``markdown_pdf`` fallback if\nBrowserbase is unavailable.","operationId":"export_research_job_pdf_api_v1_research__job_id__pdf_get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"string"}],"title":"Job Id"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Export Research Job Pdf","tags":["grep-public-api"]}},"/api/v1/research/{job_id}/session-file-viewer/{file_path}":{"get":{"description":"Return rich-viewer metadata for a workspace file.\n\nAccess: owner or Parcha admin only (see ``_require_workspace_access``).","operationId":"get_session_file_viewer_api_v1_research__job_id__session_file_viewer__file_path__get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"string"}],"title":"Job Id"}},{"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"}},"summary":"Get Session File Viewer","tags":["grep-public-api"]}},"/api/v1/research/{job_id}/session-files":{"get":{"description":"List files in the agent's workspace.\n\nFor completed jobs: reads from code.storage (Pierre Storage API) — no sandbox needed.\nFor running jobs or fallback: reads from sandbox persistent volume.\n\nAccess: owner or Parcha admin only. Public-job CAPABILITY callers and\nnon-owner authenticated callers get 403 — the public link exposes the\nreport + sources, not the agent's workspace.","operationId":"get_session_files_api_v1_research__job_id__session_files_get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"string"}],"title":"Job Id"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"title":"Response Get Session Files Api V1 Research  Job Id  Session Files Get","type":"object"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get Session Files","tags":["grep-public-api"]}},"/api/v1/research/{job_id}/session-files/{file_path}":{"get":{"description":"Get the content of a specific file from the agent's sandbox workspace.\n\nAccess: owner or Parcha admin only (see ``_require_workspace_access``).\nPublic-job CAPABILITY callers and non-owner authenticated callers get 403.","operationId":"get_session_file_content_api_v1_research__job_id__session_files__file_path__get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"string"}],"title":"Job Id"}},{"in":"path","name":"file_path","required":true,"schema":{"title":"File Path","type":"string"}},{"description":"Return raw binary file content instead of JSON wrapper","in":"query","name":"raw","required":false,"schema":{"default":false,"description":"Return raw binary file content instead of JSON wrapper","title":"Raw","type":"boolean"}},{"description":"Set Content-Disposition to attachment for download","in":"query","name":"download","required":false,"schema":{"default":false,"description":"Set Content-Disposition to attachment for download","title":"Download","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get Session File Content","tags":["grep-public-api"]}},"/api/v1/run":{"get":{"description":"List research jobs for the authenticated user.\n\nRequires USER or API_KEY authentication (not capability-based).\n\nArgs:\n    include_workspace_status: If true, includes has_workspace and file_count per job.","operationId":"list_research_jobs_api_v1_run_get","parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"title":"Limit","type":"integer"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"title":"Offset","type":"integer"}},{"in":"query","name":"include_workspace_status","required":false,"schema":{"default":false,"title":"Include Workspace Status","type":"boolean"}},{"description":"Scope the listing by billing team: 'active' (the caller's current team, personal when none), 'personal', or an explicit team tenant id. Omit for the unscoped legacy listing.","in":"query","name":"team_scope","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Scope the listing by billing team: 'active' (the caller's current team, personal when none), 'personal', or an explicit team tenant id. Omit for the unscoped legacy listing.","title":"Team Scope"}},{"description":"The client's active-team hint, forwarded exactly as job submission sends it so 'active' scoping resolves the same pool admission would bill. Ignored unless team_scope='active'.","in":"query","name":"billing_tenant_id","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The client's active-team hint, forwarded exactly as job submission sends it so 'active' scoping resolves the same pool admission would bill. Ignored unless team_scope='active'.","title":"Billing Tenant Id"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobListResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Research Jobs","tags":["grep-public-api"]},"post":{"description":"Start a new agent run (shadow of ``POST /research``).\n\nAccepts a single ``input`` field — a string (used as the question) or a\nJSON object (serialized into the question, with the raw object persisted\nto the job so the agent can read it). All other fields match\n``POST /research``.\n\nRequires USER or API_KEY authentication (not capability-based). Expert\nACL is validated upstream by ``_validate_run_expert_acl``. The run is\npollable under both ``/run/{job_id}`` and ``/research/{job_id}``.\n\nReturns:\n    ResearchJobResponse with job_id for tracking","operationId":"start_run_api_v1_run_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunInput"}}},"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"}},"summary":"Start Run","tags":["grep-public-api"]}},"/api/v1/run/agents":{"get":{"description":"List available research experts (also served at ``/agents`` and ``/run/agents``).\n\nUse these expert IDs in the 'expert_id' parameter when starting research\nto get specialized research behavior for specific domains.\n\nExample expert IDs:\n- 'patent-expert' - Patent research with USPTO, EPO, Google Patents\n- 'medical-expert' - Medical research with PubMed, clinical trials\n- 'legal-expert' - Legal research with CourtListener, case law\n- 'supply-chain-expert' - Supply chain with World Bank trade data","operationId":"list_available_experts_api_v1_run_agents_get","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertsListResponse"}}},"description":"Successful Response"}},"summary":"List Available Experts","tags":["grep-public-api"]}},"/api/v1/run/{job_id}":{"get":{"description":"Get details of a research job by ID or slug.\n\nAccepts either a UUID (e.g., /research/550e8400-...) or a human-readable\nslug (e.g., /research/what-is-stripe). Backward-compatible: UUID URLs\nkeep working with zero DB overhead.\n\nAll auth modes supported. Public jobs can be read in capability mode with only the job_id.","operationId":"get_research_job_api_v1_run__job_id__get","parameters":[{"in":"path","name":"job_id","required":true,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"string"}],"title":"Job Id"}},{"in":"query","name":"include_check_results","required":false,"schema":{"default":false,"title":"Include Check Results","type":"boolean"}},{"in":"query","name":"include_status_messages","required":false,"schema":{"default":false,"title":"Include Status Messages","type":"boolean"}},{"in":"query","name":"include_session","required":false,"schema":{"default":false,"title":"Include Session","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResearchJobResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get Research Job","tags":["grep-public-api"]}},"/api/v1/skills/available":{"get":{"description":"List all available skills for research customization.\n\nUSER callers receive the filesystem catalog and their visible custom skills.\nAPI-key and other caller modes receive the filesystem catalog only.","operationId":"list_available_skills_api_v1_skills_available_get","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillsListResponse"}}},"description":"Successful Response"}},"summary":"List Available Skills","tags":["grep-public-api"]}},"/api/v1/unstick/{check_result_id}":{"post":{"description":"Command-id-agnostic resume for stuck brain-managed subjobs.\n\nAccepts Descope JWT (`/grep/unstick`) or API keys (`/api/v1/unstick`).","operationId":"unstick_job_api_v1_unstick__check_result_id__post","parameters":[{"in":"path","name":"check_result_id","required":true,"schema":{"title":"Check Result Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnstickJobRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"title":"Response Unstick Job Api V1 Unstick  Check Result Id  Post","type":"object"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Unstick Job","tags":["grep-public-api"]}},"/api/v1/workspace/files":{"get":{"description":"List files in a workspace directory.\n\nReturns: { \"files\": [{ \"path\": \"...\", \"size\": N, ... }], \"path\": \"...\" }","operationId":"workspace_list_files_api_v1_workspace_files_get","parameters":[{"description":"Subdirectory path to list (e.g. 'projects/acme')","in":"query","name":"path","required":false,"schema":{"default":"","description":"Subdirectory path to list (e.g. 'projects/acme')","title":"Path","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"title":"Response Workspace List Files Api V1 Workspace Files Get","type":"object"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Workspace List Files","tags":["grep-public-api"]}},"/api/v1/workspace/files/{file_path}":{"get":{"description":"Read a workspace file's contents. Returns raw bytes with appropriate content-type.","operationId":"workspace_read_file_api_v1_workspace_files__file_path__get","parameters":[{"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"}},"summary":"Workspace Read File","tags":["grep-public-api"]}},"/api/v1/workspace/history":{"get":{"description":"List workspace commit history.","operationId":"workspace_history_api_v1_workspace_history_get","parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":20,"maximum":100,"minimum":1,"title":"Limit","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Workspace History","tags":["grep-public-api"]}},"/api/v1/workspace/tree":{"get":{"description":"List workspace directory tree grouped by section (projects/jobs/experts/apps).\n\nReturns: { \"sections\": { \"projects\": [\"acme\", \"docs\"], \"jobs\": [...], ... } }","operationId":"workspace_tree_api_v1_workspace_tree_get","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"title":"Response Workspace Tree Api V1 Workspace Tree Get","type":"object"}}},"description":"Successful Response"}},"summary":"Workspace Tree","tags":["grep-public-api"]}}}}