{"components":{"schemas":{"AgentStage":{"additionalProperties":false,"description":"Work that needs judgment: find, assess, inspect, rank, write.","properties":{"agent":{"anyOf":[{"$ref":"#/components/schemas/StageAgent"},{"type":"null"}],"description":"Run this stage's workers as an agent. Omit to run as the campaign's own agent, if it has one."},"approach":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Research approach for every worker.","title":"Approach"},"concurrency":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many of the stage's workers run at once: clamped to 1-20, default 5.","title":"Concurrency"},"depends_on":{"description":"Stages whose accepted records this one reads. Empty for a stage that starts the campaign.","items":{"pattern":"^[a-z][a-z0-9_-]{0,63}$","type":"string"},"maxItems":31,"title":"Depends On","type":"array"},"effort":{"anyOf":[{"enum":["build","high","low","medium"],"type":"string"},{"type":"null"}],"description":"Effort for every worker.","title":"Effort"},"entity_key_field":{"anyOf":[{"maxLength":256,"minLength":1,"type":"string"},{"type":"null"}],"description":"The field naming each record identity, such as merchant_id. Omit it on per-entity work and each record is identified by its position in the list, so repeated rows are all kept.","title":"Entity Key Field"},"fanout":{"default":"root","description":"per_entity: one worker per record (the first stage of a campaign over supplied records, and every enrichment stage). aggregate: one worker sees every record, for synthesis. root: a discovery stage that starts from nothing and returns records.","enum":["per_entity","aggregate","root"],"title":"Fanout","type":"string"},"instruction":{"anyOf":[{"maxLength":8000,"minLength":1,"type":"string"},{"type":"null"}],"description":"What each worker is asked to do. The record it applies to is appended by the host. Required unless question_field or agent.inputs supplies each worker's assignment.","title":"Instruction"},"key":{"description":"Short identifier other stages refer to, such as inspect_processor.","pattern":"^[a-z][a-z0-9_-]{0,63}$","title":"Key","type":"string"},"max_credits":{"anyOf":[{"minimum":1.0,"type":"integer"},{"type":"null"}],"description":"Credit budget for the stage. No worker starts that the remaining budget cannot cover; when it is spent the stage pauses.","title":"Max Credits"},"op":{"const":"agent","title":"Op","type":"string"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"JSON Schema of what one worker returns: only the fields it researches. Never the record's identity or the fields it was given — the host reattaches those. Omit it and each record keeps the report its worker wrote instead.","title":"Output Schema"},"question_field":{"anyOf":[{"maxLength":256,"minLength":1,"type":"string"},{"type":"null"}],"description":"The record field holding the question this record's worker is asked, used as written. It follows the instruction when there is one, and the record itself is not appended. Only for fanout 'per_entity'.","title":"Question Field"},"records_field":{"anyOf":[{"maxLength":256,"minLength":1,"type":"string"},{"type":"null"}],"description":"On a discovery stage: the output field that holds the list of records found.","title":"Records Field"},"response_language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language every worker answers in, as an ISO 639-1 code such as en or es-MX.","title":"Response Language"},"title":{"description":"What the customer sees this stage called.","maxLength":200,"minLength":1,"title":"Title","type":"string"}},"required":["key","title","op"],"title":"AgentStage","type":"object"},"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"},"ApproveCampaignRequest":{"properties":{"review_digest":{"pattern":"^[a-f0-9]{64}$","title":"Review Digest","type":"string"}},"required":["review_digest"],"title":"ApproveCampaignRequest","type":"object"},"ArtifactInfo":{"properties":{"byte_size":{"title":"Byte Size","type":"integer"},"deliverable_key":{"title":"Deliverable Key","type":"string"},"filename":{"title":"Filename","type":"string"},"media_type":{"title":"Media Type","type":"string"},"sha256":{"title":"Sha256","type":"string"}},"required":["deliverable_key","filename","media_type","byte_size","sha256"],"title":"ArtifactInfo","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"},"AttachmentUploadBegin":{"additionalProperties":false,"description":"Request body for ``POST /attachments/uploads``.","properties":{"content_type":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"title":"Content Type"},"filename":{"description":"Name the file keeps in ``./input_files/``; its extension decides acceptance.","maxLength":255,"minLength":1,"title":"Filename","type":"string"},"size_bytes":{"description":"Exact byte length of the file. The PUT body must match it.","minimum":1.0,"title":"Size Bytes","type":"integer"}},"required":["filename","size_bytes"],"title":"AttachmentUploadBegin","type":"object"},"AttachmentUploadBeginResponse":{"description":"Response from ``POST /attachments/uploads``: where and how to PUT the bytes.","properties":{"attachment_id":{"format":"uuid","title":"Attachment Id","type":"string"},"curl":{"description":"A ready-to-run upload command for the local file.","title":"Curl","type":"string"},"expires_at":{"description":"The reservation and its token expire together.","title":"Expires At","type":"string"},"max_bytes":{"title":"Max Bytes","type":"integer"},"status":{"description":"``pending_upload`` until the bytes land.","title":"Status","type":"string"},"upload_token":{"description":"One-time token bound to this attachment; send it in ``upload_token_header``.","title":"Upload Token","type":"string"},"upload_token_header":{"title":"Upload Token Header","type":"string"},"upload_url":{"description":"PUT the raw file body here.","title":"Upload Url","type":"string"}},"required":["attachment_id","status","upload_url","upload_token","upload_token_header","max_bytes","expires_at","curl"],"title":"AttachmentUploadBeginResponse","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"},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"schedule":{"anyOf":[{"$ref":"#/components/schemas/BatchScheduleSummary"},{"type":"null"}]},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id"},"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"},"BatchScheduleDetail":{"properties":{"runs":{"items":{"$ref":"#/components/schemas/ResearchBatchRunSummary"},"title":"Runs","type":"array"},"schedule":{"$ref":"#/components/schemas/BatchScheduleSummary"}},"required":["schedule","runs"],"title":"BatchScheduleDetail","type":"object"},"BatchScheduleInput":{"additionalProperties":false,"description":"Cadence for a recurring batch — the same shape loops use, minus sub-daily.","properties":{"frequency":{"description":"daily | weekly | monthly","title":"Frequency","type":"string"},"schedule_config":{"additionalProperties":true,"description":"{hour, minute} plus day_of_week (weekly, 0=Monday or a name) or day_of_month (monthly, 1-28)","title":"Schedule Config","type":"object"},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"IANA timezone; defaults to UTC","title":"Timezone"}},"required":["frequency"],"title":"BatchScheduleInput","type":"object"},"BatchScheduleSummary":{"properties":{"consecutive_failures":{"title":"Consecutive Failures","type":"integer"},"deleted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deleted At"},"frequency":{"title":"Frequency","type":"string"},"is_active":{"title":"Is Active","type":"boolean"},"last_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Run At"},"last_skip_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Skip Reason"},"last_skipped_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Skipped At"},"latest_batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Batch Id"},"name":{"title":"Name","type":"string"},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Run At"},"run_count":{"title":"Run Count","type":"integer"},"schedule_config":{"additionalProperties":true,"title":"Schedule Config","type":"object"},"schedule_id":{"title":"Schedule Id","type":"string"},"timezone":{"title":"Timezone","type":"string"}},"required":["schedule_id","name","frequency","schedule_config","timezone","is_active","run_count","consecutive_failures"],"title":"BatchScheduleSummary","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 run 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 attachment.","items":{"contentMediaType":"application/octet-stream","type":"string"},"title":"Files","type":"array"}},"required":["files"],"title":"Body_create_research_attachment_v2","type":"object"},"Body_upload_agent_context_file_v2":{"properties":{"file":{"contentMediaType":"application/octet-stream","title":"File","type":"string"}},"required":["file"],"title":"Body_upload_agent_context_file_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"},"BrowserGeolocation":{"description":"Where a proxied session egresses from: an ISO 3166-1 alpha-2 country, optionally a US state and a city.","properties":{"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"country":{"maxLength":2,"minLength":2,"title":"Country","type":"string"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},"required":["country"],"title":"BrowserGeolocation","type":"object"},"BrowserSessionPage":{"description":"One tab of a session, with its own live-view URL while the session runs.","properties":{"live_view_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Fullscreen live-view URL for this tab","title":"Live View Url"},"page_id":{"description":"Browserbase page id","title":"Page Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The page's title","title":"Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The page's current URL","title":"Url"}},"required":["page_id"],"title":"BrowserSessionPage","type":"object"},"BrowserSessionVideo":{"description":"The archived recording of a session, one MP4 per tab.","properties":{"error":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why the recording could not be archived","title":"Error"},"pages":{"items":{"$ref":"#/components/schemas/BrowserSessionVideoPage"},"title":"Pages","type":"array"},"state":{"default":"pending","enum":["pending","ready","failed","unavailable"],"title":"State","type":"string"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The first tab's MP4 URL, for single-tab sessions","title":"Url"}},"title":"BrowserSessionVideo","type":"object"},"BrowserSessionVideoPage":{"description":"One tab's archived MP4.","properties":{"end_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Offset of this tab's last frame from session start","title":"End Ms"},"page_id":{"description":"Browserbase page id","title":"Page Id","type":"string"},"start_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Offset of this tab's first frame from session start","title":"Start Ms"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Short-lived URL to the archived MP4","title":"Url"}},"required":["page_id"],"title":"BrowserSessionVideoPage","type":"object"},"CampaignAttention":{"description":"Why a campaign needs a person, and what to do about it.","properties":{"message":{"title":"Message","type":"string"},"next_action":{"enum":["retry","add_credits","cancel"],"title":"Next Action","type":"string"},"reason":{"enum":["stage_failed","quota_exhausted","budget_exhausted","key_unusable"],"title":"Reason","type":"string"},"stage_key":{"title":"Stage Key","type":"string"}},"required":["reason","stage_key","message","next_action"],"title":"CampaignAttention","type":"object"},"CampaignBrowserAgent":{"description":"The agent a stage's batch ran as, as the batch recorded it.","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The agent's id; null for the default researcher","title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The agent's name as the batch recorded it","title":"Name"}},"required":["id","name"],"title":"CampaignBrowserAgent","type":"object"},"CampaignBrowserSession":{"description":"One browser session of a campaign job, with the work it belongs to.","properties":{"active_page_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The tab the browser is on, when the harness knows it","title":"Active Page Id"},"agent":{"$ref":"#/components/schemas/CampaignBrowserAgent"},"connection":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The saved website connection's name","title":"Connection"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO timestamp the harness recorded at launch","title":"Created At"},"ended_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ended At"},"entity_key":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The key of the record the job worked on","title":"Entity Key"},"geolocation":{"anyOf":[{"$ref":"#/components/schemas/BrowserGeolocation"},{"type":"null"}],"description":"Where the proxy egresses from, when the session asked for a place"},"harness":{"anyOf":[{"enum":["claude_agents","agentrun"],"type":"string"},{"type":"null"}],"title":"Harness"},"job_id":{"title":"Job Id","type":"string"},"job_status":{"description":"The job's status","title":"Job Status","type":"string"},"last_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The last page the harness read","title":"Last Url"},"live_view_framed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Live-view URL with browser chrome","title":"Live View Framed Url"},"live_view_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Fullscreen live-view URL; only while RUNNING","title":"Live View Url"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The browser's name when the run drove several side by side; None for the default","title":"Name"},"node":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The harness node that owned the session","title":"Node"},"pages":{"items":{"$ref":"#/components/schemas/BrowserSessionPage"},"title":"Pages","type":"array"},"provider":{"anyOf":[{"enum":["browserbase","kernel"],"type":"string"},{"type":"null"}],"description":"The browser provider behind a saved website connection; None means Browserbase","title":"Provider"},"proxies":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Proxies"},"proxy_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Proxy Bytes"},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The part the stage's agent plays in the campaign","title":"Role"},"session_id":{"description":"Browserbase session id","title":"Session Id","type":"string"},"stage_key":{"title":"Stage Key","type":"string"},"stage_title":{"title":"Stage Title","type":"string"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"state":{"description":"live while the job runs and the browser is not released","enum":["live","ended"],"title":"State","type":"string"},"status":{"anyOf":[{"enum":["RUNNING","COMPLETED","ERROR","TIMED_OUT"],"type":"string"},{"type":"null"}],"title":"Status"},"stopped":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"The harness confirmed the release","title":"Stopped"},"verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Verified"},"video":{"anyOf":[{"$ref":"#/components/schemas/BrowserSessionVideo"},{"type":"null"}]}},"required":["session_id","harness","node","name","provider","connection","live_view_url","live_view_framed_url","pages","active_page_id","proxies","geolocation","verified","created_at","status","started_at","ended_at","stopped","last_url","region","proxy_bytes","video","job_id","job_status","state","stage_key","stage_title","entity_key","role","agent"],"title":"CampaignBrowserSession","type":"object"},"CampaignBrowserSessionCounts":{"properties":{"ended":{"default":0,"title":"Ended","type":"integer"},"live":{"default":0,"title":"Live","type":"integer"}},"required":["live","ended"],"title":"CampaignBrowserSessionCounts","type":"object"},"CampaignBrowserSessions":{"description":"``GET /api/v2/campaigns/{campaign_id}/browser-sessions``: newest first, one page at a time.","properties":{"campaign_id":{"title":"Campaign Id","type":"string"},"campaign_status":{"enum":["draft","approved","running","needs_attention","completed","cancelled"],"title":"Campaign Status","type":"string"},"counts":{"$ref":"#/components/schemas/CampaignBrowserSessionCounts","description":"Sessions in the stage filter's scope, before the status filter and the cursor"},"has_more":{"default":false,"title":"Has More","type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/CampaignBrowserSession"},"title":"Items","type":"array"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"required":["campaign_id","campaign_status","counts","items","next_cursor","has_more"],"title":"CampaignBrowserSessions","type":"object"},"CampaignDetail":{"description":"A campaign read back: the plan, each stage's state and progress, and the files produced.","properties":{"approved_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Approved At"},"artifacts":{"items":{"$ref":"#/components/schemas/ArtifactInfo"},"title":"Artifacts","type":"array"},"attention":{"anyOf":[{"$ref":"#/components/schemas/CampaignAttention"},{"type":"null"}]},"campaign_id":{"title":"Campaign Id","type":"string"},"capabilities":{"items":{"type":"string"},"title":"Capabilities","type":"array"},"deliverable_files":{"items":{"$ref":"#/components/schemas/DeliverableFile"},"title":"Deliverable Files","type":"array"},"deliverables":{"items":{"additionalProperties":true,"type":"object"},"title":"Deliverables","type":"array"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Id"},"expert_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Name"},"finished_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Finished At"},"name":{"title":"Name","type":"string"},"next_step":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What happens next without the caller doing anything. Present on create.","title":"Next Step"},"objective":{"title":"Objective","type":"string"},"owner_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner User Id"},"plan":{"anyOf":[{"$ref":"#/components/schemas/Plan"},{"type":"null"}],"description":"The plan the campaign runs, exactly as validated and stored. Present on create, on update and on the campaign read, whatever the campaign's status; absent in lists and in the summaries of approve, cancel and retry. Send it back unchanged, or with one stage changed, to edit a draft."},"records":{"anyOf":[{"$ref":"#/components/schemas/RecordsReport"},{"type":"null"}]},"review_digest":{"description":"Approve this exact digest to start the campaign.","title":"Review Digest","type":"string"},"revision":{"title":"Revision","type":"integer"},"stages":{"items":{"$ref":"#/components/schemas/StageDetail"},"title":"Stages","type":"array"},"started_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Started At"},"status":{"enum":["draft","approved","running","needs_attention","completed","cancelled"],"title":"Status","type":"string"},"status_changed_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Status Changed At"},"workforce":{"anyOf":[{"$ref":"#/components/schemas/CampaignWorkforce"},{"type":"null"}],"description":"The agents doing the campaign's work, one per agent stage. Present on create and read."}},"required":["campaign_id","name","status","revision","objective","review_digest"],"title":"CampaignDetail","type":"object"},"CampaignLimits":{"properties":{"max_assignment_chars":{"title":"Max Assignment Chars","type":"integer"},"max_records_per_stage":{"title":"Max Records Per Stage","type":"integer"},"max_supplied_records":{"title":"Max Supplied Records","type":"integer"}},"required":["max_records_per_stage","max_supplied_records","max_assignment_chars"],"title":"CampaignLimits","type":"object"},"CampaignPortfolio":{"description":"A stage's records, described well enough to render without knowing them.\n\n``output_schema`` is what the plan declared and ``fields`` is how it wants\nto be shown, so a table builds its columns from the contract rather than\nfrom whichever keys the first row happened to have. Everything here is\ngeneric: a campaign about merchants and one about hiring produce the same\nshape.","properties":{"campaign_id":{"title":"Campaign Id","type":"string"},"coverage":{"$ref":"#/components/schemas/PortfolioCoverage"},"entity_key_field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Key Field"},"fields":{"items":{"$ref":"#/components/schemas/FieldView"},"title":"Fields","type":"array"},"items":{"items":{"$ref":"#/components/schemas/PortfolioItem"},"title":"Items","type":"array"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema"},"revision":{"title":"Revision","type":"integer"},"stage_key":{"title":"Stage Key","type":"string"},"status":{"title":"Status","type":"string"}},"required":["campaign_id","revision","status","stage_key","fields","coverage","items"],"title":"CampaignPortfolio","type":"object"},"CampaignSummary":{"properties":{"campaign_id":{"title":"Campaign Id","type":"string"},"capabilities":{"items":{"type":"string"},"title":"Capabilities","type":"array"},"deliverables":{"items":{"additionalProperties":true,"type":"object"},"title":"Deliverables","type":"array"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Id"},"expert_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Name"},"name":{"title":"Name","type":"string"},"next_step":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What happens next without the caller doing anything. Present on create.","title":"Next Step"},"objective":{"title":"Objective","type":"string"},"plan":{"anyOf":[{"$ref":"#/components/schemas/Plan"},{"type":"null"}],"description":"The plan the campaign runs, exactly as validated and stored. Present on create, on update and on the campaign read, whatever the campaign's status; absent in lists and in the summaries of approve, cancel and retry. Send it back unchanged, or with one stage changed, to edit a draft."},"records":{"anyOf":[{"$ref":"#/components/schemas/RecordsReport"},{"type":"null"}]},"review_digest":{"description":"Approve this exact digest to start the campaign.","title":"Review Digest","type":"string"},"revision":{"title":"Revision","type":"integer"},"stages":{"items":{"additionalProperties":true,"type":"object"},"title":"Stages","type":"array"},"status":{"enum":["draft","approved","running","needs_attention","completed","cancelled"],"title":"Status","type":"string"},"workforce":{"anyOf":[{"$ref":"#/components/schemas/CampaignWorkforce"},{"type":"null"}],"description":"The agents doing the campaign's work, one per agent stage. Present on create and read."}},"required":["campaign_id","name","status","revision","objective","review_digest"],"title":"CampaignSummary","type":"object"},"CampaignWorkforce":{"description":"The agents doing a campaign's work, one member per agent stage, in plan order.","properties":{"members":{"items":{"$ref":"#/components/schemas/WorkforceMember"},"title":"Members","type":"array"},"totals":{"$ref":"#/components/schemas/WorkforceTotals"}},"required":["totals"],"title":"CampaignWorkforce","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 attachment.","properties":{"attachment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Copy a file from this 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 agent (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 agent.","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 agent 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 agent 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 agent 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 agent 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"},"CreateCampaignRequest":{"additionalProperties":false,"description":"A campaign plan, or the rows and settings of a one-stage campaign in its place.\n\nThe one-stage fields expand into a plan with one agent stage and a CSV file\nof its results; send either ``plan`` or those fields, not both. A field the\nrequest does not have is refused, never ignored: a setting dropped in\nsilence would start a campaign that runs, and costs, other than was asked.","properties":{"agent":{"anyOf":[{"$ref":"#/components/schemas/StageAgent"},{"type":"null"}],"description":"Run every row as this agent, and how each record fills its form."},"approach":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Research approach for every row.","title":"Approach"},"concurrency":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How many rows run at once.","title":"Concurrency"},"effort":{"anyOf":[{"enum":["build","high","low","medium"],"type":"string"},{"type":"null"}],"description":"Effort for every row.","title":"Effort"},"instruction":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What each row's worker is asked to do. With questions or question_field, each row's question follows it; with records alone, the record is appended to it.","title":"Instruction"},"max_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Credit budget for the campaign's rows. When it is spent the campaign pauses.","title":"Max Credits"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A short title for the campaign. Omit for a default one.","title":"Name"},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"JSON Schema of what each row returns; each field becomes a column of the results file. Omit it and each row keeps the report its worker wrote.","title":"Output Schema"},"plan":{"anyOf":[{"$ref":"#/components/schemas/Plan"},{"type":"null"}],"description":"The campaign plan: its stages, and the deliverables they produce. Omit it to describe a one-stage campaign with the fields of this request instead."},"question_field":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The field of each record holding that row's question, used as written.","title":"Question Field"},"questions":{"anyOf":[{"items":{"type":"string"},"maxItems":100000,"type":"array"},{"type":"null"}],"description":"One question per row, asked trimmed; a blank one is left out and counted in the records report, as a batch leaves it out. Send this or records, not both.","title":"Questions"},"records":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"maxItems":100000,"type":"array"},{"type":"null"}],"description":"Records the first stage runs over, each an object carrying the stage's key field.","title":"Records"},"response_language":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Language every row answers in, as an ISO 639-1 code such as en or es-MX.","title":"Response Language"},"start":{"default":false,"description":"Approve the campaign in the same call, so it starts without a separate approve. A call replayed with the same Idempotency-Key returns the campaign that key created as it stands now, which may already be running: the campaign checks are not run on the replayed body, and it starts nothing. A body that is not a well-formed request is refused before the key is read.","title":"Start","type":"boolean"}},"title":"CreateCampaignRequest","type":"object"},"CreateExpertV2Request":{"description":"Direct agent 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 agent","title":"Allow Free Tier Use","type":"boolean"},"campaign_plan":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Campaign plan template with {{field_label}} input placeholders. Validated on save; null clears on update.","title":"Campaign Plan"},"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/agents/{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 agent runs with by default","title":"Default Model"},"default_runtime":{"anyOf":[{"enum":["claude_agents","agentrun"],"type":"string"},{"type":"null"}],"description":"Sandbox harness the agent 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":"Supported kebab-case Lucide icon name","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 agent 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 agent. 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 agent","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 agent 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/agents/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 agent 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/agents/generate-workflow`. The agentrun runtime runs it verbatim; omit to let the harness author a workflow per run.","title":"Pinned Workflow"},"registry_expert_id":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"description":"The registry agent this agent runs as (a premium agent); its copies run the same agent.","title":"Registry Expert Id"},"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"},"run_mode":{"anyOf":[{"enum":["job","campaign"],"type":"string"},{"type":"null"}],"description":"Run a single job or render the agent's campaign template.","title":"Run Mode"},"skill_names":{"description":"Skill names to link to the agent","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"},"tags":{"description":"Shared labels used to organize this agent","items":{"maxLength":50,"minLength":1,"type":"string"},"maxItems":20,"title":"Tags","type":"array"}},"required":["name","system_prompt"],"title":"CreateExpertV2Request","type":"object"},"CreateLoopRequest":{"additionalProperties":false,"description":"Create a recurring batch and immediately start its first occurrence.","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"},"custom_json_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Optional JSON Schema every row's structured output must satisfy. The same contract the single-job research path accepts; rows that cannot satisfy it fail rather than returning a differently shaped result.","title":"Custom Json Schema"},"effort":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Effort applied to every row: low|medium|high|build. When omitted, uses the agent's default effort, or medium if none is configured.","title":"Effort"},"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"},"inputs":{"anyOf":[{"items":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}]},"type":"array"},{"type":"null"}],"description":"Optional agent input-form submission per row ({field label: value}), positionally aligned with `questions`. Requires `expert_id`. Each row's question is composed from its question text (may be blank) plus these inputs, exactly as a chat run of the agent's form composes it. Length must match `questions` when provided.","title":"Inputs"},"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-1000, 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"},"schedule":{"$ref":"#/components/schemas/BatchScheduleInput","description":"Required recurring schedule."}},"required":["batch_name","questions","schedule"],"title":"CreateLoopRequest","type":"object"},"CreateResearchBatchInput":{"additionalProperties":false,"description":"Create a batch from a list of questions (one run 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"},"custom_json_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Optional JSON Schema every row's structured output must satisfy. The same contract the single-job research path accepts; rows that cannot satisfy it fail rather than returning a differently shaped result.","title":"Custom Json Schema"},"effort":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Effort applied to every row: low|medium|high|build. When omitted, uses the agent's default effort, or medium if none is configured.","title":"Effort"},"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"},"inputs":{"anyOf":[{"items":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}]},"type":"array"},{"type":"null"}],"description":"Optional agent input-form submission per row ({field label: value}), positionally aligned with `questions`. Requires `expert_id`. Each row's question is composed from its question text (may be blank) plus these inputs, exactly as a chat run of the agent's form composes it. Length must match `questions` when provided.","title":"Inputs"},"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-1000, 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"},"schedule":{"anyOf":[{"$ref":"#/components/schemas/BatchScheduleInput"},{"type":"null"}],"description":"Make this batch recurring. Run #1 starts now; the batch then re-runs on the cadence, each row's new job seeing the same row's previous job as a read-only reference."}},"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"},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id"},"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_CampaignSummary_":{"properties":{"has_more":{"default":false,"title":"Has More","type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/CampaignSummary"},"title":"Items","type":"array"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"required":["items"],"title":"CursorPage[CampaignSummary]","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"},"tags":{"items":{"type":"string"},"title":"Tags","type":"array"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"required":["id","name"],"title":"CustomExpertSummary","type":"object"},"CustomExpertsPage":{"description":"The custom-experts listing, or one page of it when ``limit`` or ``cursor`` is given.\n\nThe paging fields are present only on a paged response, so a call without them keeps its shape.","properties":{"count":{"default":0,"title":"Count","type":"integer"},"experts":{"items":{"$ref":"#/components/schemas/CustomExpertSummary"},"title":"Experts","type":"array"},"has_more":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether another page follows (paged responses only).","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as cursor for the next page (paged responses only; absent on the last page).","title":"Next Cursor"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Rows across all pages (paged responses only).","title":"Total"}},"title":"CustomExpertsPage","type":"object"},"Deliverable":{"additionalProperties":false,"description":"One named thing the customer asked for.","properties":{"columns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Columns"},"description":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"title":"Description"},"entity_key_field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Key Field"},"from_stage":{"description":"The stage that produces it: an export stage for a dataset, an aggregate agent stage for a document.","maxLength":64,"minLength":1,"title":"From Stage","type":"string"},"key":{"maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_-]*$","title":"Key","type":"string"},"kind":{"enum":["dataset","document"],"title":"Kind","type":"string"},"records_field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Records Field"},"title":{"maxLength":200,"minLength":1,"title":"Title","type":"string"}},"required":["key","title","kind","from_stage"],"title":"Deliverable","type":"object"},"DeliverableFile":{"description":"Whether one deliverable's file can be downloaded, and why not when it cannot.","properties":{"deliverable_key":{"title":"Deliverable Key","type":"string"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Why an unavailable deliverable has no file.","title":"Reason"},"state":{"enum":["ready","pending","unavailable"],"title":"State","type":"string"}},"required":["deliverable_key","state"],"title":"DeliverableFile","type":"object"},"ExcludedRecord":{"properties":{"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"key":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The record's identity, when it had one.","title":"Key"},"reason":{"description":"Why the record was left out, e.g. missing_identity or duplicate_identity.","title":"Reason","type":"string"}},"required":["reason"],"title":"ExcludedRecord","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 agent"}},"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 agent (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 agent 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 agent build.","properties":{"job_id":{"description":"Build job id — poll GET /agents/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 agent, 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":"Agent lifecycle status — builds register a 'building' draft; activate via PATCH /agents/{id}","title":"Status"}},"title":"ExpertBuildResult","type":"object"},"ExpertBuildStatusResponse":{"description":"Status of an async agent 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 agent is being persisted · succeeded: the agent 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 agent 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"},"campaign_plan":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Campaign Plan"},"can_edit":{"default":false,"title":"Can Edit","type":"boolean"},"cloned_from_expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The agent this one was copied from; null for an original","title":"Cloned From Expert Id"},"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 agents (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"},"registry_expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The registry agent a premium agent runs as; null for any other agent","title":"Registry Expert Id"},"required_tool_calls":{"items":{"type":"string"},"title":"Required Tool Calls","type":"array"},"run_mode":{"default":"job","enum":["job","campaign"],"title":"Run Mode","type":"string"},"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"},"tags":{"items":{"type":"string"},"title":"Tags","type":"array"},"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 agent 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 agent 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 agent'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 agent. 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 agent; 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"}],"description":"Intake form (form.json shape) shown in the editor's Inputs & Outputs step and used for batch CSV column mapping. Omit to leave unchanged; [] means the agent takes no structured input.","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 agent 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 agent'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":"Agent id, passed as ``expert_id`` when starting a run.","title":"Id","type":"string"},"name":{"description":"Display name (e.g., ``Patent & IP``).","title":"Name","type":"string"},"output_types":{"description":"What this agent 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 agent. Agents can pattern-match against the user's request to pick the right agent 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 agent.","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"},"tags":{"items":{"type":"string"},"title":"Tags","type":"array"}},"required":["id","name","slug","description","domain","status"],"title":"ExpertV2Response","type":"object"},"ExpertValidateV2Request":{"description":"Validate an agent config without persisting anything.\n\nPass ``expert_id`` to validate an UPDATE (the checks run against the\nmerged state of that agent); 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 agent","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"},"ExportStage":{"additionalProperties":false,"description":"Write the accepted records to a file the customer downloads.","properties":{"columns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Column order for the file. Omit to export every field the records carry.","title":"Columns"},"depends_on":{"description":"The stages this one operates on.","items":{"pattern":"^[a-z][a-z0-9_-]{0,63}$","type":"string"},"maxItems":31,"minItems":1,"title":"Depends On","type":"array"},"entity_key_field":{"description":"The field naming each record identity in the export.","maxLength":256,"minLength":1,"title":"Entity Key Field","type":"string"},"filename":{"description":"The filename the customer downloads: .csv for a CSV file, .xlsx for an Excel workbook.","maxLength":200,"minLength":5,"pattern":"\\.([cC][sSſ][vV]|[xX][lL][sSſ][xX])$","title":"Filename","type":"string"},"key":{"description":"Short identifier other stages refer to, such as inspect_processor.","pattern":"^[a-z][a-z0-9_-]{0,63}$","title":"Key","type":"string"},"op":{"const":"export","title":"Op","type":"string"},"requested":{"anyOf":[{"minimum":0.0,"type":"integer"},{"type":"null"}],"description":"How many records the customer asked for, when they named a number. Omit otherwise.","title":"Requested"},"title":{"description":"What the customer sees this stage called.","maxLength":200,"minLength":1,"title":"Title","type":"string"}},"required":["key","title","depends_on","op","filename","entity_key_field"],"title":"ExportStage","type":"object"},"FieldView":{"description":"One field, described well enough to render without knowing its meaning.","properties":{"hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hint"},"label":{"title":"Label","type":"string"},"name":{"title":"Name","type":"string"},"order":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Order"},"type":{"default":"string","title":"Type","type":"string"}},"required":["name","label"],"title":"FieldView","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"JoinStage":{"additionalProperties":false,"description":"Attach findings to the records they belong to; where branches converge.","properties":{"depends_on":{"description":"The stages this one operates on.","items":{"pattern":"^[a-z][a-z0-9_-]{0,63}$","type":"string"},"maxItems":31,"minItems":1,"title":"Depends On","type":"array"},"key":{"description":"Short identifier other stages refer to, such as inspect_processor.","pattern":"^[a-z][a-z0-9_-]{0,63}$","title":"Key","type":"string"},"op":{"const":"join","title":"Op","type":"string"},"title":{"description":"What the customer sees this stage called.","maxLength":200,"minLength":1,"title":"Title","type":"string"}},"required":["key","title","depends_on","op"],"title":"JoinStage","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 an 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 agent can be granted.","properties":{"always_on":{"default":false,"description":"Every run carries this tool regardless of agent 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"},"MetricsStage":{"additionalProperties":false,"description":"Count what was produced, excluded and fallen short.","properties":{"depends_on":{"description":"The stages this one operates on.","items":{"pattern":"^[a-z][a-z0-9_-]{0,63}$","type":"string"},"maxItems":31,"minItems":1,"title":"Depends On","type":"array"},"key":{"description":"Short identifier other stages refer to, such as inspect_processor.","pattern":"^[a-z][a-z0-9_-]{0,63}$","title":"Key","type":"string"},"op":{"const":"metrics","title":"Op","type":"string"},"requested":{"anyOf":[{"minimum":0.0,"type":"integer"},{"type":"null"}],"description":"How many records the customer asked for, when they named a number. The host reports it beside what was actually accepted, and the shortfall between them. Omit otherwise.","title":"Requested"},"title":{"description":"What the customer sees this stage called.","maxLength":200,"minLength":1,"title":"Title","type":"string"}},"required":["key","title","depends_on","op"],"title":"MetricsStage","type":"object"},"Plan":{"additionalProperties":false,"description":"A complete campaign: its objective, its stages, and what it delivers.","properties":{"deliverables":{"description":"Every artifact the customer asked for, and the stage producing it.","items":{"$ref":"#/components/schemas/Deliverable"},"maxItems":16,"minItems":1,"title":"Deliverables","type":"array"},"name":{"description":"A short title the customer sees in lists and on the campaign page.","maxLength":80,"minLength":1,"title":"Name","type":"string"},"objective":{"description":"What the customer asked for, in full.","maxLength":8000,"minLength":1,"title":"Objective","type":"string"},"stages":{"items":{"discriminator":{"mapping":{"agent":"#/components/schemas/AgentStage","export":"#/components/schemas/ExportStage","join":"#/components/schemas/JoinStage","metrics":"#/components/schemas/MetricsStage"},"propertyName":"op"},"oneOf":[{"$ref":"#/components/schemas/AgentStage"},{"$ref":"#/components/schemas/JoinStage"},{"$ref":"#/components/schemas/ExportStage"},{"$ref":"#/components/schemas/MetricsStage"}]},"maxItems":32,"minItems":1,"title":"Stages","type":"array"}},"required":["name","objective","stages","deliverables"],"title":"Plan","type":"object"},"PlanDiagnostic":{"description":"One reason a draft is not yet a plan.","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"message":{"title":"Message","type":"string"},"path":{"description":"Where the problem is, e.g. 'stages.2.instruction'","title":"Path","type":"string"}},"required":["path","message"],"title":"PlanDiagnostic","type":"object"},"PortfolioCoverage":{"description":"How much of a stage's work has landed.","properties":{"accepted":{"title":"Accepted","type":"integer"},"entity_count":{"title":"Entity Count","type":"integer"},"excluded_count":{"title":"Excluded Count","type":"integer"},"failed":{"title":"Failed","type":"integer"},"pending":{"title":"Pending","type":"integer"},"scope_complete":{"title":"Scope Complete","type":"boolean"}},"required":["entity_count","accepted","pending","failed","excluded_count","scope_complete"],"title":"PortfolioCoverage","type":"object"},"PortfolioItem":{"description":"One record at one stage, with what the customer can open from it.","properties":{"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch Id"},"completed_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Completed At"},"content":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Content"},"entity_key":{"title":"Entity Key","type":"string"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id"},"job_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Status"},"latest_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Status"},"rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rejection Reason"},"report_link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Report Link"},"result_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Id"},"retry_eligible":{"default":false,"title":"Retry Eligible","type":"boolean"},"row_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Row Number"},"stage_key":{"title":"Stage Key","type":"string"},"started_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Started At"},"status":{"enum":["accepted","pending","failed","excluded"],"title":"Status","type":"string"}},"required":["entity_key","stage_key","status"],"title":"PortfolioItem","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 /runs`` 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"},"RecordsReport":{"description":"What happened to the supplied records before any work started.","properties":{"accepted":{"title":"Accepted","type":"integer"},"excluded":{"title":"Excluded","type":"integer"},"excluded_by_reason":{"additionalProperties":{"type":"integer"},"title":"Excluded By Reason","type":"object"},"sample_excluded":{"description":"The first few excluded records.","items":{"$ref":"#/components/schemas/ExcludedRecord"},"title":"Sample Excluded","type":"array"},"supplied":{"title":"Supplied","type":"integer"}},"required":["supplied","accepted","excluded"],"title":"RecordsReport","type":"object"},"ResearchAppArtifact":{"description":"Deployed app produced by a build-mode run.","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"},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"runs":{"items":{"$ref":"#/components/schemas/ResearchBatchRunSummary"},"title":"Runs","type":"array"},"schedule":{"anyOf":[{"$ref":"#/components/schemas/BatchScheduleSummary"},{"type":"null"}]},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id"},"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"},"entity_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Key"},"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"},"prior_job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prior Job Id"},"prior_job_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prior Job Slug"},"prior_run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prior Run Number"},"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"},"ResearchBatchRunSummary":{"properties":{"batch_id":{"title":"Batch Id","type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"has_active_rows":{"default":false,"title":"Has Active Rows","type":"boolean"},"processed_rows":{"title":"Processed Rows","type":"integer"},"processing_status":{"title":"Processing Status","type":"string"},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"total_rows":{"title":"Total Rows","type":"integer"}},"required":["batch_id","processing_status","processed_rows","total_rows"],"title":"ResearchBatchRunSummary","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"},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"schedule":{"anyOf":[{"$ref":"#/components/schemas/BatchScheduleSummary"},{"type":"null"}]},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id"},"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 /runs/{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 run.","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 run 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 /runs/{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 run'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 /runs/{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 run.","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. When omitted, uses the agent default depth, or low if none is configured. ``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 agent. Accepts: (a) a built-in registry id (e.g. ``individual-aml-compliance-expert``); (b) a custom agent UUID you own (or have been granted access to via agent sharing); (c) a custom agent slug. When omitted, an agent 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 agent, you can dispatch against it.","title":"Expert Id"},"harness_sha":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Vendored agentrun 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 run 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 agentrun 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/runs/{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 /runs``).","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 agent ID, if the caller specified one. Empty when the agent 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/runs`` — 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/runs/{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 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"},"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 /runs/{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/runs/{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/runs/{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"},"RetryCampaignResponse":{"description":"A campaign after a retry, with what the retry reached and what it could not.","properties":{"campaign_id":{"title":"Campaign Id","type":"string"},"capabilities":{"items":{"type":"string"},"title":"Capabilities","type":"array"},"deliverables":{"items":{"additionalProperties":true,"type":"object"},"title":"Deliverables","type":"array"},"expert_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Id"},"expert_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expert Name"},"name":{"title":"Name","type":"string"},"next_step":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"What happens next without the caller doing anything. Present on create.","title":"Next Step"},"objective":{"title":"Objective","type":"string"},"plan":{"anyOf":[{"$ref":"#/components/schemas/Plan"},{"type":"null"}],"description":"The plan the campaign runs, exactly as validated and stored. Present on create, on update and on the campaign read, whatever the campaign's status; absent in lists and in the summaries of approve, cancel and retry. Send it back unchanged, or with one stage changed, to edit a draft."},"records":{"anyOf":[{"$ref":"#/components/schemas/RecordsReport"},{"type":"null"}]},"refused_stages":{"items":{"$ref":"#/components/schemas/RetryRefusal"},"title":"Refused Stages","type":"array"},"retried_stages":{"items":{"type":"string"},"title":"Retried Stages","type":"array"},"review_digest":{"description":"Approve this exact digest to start the campaign.","title":"Review Digest","type":"string"},"revision":{"title":"Revision","type":"integer"},"stages":{"items":{"additionalProperties":true,"type":"object"},"title":"Stages","type":"array"},"stages_not_topped_up":{"items":{"type":"string"},"title":"Stages Not Topped Up","type":"array"},"status":{"enum":["draft","approved","running","needs_attention","completed","cancelled"],"title":"Status","type":"string"},"workforce":{"anyOf":[{"$ref":"#/components/schemas/CampaignWorkforce"},{"type":"null"}],"description":"The agents doing the campaign's work, one per agent stage. Present on create and read."}},"required":["campaign_id","name","status","revision","objective","review_digest"],"title":"RetryCampaignResponse","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"},"run_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Number"},"schedule":{"anyOf":[{"$ref":"#/components/schemas/BatchScheduleSummary"},{"type":"null"}]},"schedule_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schedule Id"},"total_rows":{"title":"Total Rows","type":"integer"}},"required":["batch_id","batch_name","agent_key","total_rows","processed_rows","processing_status"],"title":"RetryFailedRowsResponse","type":"object"},"RetryRefusal":{"description":"A stage whose batch would not take a retry, and why.","properties":{"message":{"title":"Message","type":"string"},"stage_key":{"title":"Stage Key","type":"string"}},"required":["stage_key","message"],"title":"RetryRefusal","type":"object"},"RunBatchScheduleNowResponse":{"properties":{"batch_id":{"title":"Batch Id","type":"string"},"run_number":{"title":"Run Number","type":"integer"}},"required":["batch_id","run_number"],"title":"RunBatchScheduleNowResponse","type":"object"},"RunExpertCampaignRequest":{"description":"The agent's form, filled. Keys are the form field labels, as a chat run submits them.","properties":{"inputs":{"additionalProperties":true,"title":"Inputs","type":"object"},"records":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"maxItems":100000,"type":"array"},{"type":"null"}],"title":"Records"}},"title":"RunExpertCampaignRequest","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 agent 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"},"StageAgent":{"additionalProperties":false,"description":"The agent a stage's workers run as, and how a record fills that agent's form.","properties":{"id":{"description":"The agent every worker of this stage runs as: a built-in agent id, or the UUID, slug or handle of a custom agent the caller may run.","maxLength":200,"minLength":1,"title":"Id","type":"string"},"inputs":{"anyOf":[{"additionalProperties":{"maxLength":256,"minLength":1,"type":"string"},"propertyNames":{"maxLength":256,"minLength":1},"type":"object"},{"type":"null"}],"description":"How each record fills the agent's input form: form field label to the record field holding its value. A record reaches the agent through its form, so the host does not also append the record to the instruction. Only for fanout 'per_entity'.","title":"Inputs"},"role":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"description":"The part this agent plays in the campaign, in a few words, such as 'First reviewer'. Shown beside the agent wherever the campaign's team is listed.","title":"Role"}},"required":["id"],"title":"StageAgent","type":"object"},"StageDetail":{"additionalProperties":true,"description":"A stage as planned, with where its work stands.\n\nThe plan fields of the stage's op (instruction, fanout, filename and so on)\nare carried alongside the fields below; the plan schema describes them.","properties":{"accepted_rows":{"title":"Accepted Rows","type":"integer"},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch Id"},"batch_ids":{"items":{"type":"string"},"title":"Batch Ids","type":"array"},"changed_since_collected":{"default":false,"title":"Changed Since Collected","type":"boolean"},"depends_on":{"items":{"type":"string"},"title":"Depends On","type":"array"},"display_status":{"title":"Display Status","type":"string"},"failed_rows":{"title":"Failed Rows","type":"integer"},"failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Reason"},"finished_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Finished At"},"key":{"title":"Key","type":"string"},"op":{"title":"Op","type":"string"},"records_after_dispatch":{"default":0,"title":"Records After Dispatch","type":"integer"},"result_summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result Summary"},"started_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"title":"Started At"},"status":{"title":"Status","type":"string"},"title":{"title":"Title","type":"string"},"total_rows":{"title":"Total Rows","type":"integer"}},"required":["key","title","op","status","display_status","total_rows","accepted_rows","failed_rows"],"title":"StageDetail","type":"object"},"TimelineEvent":{"description":"One event in a run's execution timeline.\n\nReturned in DESC order (newest first) by ``GET\n/runs/{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``, ``steering`` (guidance the run's owner sent while it worked). Unknown / internal event kinds are filtered out before the response is built.","title":"Kind","type":"string"},"steering_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"For ``kind=steering``: the steer this event belongs to; every phase of one steer shares it.","title":"Steering Id"},"steering_phase":{"anyOf":[{"enum":["received","delivered","resumed","failed"],"type":"string"},{"type":"null"}],"description":"For ``kind=steering``: where the owner's guidance stands. ``received`` when it arrives; ``delivered`` when the running agent took it without a pause; ``resumed`` when a run paused for it continues with it; ``failed`` when it could not be applied (``summary`` says whether the run is paused or went on unchanged).","title":"Steering Phase"},"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 /runs/{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"},"UpdateBatchScheduleInput":{"additionalProperties":false,"description":"Editable schedule fields. The row template is frozen — new inputs mean a new schedule.","properties":{"frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Frequency"},"name":{"anyOf":[{"maxLength":200,"minLength":1,"type":"string"},{"type":"null"}],"title":"Name"},"schedule_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Schedule Config"},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timezone"}},"title":"UpdateBatchScheduleInput","type":"object"},"UpdateCampaignRequest":{"additionalProperties":false,"description":"A draft's new plan, and optionally new records, against the digest of the draft as it was read.","properties":{"plan":{"$ref":"#/components/schemas/Plan","description":"The new plan. It replaces the draft's plan whole and is checked as creating a campaign is."},"records":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"maxItems":100000,"type":"array"},{"type":"null"}],"description":"Records that replace the draft's. Omit them to keep the draft's records, checked against the new plan.","title":"Records"},"review_digest":{"description":"The review_digest of the draft as you last read it. A draft changed since then is refused.","pattern":"^[a-f0-9]{64}$","title":"Review Digest","type":"string"}},"required":["review_digest","plan"],"title":"UpdateCampaignRequest","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"},"campaign_plan":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Campaign plan template with {{field_label}} input placeholders. Validated on save; null clears on update.","title":"Campaign Plan"},"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 agent'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 /agents/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"},"registry_expert_id":{"anyOf":[{"maxLength":255,"type":"string"},{"type":"null"}],"description":"The registry agent this agent runs as (a premium agent); its copies run the same agent.","title":"Registry Expert Id"},"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"},"run_mode":{"anyOf":[{"enum":["job","campaign"],"type":"string"},{"type":"null"}],"description":"Run a single job or render the agent's campaign template.","title":"Run Mode"},"skill_names":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Replaces the agent'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"},"tags":{"anyOf":[{"items":{"maxLength":50,"minLength":1,"type":"string"},"maxItems":20,"type":"array"},{"type":"null"}],"description":"Replace the agent's shared labels; an empty list clears them","title":"Tags"}},"title":"UpdateExpertV2Request","type":"object"},"ValidateCampaignResponse":{"description":"What creating this campaign would do, without creating it.","properties":{"diagnostics":{"items":{"$ref":"#/components/schemas/PlanDiagnostic"},"title":"Diagnostics","type":"array"},"limits":{"$ref":"#/components/schemas/CampaignLimits"},"plan":{"anyOf":[{"$ref":"#/components/schemas/Plan"},{"type":"null"}]},"records":{"anyOf":[{"$ref":"#/components/schemas/RecordsReport"},{"type":"null"}]},"review_digest":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Review Digest"},"valid":{"title":"Valid","type":"boolean"},"workforce":{"anyOf":[{"$ref":"#/components/schemas/CampaignWorkforce"},{"type":"null"}],"description":"The agents that would do the campaign's work. Null while the plan is not valid."}},"required":["valid","limits"],"title":"ValidateCampaignResponse","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"},"WorkforceAgent":{"properties":{"catalog_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Catalog Slug"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"icon":{"default":"brain","title":"Icon","type":"string"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The agent's id; null for the default researcher.","title":"Id"},"kind":{"anyOf":[{"enum":["operational","insight"],"type":"string"},{"type":"null"}],"title":"Kind"},"lane":{"anyOf":[{"enum":["personal","work","company"],"type":"string"},{"type":"null"}],"title":"Lane"},"name":{"title":"Name","type":"string"},"premium":{"default":false,"title":"Premium","type":"boolean"},"source":{"enum":["catalog","yours","team","shared","default"],"title":"Source","type":"string"}},"required":["name","source"],"title":"WorkforceAgent","type":"object"},"WorkforceMember":{"properties":{"agent":{"$ref":"#/components/schemas/WorkforceAgent"},"credits_spent":{"default":0,"title":"Credits Spent","type":"integer"},"effort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effort"},"expected_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Credits"},"fanout":{"enum":["per_entity","aggregate","root"],"title":"Fanout","type":"string"},"max_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Credits"},"max_runs":{"description":"planned_runs, or the most a stage can run when that is not yet known.","title":"Max Runs","type":"integer"},"member_key":{"description":"The stage key of the stage this member works.","title":"Member Key","type":"string"},"planned_runs":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Runs this member will make; null until known.","title":"Planned Runs"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role"},"runs":{"$ref":"#/components/schemas/WorkforceRuns"},"stage_key":{"title":"Stage Key","type":"string"},"stage_title":{"title":"Stage Title","type":"string"},"status":{"default":"waiting","enum":["waiting","working","done","stopped"],"title":"Status","type":"string"}},"required":["member_key","stage_key","stage_title","agent","fanout","max_runs"],"title":"WorkforceMember","type":"object"},"WorkforceRuns":{"properties":{"failed":{"default":0,"title":"Failed","type":"integer"},"queued":{"default":0,"title":"Queued","type":"integer"},"running":{"default":0,"title":"Running","type":"integer"},"succeeded":{"default":0,"title":"Succeeded","type":"integer"}},"title":"WorkforceRuns","type":"object"},"WorkforceTotals":{"properties":{"credits_spent":{"default":0,"title":"Credits Spent","type":"integer"},"distinct_agents":{"title":"Distinct Agents","type":"integer"},"expected_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Credits"},"failed":{"default":0,"title":"Failed","type":"integer"},"max_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Credits"},"max_runs":{"title":"Max Runs","type":"integer"},"members":{"title":"Members","type":"integer"},"planned_runs":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Null when any member's runs are not yet known.","title":"Planned Runs"},"running_now":{"default":0,"title":"Running Now","type":"integer"},"succeeded":{"default":0,"title":"Succeeded","type":"integer"}},"required":["members","distinct_agents","max_runs"],"title":"WorkforceTotals","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 runs and manage 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":"Returns the canonical list of public agents that v2 and the MPP gateway both accept on the ``expert_id`` field. Use this to pick an ``expert_id`` for ``POST /api/v2/runs``. 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":["Agents"]},"post":{"description":"Create a custom agent directly from a full configuration (name, system prompt, skills, tools). The agent is immediately usable with `POST /api/v2/runs` via its `expert_id` unless created as a `building` draft.","operationId":"create_agent_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 agent","tags":["Agents"]}},"/api/v2/agents/apply":{"post":{"description":"Diff a full desired-state manifest against the current agent (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_agent_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 agent manifest","tags":["Agents"]}},"/api/v2/agents/build":{"post":{"description":"Start the prompt-driven agent builder: describe a domain and the builder designs the agent (system prompt, skills, tools) in a sandbox. Poll `GET /api/v2/agents/build/{job_id}` for progress; on success the agent registers as a `building` draft — activate it with `PATCH /api/v2/agents/{expert_id}`.","operationId":"start_agent_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 agent build","tags":["Agents"]}},"/api/v2/agents/build/{run_id}":{"get":{"description":"Poll the status of an async agent build. Terminal states are `succeeded` (the `expert` field carries the registered draft) and `failed` (see `error`).","operationId":"get_agent_build_v2","parameters":[{"in":"path","name":"run_id","required":true,"schema":{"title":"Run 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 agent build status","tags":["Agents"]}},"/api/v2/agents/custom":{"get":{"description":"List custom agents you own or can access. Distinct from the unauthenticated `GET /api/v2/agents` registry list: this returns user-created agents, including `building` drafts. Without `limit` or `cursor` every row is returned. With either, one page is returned (`limit` 1-100, default 20) with `total`, `has_more` and an opaque `next_cursor` to pass back for the next page.","operationId":"list_custom_agents_v2","parameters":[{"in":"query","name":"include_public","required":false,"schema":{"default":true,"title":"Include Public","type":"boolean"}},{"in":"query","name":"limit","required":false,"schema":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"title":"Limit"}},{"in":"query","name":"cursor","required":false,"schema":{"anyOf":[{"maxLength":2048,"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomExpertsPage"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"List your custom agents","tags":["Agents"]}},"/api/v2/agents/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/agents` or `PATCH /api/v2/agents/{expert_id}`.","operationId":"extract_agent_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":["Agents"]}},"/api/v2/agents/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_agent_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":["Agents"]}},"/api/v2/agents/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 agent's merged state; omit it to validate a fresh create.","operationId":"validate_agent_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 agent config without saving","tags":["Agents"]}},"/api/v2/agents/{agent_id}":{"delete":{"description":"Archive a custom agent you own. The agent disappears from pickers and can no longer be run; its configuration and version history are kept. Idempotent.","operationId":"delete_agent_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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 agent","tags":["Agents"]},"get":{"description":"Read the full configuration of a custom agent (by id or slug) or a built-in registry agent: system prompt, skills, tools, output type/schema/SOP, template, input form, context files, defaults, cost cap and sharing flags.","operationId":"get_agent_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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 agent's configuration","tags":["Agents"]},"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_agent_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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 agent","tags":["Agents"]}},"/api/v2/agents/{agent_id}/campaigns":{"post":{"description":"Render an accessible agent's configured campaign template and explicitly start it.","operationId":"run_agent_campaign_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent Id","type":"string"}},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunExpertCampaignRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Run an agent's campaign","tags":["Campaigns"]}},"/api/v2/agents/{agent_id}/context-files":{"get":{"description":"Context files attached to an agent, merged from the agent repository and the text mirror.","operationId":"list_agent_context_files_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]},"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 agent repository and the extracted text is mirrored onto the agent so runs, search and the output-template scaffold can use it. Re-uploading a name replaces it.","operationId":"upload_agent_context_file_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent Id","type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_agent_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":["Agents"]}},"/api/v2/agents/{agent_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 an attachment you own). The fetched bytes run the same admission as a direct upload — extension allowlist, archive rejection, binary magic-byte validation.","operationId":"import_agent_context_file_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]}},"/api/v2/agents/{agent_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_agent_context_file_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]},"get":{"description":"Raw bytes of one context file (original upload when present, otherwise the mirrored text).","operationId":"get_agent_context_file_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]}},"/api/v2/agents/{agent_id}/plan-preview":{"post":{"description":"Run ONLY the planning phase with this agent attached — no sandbox, no 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 agent'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_agent_plan_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]}},"/api/v2/agents/{agent_id}/share":{"delete":{"description":"Revoke a previously granted user, tenant, or team access.","operationId":"unshare_agent_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]},"get":{"description":"Access grants on the agent (owner, Parcha admins, team admins, ACL admins).","operationId":"list_agent_shares_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]},"post":{"description":"Grant a user (email), an email-domain tenant, or a team access to the agent. Owners and ACL admins may share within their own email domain; Parcha admins may share anywhere.","operationId":"share_agent_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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 agent","tags":["Agents"]}},"/api/v2/agents/{agent_id}/versions":{"get":{"description":"Version history of the agent's configuration, newest first (editors only).","operationId":"list_agent_versions_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]}},"/api/v2/agents/{agent_id}/versions/{version_num}":{"get":{"description":"The full configuration snapshot stored for a version.","operationId":"get_agent_version_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]}},"/api/v2/agents/{agent_id}/versions/{version_num}/restore":{"post":{"description":"Roll the agent's configuration back to a version. The current configuration is snapshotted first (`new_version_num`) so the restore is itself reversible.","operationId":"restore_agent_version_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]}},"/api/v2/agents/{agent_id}/visibility":{"post":{"description":"Owner-only. Making an agent public (visible to everyone in the picker) is Parcha-admin-only; owners may always make it private again.","operationId":"set_agent_visibility_v2","parameters":[{"in":"path","name":"agent_id","required":true,"schema":{"title":"Agent 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":["Agents"]}},"/api/v2/attachments":{"post":{"description":"Upload files and receive an ``attachment_id`` for ``POST /runs``.\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 an 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/uploads":{"post":{"description":"Reserve an attachment and mint a one-time token for its bytes.\n\nThe caller then ``PUT``s the raw file to ``upload_url`` with the token in\n``upload_token_header``. The attachment is ``pending_upload`` until then,\n``uploaded`` once the bytes land, and only an uploaded attachment can be\nused by ``POST /runs`` or copied into an agent's context. The PUT\nneeds no API key, so a shell can move a local file without the bytes\never passing through an agent's context window.","operationId":"begin_attachment_upload_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentUploadBegin"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentUploadBeginResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Begin Attachment Upload","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 an 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 an attachment","tags":["Attachments"]}},"/api/v2/attachments/{attachment_id}/content":{"put":{"description":"Receive the raw bytes of a reserved attachment.\n\nAuthenticated by the one-time token from ``POST /attachments/uploads``\nin the ``X-Upload-Token`` header, never by an API key. The PUT claims the\nreservation atomically (``pending_upload`` -> ``uploading``) before it\nreads the body, so concurrent PUTs cannot interleave, and no database\ntransaction is held while the body streams. The body must be exactly\n``size_bytes`` long; a rejected body hands the reservation back for a\nretry, up to a small attempt cap, and success flips it to ``uploaded``.","operationId":"upload_attachment_content_v2","parameters":[{"in":"path","name":"attachment_id","required":true,"schema":{"format":"uuid","title":"Attachment Id","type":"string"}}],"requestBody":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"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":"Upload Attachment Content","tags":["Attachments"]}},"/api/v2/batch-schedules/{schedule_id}":{"delete":{"operationId":"delete_batch_schedule_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}},{"description":"Also cancel the latest run if it is still in progress","in":"query","name":"cancel_active","required":false,"schema":{"default":false,"description":"Also cancel the latest run if it is still in progress","title":"Cancel Active","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Delete Batch Schedule","tags":["Batch schedules"]},"get":{"operationId":"get_batch_schedule_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleDetail"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Get Batch Schedule","tags":["Batch schedules"]},"patch":{"operationId":"patch_batch_schedule_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBatchScheduleInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Patch Batch Schedule","tags":["Batch schedules"]}},"/api/v2/batch-schedules/{schedule_id}/pause":{"post":{"operationId":"pause_batch_schedule_endpoint_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Pause Batch Schedule Endpoint","tags":["Batch schedules"]}},"/api/v2/batch-schedules/{schedule_id}/resume":{"post":{"operationId":"resume_batch_schedule_endpoint_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Resume Batch Schedule Endpoint","tags":["Batch schedules"]}},"/api/v2/batch-schedules/{schedule_id}/run-now":{"post":{"operationId":"run_batch_schedule_now_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunBatchScheduleNowResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Run Batch Schedule Now","tags":["Batch schedules"]}},"/api/v2/batches":{"get":{"description":"List your 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 batches","tags":["Batches"]},"post":{"description":"Create a batch that starts one run per question (up to 1000 rows). Config — agent, 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 run readable via `GET /runs/{job_id}`. Rows are metered like ordinary runs 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 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":1000,"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 run id — read a finished row's report via `GET /runs/{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 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 batch","tags":["Batches"]}},"/api/v2/batches/{batch_id}/results":{"get":{"description":"The batch's return path: per row — status, `error_code`, the linked run 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 /runs/{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 runs 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 run 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 run, 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/campaigns":{"get":{"operationId":"list_campaigns_v2","parameters":[{"in":"query","name":"cursor","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"title":"Limit","type":"integer"}},{"in":"query","name":"status","required":false,"schema":{"anyOf":[{"enum":["draft","approved","running","needs_attention","completed","cancelled"],"type":"string"},{"type":"null"}],"title":"Status"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPage_CampaignSummary_"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"List Campaigns","tags":["Campaigns"]},"post":{"description":"Save a validated draft. Review it, then approve its exact review_digest to start work.","operationId":"create_campaign_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/CreateCampaignRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Create Campaign","tags":["Campaigns"]}},"/api/v2/campaigns/validate":{"post":{"description":"Check a plan and its records exactly as create would, and create nothing.\n\nReturns the problems with their paths, the normalized plan, the review digest\nand how many records the first stage can take. A plan with problems is a 200\nanswer with ``valid`` false.","operationId":"validate_campaign_v2","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCampaignRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateCampaignResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Validate Campaign","tags":["Campaigns"]}},"/api/v2/campaigns/{campaign_id}":{"get":{"operationId":"get_campaign_v2","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"title":"Campaign Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignDetail"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Get Campaign","tags":["Campaigns"]},"patch":{"description":"Replace a draft's plan, and its records when given. Pass the review_digest you read; the draft gets a new one.","operationId":"update_campaign_v2","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"title":"Campaign Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCampaignRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Update Campaign","tags":["Campaigns"]}},"/api/v2/campaigns/{campaign_id}/approve":{"post":{"operationId":"approve_campaign_v2","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"title":"Campaign Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveCampaignRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Approve Campaign","tags":["Campaigns"]}},"/api/v2/campaigns/{campaign_id}/artifacts/{deliverable_key}":{"get":{"operationId":"download_campaign_artifact_v2","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"title":"Campaign Id","type":"string"}},{"in":"path","name":"deliverable_key","required":true,"schema":{"title":"Deliverable Key","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":"Download Campaign Artifact","tags":["Campaigns"]}},"/api/v2/campaigns/{campaign_id}/browser-sessions":{"get":{"description":"Every browser of the campaign's jobs, newest first: a live view while the job drives it, the recording after.\n\nRecording URLs are signed for one hour at each read. Cheap to poll every few seconds.","operationId":"get_campaign_browser_sessions_v2","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"title":"Campaign Id","type":"string"}},{"in":"query","name":"stage_key","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stage Key"}},{"in":"query","name":"status","required":false,"schema":{"anyOf":[{"enum":["live","ended"],"type":"string"},{"type":"null"}],"title":"Status"}},{"in":"query","name":"cursor","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"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/CampaignBrowserSessions"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Get Campaign Browser Sessions","tags":["Campaigns"]}},"/api/v2/campaigns/{campaign_id}/cancel":{"post":{"operationId":"cancel_campaign_v2","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"title":"Campaign Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Cancel Campaign","tags":["Campaigns"]}},"/api/v2/campaigns/{campaign_id}/portfolio":{"get":{"operationId":"get_campaign_portfolio_v2","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"title":"Campaign Id","type":"string"}},{"in":"query","name":"stage_key","required":true,"schema":{"title":"Stage Key","type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"default":20,"title":"Limit","type":"integer"}},{"in":"query","name":"cursor","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"in":"query","name":"entity_key","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Key"}},{"in":"query","name":"status","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"in":"query","name":"search","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"}},{"in":"query","name":"filter_field","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filter Field"}},{"in":"query","name":"filter_value","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filter Value"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignPortfolio"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Get Campaign Portfolio","tags":["Campaigns"]}},"/api/v2/campaigns/{campaign_id}/retry":{"post":{"description":"Run a campaign's failed work again: one stage's when `stage_key` is given, otherwise every stage's.","operationId":"retry_campaign_v2","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"title":"Campaign Id","type":"string"}},{"in":"query","name":"stage_key","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stage Key"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryCampaignResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Retry Campaign","tags":["Campaigns"]}},"/api/v2/experts":{"get":{"deprecated":true,"description":"Returns the canonical list of public agents that v2 accepts on the ``expert_id`` field. Use this to pick an ``expert_id`` for ``POST /api/v2/runs``. 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 agents","tags":["Agents"]},"post":{"deprecated":true,"description":"Create a custom agent directly from a full configuration (name, system prompt, skills, tools). The agent is immediately usable with `POST /api/v2/runs` 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 agent","tags":["Agents"]}},"/api/v2/experts/apply":{"post":{"deprecated":true,"description":"Diff a full desired-state manifest against the current agent (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 agent manifest","tags":["Agents"]}},"/api/v2/experts/build":{"post":{"deprecated":true,"description":"Start the prompt-driven agent builder: describe a domain and the builder designs the agent (system prompt, skills, tools) in a sandbox. Poll `GET /api/v2/agents/build/{job_id}` for progress; on success the agent registers as a `building` draft — activate it with `PATCH /api/v2/agents/{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 agent build","tags":["Agents"]}},"/api/v2/experts/build/{job_id}":{"get":{"deprecated":true,"description":"Poll the status of an async agent 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 agent build status","tags":["Agents"]}},"/api/v2/experts/custom":{"get":{"deprecated":true,"description":"List custom agents you own or can access. Distinct from the unauthenticated `GET /api/v2/agents` registry list: this returns user-created agents, including `building` drafts. Without `limit` or `cursor` every row is returned. With either, one page is returned (`limit` 1-100, default 20) with `total`, `has_more` and an opaque `next_cursor` to pass back for the next page.","operationId":"list_custom_experts_v2","parameters":[{"in":"query","name":"include_public","required":false,"schema":{"default":true,"title":"Include Public","type":"boolean"}},{"in":"query","name":"limit","required":false,"schema":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"title":"Limit"}},{"in":"query","name":"cursor","required":false,"schema":{"anyOf":[{"maxLength":2048,"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomExpertsPage"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["experts:read"]}],"summary":"List your custom agents","tags":["Agents"]}},"/api/v2/experts/extract":{"post":{"deprecated":true,"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/agents` or `PATCH /api/v2/agents/{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":["Agents"]}},"/api/v2/experts/generate-workflow":{"post":{"deprecated":true,"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":["Agents"]}},"/api/v2/experts/mcp-tools":{"get":{"deprecated":true,"description":"The tools an agent 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 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 agents","tags":["Agents"]}},"/api/v2/experts/skills":{"get":{"deprecated":true,"description":"The skill catalog an agent can be linked to via `skill_names`, plus the custom skills you authored with `POST /api/v2/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 agents","tags":["Agents"]},"post":{"deprecated":true,"description":"Author a custom skill (SKILL.md) that any of your agents 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":["Agents"]}},"/api/v2/experts/skills/{skill_name}":{"get":{"deprecated":true,"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":["Agents"]}},"/api/v2/experts/validate":{"post":{"deprecated":true,"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 agent'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 agent config without saving","tags":["Agents"]}},"/api/v2/experts/{expert_id}":{"delete":{"deprecated":true,"description":"Archive a custom agent you own. The agent 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 agent","tags":["Agents"]},"get":{"deprecated":true,"description":"Read the full configuration of a custom agent (by id or slug) or a built-in registry agent: 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 agent's configuration","tags":["Agents"]},"patch":{"deprecated":true,"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 agent","tags":["Agents"]}},"/api/v2/experts/{expert_id}/campaigns":{"post":{"deprecated":true,"description":"Render an accessible agent's configured campaign template and explicitly start it.","operationId":"run_expert_campaign_v2","parameters":[{"in":"path","name":"expert_id","required":true,"schema":{"title":"Expert Id","type":"string"}},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunExpertCampaignRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Run an agent's campaign","tags":["Campaigns"]}},"/api/v2/experts/{expert_id}/context-files":{"get":{"deprecated":true,"description":"Context files attached to an agent, merged from the agent 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":["Agents"]},"post":{"deprecated":true,"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 agent repository and the extracted text is mirrored onto the agent 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":["Agents"]}},"/api/v2/experts/{expert_id}/context-files/import":{"post":{"deprecated":true,"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 an 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":["Agents"]}},"/api/v2/experts/{expert_id}/context-files/{name}":{"delete":{"deprecated":true,"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":["Agents"]},"get":{"deprecated":true,"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":["Agents"]}},"/api/v2/experts/{expert_id}/plan-preview":{"post":{"deprecated":true,"description":"Run ONLY the planning phase with this agent attached — no sandbox, no 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 agent'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":["Agents"]}},"/api/v2/experts/{expert_id}/share":{"delete":{"deprecated":true,"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":["Agents"]},"get":{"deprecated":true,"description":"Access grants on the agent (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":["Agents"]},"post":{"deprecated":true,"description":"Grant a user (email), an email-domain tenant, or a team access to the agent. 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 agent","tags":["Agents"]}},"/api/v2/experts/{expert_id}/versions":{"get":{"deprecated":true,"description":"Version history of the agent'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":["Agents"]}},"/api/v2/experts/{expert_id}/versions/{version_num}":{"get":{"deprecated":true,"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":["Agents"]}},"/api/v2/experts/{expert_id}/versions/{version_num}/restore":{"post":{"deprecated":true,"description":"Roll the agent'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":["Agents"]}},"/api/v2/experts/{expert_id}/visibility":{"post":{"deprecated":true,"description":"Owner-only. Making an agent 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":["Agents"]}},"/api/v2/integrations":{"get":{"description":"The tools an agent 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 run and need not be granted.","operationId":"list_agent_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 agents","tags":["Agents"]}},"/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":["experts:write"]},{"GrepOAuth2":["research:write"]},{"GrepOAuth2":["webhooks:write"]}],"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":["experts:write"]},{"GrepOAuth2":["research:write"]},{"GrepOAuth2":["webhooks:write"]}],"summary":"Revoke an API key","tags":["API Keys"]}},"/api/v2/loops":{"post":{"operationId":"create_loop_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/CreateLoopRequest"}}},"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 Loop","tags":["Batch schedules"]}},"/api/v2/loops/{schedule_id}":{"delete":{"operationId":"resource_delete_batch_schedule_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}},{"description":"Also cancel the latest run if it is still in progress","in":"query","name":"cancel_active","required":false,"schema":{"default":false,"description":"Also cancel the latest run if it is still in progress","title":"Cancel Active","type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Resource Delete Batch Schedule","tags":["Batch schedules"]},"get":{"operationId":"resource_get_batch_schedule_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleDetail"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"summary":"Resource Get Batch Schedule","tags":["Batch schedules"]},"patch":{"operationId":"resource_patch_batch_schedule_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBatchScheduleInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Resource Patch Batch Schedule","tags":["Batch schedules"]}},"/api/v2/loops/{schedule_id}/pause":{"post":{"operationId":"resource_pause_batch_schedule_endpoint_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Resource Pause Batch Schedule Endpoint","tags":["Batch schedules"]}},"/api/v2/loops/{schedule_id}/resume":{"post":{"operationId":"resource_resume_batch_schedule_endpoint_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleSummary"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Resource Resume Batch Schedule Endpoint","tags":["Batch schedules"]}},"/api/v2/loops/{schedule_id}/run-now":{"post":{"operationId":"resource_run_batch_schedule_now_v2","parameters":[{"in":"path","name":"schedule_id","required":true,"schema":{"title":"Schedule Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunBatchScheduleNowResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:write"]}],"summary":"Resource Run Batch Schedule Now","tags":["Batch schedules"]}},"/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/runs`` 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":{"deprecated":true,"description":"List the caller's runs, 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/runs/{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 runs","tags":["Runs"]},"post":{"deprecated":true,"description":"Start a run.","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":"Start a run","tags":["Runs"]}},"/api/v2/research/{job_id_or_slug}":{"get":{"deprecated":true,"description":"Fetch a single run 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 a run","tags":["Runs"]},"patch":{"deprecated":true,"description":"Update mutable fields on a run.\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 a run","tags":["Runs"]}},"/api/v2/research/{job_id_or_slug}/cancel":{"post":{"deprecated":true,"description":"Cancel a queued or in-progress run.\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 a run","tags":["Runs"]}},"/api/v2/research/{job_id_or_slug}/continue":{"post":{"deprecated":true,"description":"Continue a completed run 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 a run","tags":["Runs"]}},"/api/v2/research/{job_id_or_slug}/files":{"get":{"deprecated":true,"description":"List files in a run'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/runs/{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 a run's files","tags":["Runs"]}},"/api/v2/research/{job_id_or_slug}/files/{file_path}":{"get":{"deprecated":true,"description":"Download a single file from a run'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 /runs/{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 a run's file","tags":["Runs"]}},"/api/v2/research/{job_id_or_slug}/timeline":{"get":{"deprecated":true,"description":"Paginated, recent-first execution timeline for a run.\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 a run's timeline","tags":["Runs"]}},"/api/v2/run":{"get":{"deprecated":true,"description":"List the caller's runs, 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/runs/{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_legacy_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 runs","tags":["Runs"]},"post":{"deprecated":true,"description":"Start a run.","operationId":"create_run_legacy_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":"Start a run","tags":["Runs"]}},"/api/v2/run/{job_id_or_slug}":{"get":{"deprecated":true,"description":"Fetch a single run 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_legacy_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 a run","tags":["Runs"]}},"/api/v2/runs":{"get":{"description":"List the caller's runs, 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/runs/{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 runs","tags":["Runs"]},"post":{"description":"Start a run.","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":"Start a run","tags":["Runs"]}},"/api/v2/runs/{run_id_or_slug}":{"get":{"description":"Fetch a single run 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":"run_id_or_slug","required":true,"schema":{"title":"Run 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 a run","tags":["Runs"]},"patch":{"description":"Update mutable fields on a run.\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_run_v2","parameters":[{"in":"path","name":"run_id_or_slug","required":true,"schema":{"title":"Run 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 a run","tags":["Runs"]}},"/api/v2/runs/{run_id_or_slug}/cancel":{"post":{"description":"Cancel a queued or in-progress run.\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_run_v2","parameters":[{"in":"path","name":"run_id_or_slug","required":true,"schema":{"title":"Run 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 a run","tags":["Runs"]}},"/api/v2/runs/{run_id_or_slug}/continue":{"post":{"description":"Continue a completed run 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_run_v2","parameters":[{"in":"path","name":"run_id_or_slug","required":true,"schema":{"title":"Run 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 a run","tags":["Runs"]}},"/api/v2/runs/{run_id_or_slug}/files":{"get":{"description":"List files in a run'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/runs/{job_id_or_slug}/files/{file_path}`` to download individual\nfile contents.","operationId":"list_run_files_v2","parameters":[{"in":"path","name":"run_id_or_slug","required":true,"schema":{"title":"Run 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 a run's files","tags":["Runs"]}},"/api/v2/runs/{run_id_or_slug}/files/{file_path}":{"get":{"description":"Download a single file from a run'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 /runs/{job_id_or_slug}/files`` listing.","operationId":"read_run_file_v2","parameters":[{"in":"path","name":"run_id_or_slug","required":true,"schema":{"title":"Run 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 a run's file","tags":["Runs"]}},"/api/v2/runs/{run_id_or_slug}/timeline":{"get":{"description":"Paginated, recent-first execution timeline for a run.\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_run_timeline_v2","parameters":[{"in":"path","name":"run_id_or_slug","required":true,"schema":{"title":"Run 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 a run's timeline","tags":["Runs"]}},"/api/v2/skills":{"get":{"description":"The skill catalog an agent can be linked to via `skill_names`, plus the custom skills you authored with `POST /api/v2/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_agent_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 agents","tags":["Agents"]},"post":{"description":"Author a custom skill (SKILL.md) that any of your agents can link via `skill_names`. Re-posting the same name overwrites your own skill in place (`created: false`).","operationId":"create_agent_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":["Agents"]}},"/api/v2/skills/{skill_name}":{"get":{"description":"Full SKILL.md content of a catalog skill or one of your custom skills.","operationId":"get_agent_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":["Agents"]}},"/api/v2/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":"resource_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":"Resource Get Billing Usage","tags":["Billing"]}}},"security":[{"GrepApiKeyBearer":[]},{"GrepOAuth2":["research:read"]}],"tags":[{"name":"Runs"},{"name":"Attachments"},{"name":"Billing"},{"name":"Agent-to-Agent"}]}