The Contextual Schema Optimization API is an asynchronous, organization-scoped API for creating and improving extraction configurations. Reducto provides the API base URL during beta onboarding.
When to use
Use the API when an application needs to submit Contextual Schema Optimization runs, monitor them programmatically, or receive completion webhooks. For interactive work with local documents, use the reducto-beta MCP instead.
Defaults
| Setting | Default |
|---|---|
run_id |
Generated by Contextual Schema Optimization when omitted |
include_full_results |
false |
user_prompt |
Empty string |
webhook |
No completion webhook |
webhook.channels |
Empty; publish to every eligible endpoint registered for the organization |
Authentication
Send your Reducto API key as a bearer token on every request:
Authorization: Bearer $REDUCTO_API_KEYThe organization_id in a submission must match the credential’s organization. Contextual Schema Optimization also scopes run retrieval by organization. A credential from another organization receives no run data.
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST |
/setup-use-case |
Create a schema and system prompt for a new extraction use case |
POST |
/schema-optimize |
Improve an existing schema and system prompt |
POST |
/health-check |
Coming soon; not available during the current design-partner beta |
GET |
/runs/{run_id} |
Retrieve run status and finished-run artifacts |
POST |
/workspace-upload |
Create a presigned upload for a native workspace ZIP |
Required inputs at a glance
For each available workflow, choose either inline inputs or a native workspace ZIP:
| Endpoint | Required inline inputs | Workspace input |
|---|---|---|
POST /setup-use-case |
organization_id, 3–10,000 document_refs, and exactly one extraction goal: a non-empty user_prompt or a requirement_refs entry named what_we_want.md |
organization_id and workspace_ref |
POST /schema-optimize |
organization_id, current_schema, current_system_prompt, and 3–10,000 document_refs; current_system_prompt must be present but may be an empty string |
organization_id and workspace_ref |
Do not combine workspace_ref with the endpoint’s inline documents or configuration fields. Document identifiers must be unique within a run, external files must use HTTPS URLs, and unknown request fields are rejected. Common optional controls such as run_id, include_full_results, webhook, and metadata work with either input mode.
Supported document extensions are .pdf, .doc, .docx, .xls, .xlsx, .csv, .tsv, .ppt, .pptx, .png, .jpg, .jpeg, .tif, .tiff, .bmp, .webp, .heic, .txt, .html, .eml, .msg, and .numbers.
Both available submission endpoints return 202 Accepted:
{
"status": "accepted",
"run_id": "resume-optimize-2026-09-02",
"provider_run_id": "resume-optimize-2026-09-02",
"status_url": "/runs/resume-optimize-2026-09-02"
}run_id is optional on submission. If you omit it, Contextual Schema Optimization generates one. If you provide it, use 1–128 letters, numbers, periods, underscores, or hyphens, beginning with a letter or number. Treat a run ID as immutable and do not reuse it for different inputs.
Use run_id and status_url to retrieve the run. provider_run_id currently matches run_id and can be ignored.
Common request fields
| Field | Type | Required | Description |
|---|---|---|---|
organization_id |
string | Yes | Reducto organization that owns and pays for the run |
run_id |
string | No | Caller-defined idempotent run identifier |
user_prompt |
string | No | Extraction goal, known failures, or other guidance; maximum 50,000 characters |
webhook |
object | No | Svix completion notification configuration |
metadata |
object | No | Optional Studio identifiers; when provided, it requires pipeline_id, processor_id, config_id, and non-negative config_version |
deep_extract_model |
v2 | v3 | v3-turbo |
No | Deep Extract model used by setup and schema optimization |
POST /setup-use-case and POST /schema-optimize also accept include_full_results. This boolean includes detailed evaluation outputs in the result bundle and defaults to false.
For customer webhooks, use:
{
"webhook": {
"mode": "svix",
"channels": ["schema-optimization-production"]
}
}channels may contain up to 32 values of 1–128 characters. An empty list delivers to every eligible endpoint registered for the organization. See Completion webhooks for registration, verification, retries, and event fields.
Set up a new use case
POST /setup-use-case creates an extraction schema and system prompt from representative documents and requirements.
import os
import requests
payload = {
"organization_id": "org_123",
"run_id": "resume-setup-001",
"document_refs": [
{
"document_id": f"resume-{index}",
"file_name": f"resume-{index}.pdf",
"url": f"https://example.com/resume-{index}.pdf",
}
for index in range(1, 4)
],
"user_prompt": (
"Extract the candidate profile, work history, education, and skills. "
"Preserve responsibility text verbatim."
),
}
response = requests.post(
f"{os.environ['CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL']}/setup-use-case",
headers={"Authorization": f"Bearer {os.environ['REDUCTO_API_KEY']}"},
json=payload,
)
response.raise_for_status()
print(response.json())const payload = {
organization_id: "org_123",
run_id: "resume-setup-001",
document_refs: [1, 2, 3].map((index) => ({
document_id: `resume-${index}`,
file_name: `resume-${index}.pdf`,
url: `https://example.com/resume-${index}.pdf`,
})),
user_prompt:
"Extract the candidate profile, work history, education, and skills. Preserve responsibility text verbatim.",
};
const response = await fetch(`${process.env.CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL}/setup-use-case`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.REDUCTO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());curl --request POST "$CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL/setup-use-case" \
--header "Authorization: Bearer $REDUCTO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"organization_id": "org_123",
"run_id": "resume-setup-001",
"document_refs": [
{
"document_id": "resume-1",
"file_name": "resume-1.pdf",
"url": "https://example.com/resume-1.pdf"
},
{
"document_id": "resume-2",
"file_name": "resume-2.pdf",
"url": "https://example.com/resume-2.pdf"
},
{
"document_id": "resume-3",
"file_name": "resume-3.pdf",
"url": "https://example.com/resume-3.pdf"
}
],
"user_prompt": "Extract the candidate profile, work history, education, and skills. Preserve responsibility text verbatim."
}'Setup document reference
| Field | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes | Unique document identifier within the run |
file_name |
string | Yes | Safe base name with a supported document extension |
url |
string | Yes | Public or presigned HTTPS URL without embedded credentials or a fragment |
sha256 |
string | No | Expected lowercase or uppercase SHA-256 digest |
size_bytes |
integer | No | Expected byte length; maximum 50 MiB |
You may provide up to 20 requirement_refs. Each reference has requirement_id, file_name, url, and optional sha256 and size_bytes. Supply either a non-empty user_prompt or a requirement named what_we_want.md, but not both.
Optimize an existing schema
POST /schema-optimize improves an existing JSON Schema and system prompt using representative documents. Attach ground_truth_url where expected JSON is available.
Save the request body as resume-optimization.json:
{
"organization_id": "org_123",
"run_id": "resume-optimize-001",
"current_schema": {
"type": "object",
"properties": {
"candidate_name": { "type": "string" },
"work_experience": {
"type": "array",
"items": {
"type": "object",
"properties": {
"job_title": { "type": "string" },
"company": { "type": "string" },
"responsibilities": {
"type": "array",
"items": { "type": "string" }
}
}
}
}
}
},
"current_system_prompt": "Extract resume information exactly as written. Do not infer missing values.",
"document_refs": [
{
"document_id": "resume-1",
"file_name": "resume-1.pdf",
"document_url": "https://example.com/resume-1.pdf",
"ground_truth_url": "https://example.com/resume-1.json"
},
{
"document_id": "resume-2",
"file_name": "resume-2.pdf",
"document_url": "https://example.com/resume-2.pdf",
"ground_truth_url": "https://example.com/resume-2.json"
},
{
"document_id": "resume-3",
"file_name": "resume-3.pdf",
"document_url": "https://example.com/resume-3.pdf",
"ground_truth_url": "https://example.com/resume-3.json"
}
],
"user_prompt": "Preserve responsibility text verbatim and return null instead of inventing missing dates.",
"include_full_results": false,
"webhook": { "mode": "svix", "channels": ["schema-optimization-production"] }
}Then submit it with any HTTP client:
import json
import os
from pathlib import Path
import requests
payload = json.loads(Path("resume-optimization.json").read_text())
response = requests.post(
f"{os.environ['CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL']}/schema-optimize",
headers={"Authorization": f"Bearer {os.environ['REDUCTO_API_KEY']}"},
json=payload,
)
response.raise_for_status()
print(response.json())import { readFile } from "node:fs/promises";
const payload = JSON.parse(await readFile("resume-optimization.json", "utf8"));
const response = await fetch(`${process.env.CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL}/schema-optimize`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.REDUCTO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());curl --request POST "$CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL/schema-optimize" \
--header "Authorization: Bearer $REDUCTO_API_KEY" \
--header "Content-Type: application/json" \
--data @resume-optimization.jsonSchema optimization document reference
| Field | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes | Unique document identifier within the run |
document_url |
string | Yes | Public or presigned HTTPS URL for the source document |
file_name |
string | When needed | Safe base name with a supported extension; required when the URL path does not include one |
ground_truth_url |
string | No | Public or presigned HTTPS URL for the expected JSON object |
Inline inputs require current_schema and current_system_prompt. You may leave the system prompt empty intentionally, but the field must still be present. Each document_id must be unique.
Health checks
Health checks are coming soon and are not part of the current design-partner API contract. Reducto will provide the finalized endpoint conventions when the workflow is ready to use.
Upload a native workspace
Use a native workspace when inputs exceed the 150 MiB inline limit or when it is easier to package local files directly.
Create an upload session
import os import requests response = requests.post( f"{os.environ['CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL']}/workspace-upload", headers={"Authorization": f"Bearer {os.environ['REDUCTO_API_KEY']}"}, json={"organization_id": "org_123"}, ) response.raise_for_status() upload = response.json() print(upload)const response = await fetch(`${process.env.CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL}/workspace-upload`, { method: "POST", headers: { Authorization: `Bearer ${process.env.REDUCTO_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ organization_id: "org_123" }), }); if (!response.ok) throw new Error(await response.text()); const upload = await response.json(); console.log(upload);upload="$(curl --silent --show-error --fail-with-body \ --request POST "$CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL/workspace-upload" \ --header "Authorization: Bearer $REDUCTO_API_KEY" \ --header "Content-Type: application/json" \ --data '{"organization_id":"org_123"}')" PRESIGNED_URL="$(printf '%s' "$upload" | jq --raw-output '.presigned_url')" FILE_ID="$(printf '%s' "$upload" | jq --raw-output '.file_id')"The response contains a
file_idsuch asreducto://...zipand a one-hourpresigned_url.Upload the ZIP
with open("schema-optimization-workspace.zip", "rb") as workspace: response = requests.put(upload["presigned_url"], data=workspace) response.raise_for_status()import { readFile } from "node:fs/promises"; const response = await fetch(upload.presigned_url, { method: "PUT", body: await readFile("schema-optimization-workspace.zip"), }); if (!response.ok) throw new Error(await response.text());curl --request PUT --upload-file ./schema-optimization-workspace.zip "$PRESIGNED_URL"Send the raw ZIP bytes without an
Authorizationheader.Submit the run
Pass the response’s
file_idasworkspace_ref. Do not combineworkspace_refwith inline documents, schema, prompt, or requirements.response = requests.post( f"{os.environ['CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL']}/schema-optimize", headers={"Authorization": f"Bearer {os.environ['REDUCTO_API_KEY']}"}, json={ "organization_id": "org_123", "workspace_ref": upload["file_id"], "include_full_results": False, }, ) response.raise_for_status() print(response.json())const response = await fetch(`${process.env.CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL}/schema-optimize`, { method: "POST", headers: { Authorization: `Bearer ${process.env.REDUCTO_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ organization_id: "org_123", workspace_ref: upload.file_id, include_full_results: false, }), }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json());curl --request POST "$CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL/schema-optimize" \ --header "Authorization: Bearer $REDUCTO_API_KEY" \ --header "Content-Type: application/json" \ --data "$(jq --null-input --arg file_id "$FILE_ID" '{ organization_id: "org_123", workspace_ref: $file_id, include_full_results: false }')"
For setup, the ZIP must contain:
requirements/
what_we_want.md
documents/
<document_id>/
<document>For schema optimization, the ZIP must contain:
schema.json
system_prompt.txt
documents/
<document_id>/
<document>
ground_truth.json # optionalEach document directory must contain exactly one supported document. Setup workspaces cannot include ground_truth.json.
Poll a run
Poll the relative status_url from the submission response until the run reaches a final status.
Results remain available for 24 hours after the run finishes. Download or copy the results you need during that window; after it closes, run retrieval returns 404.
import os
import requests
response = requests.get(
f"{os.environ['CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL']}/runs/{os.environ['CONTEXTUAL_SCHEMA_OPTIMIZATION_RUN_ID']}",
headers={"Authorization": f"Bearer {os.environ['REDUCTO_API_KEY']}"},
)
response.raise_for_status()
print(response.json())const response = await fetch(
`${process.env.CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL}/runs/${process.env.CONTEXTUAL_SCHEMA_OPTIMIZATION_RUN_ID}`,
{ headers: { Authorization: `Bearer ${process.env.REDUCTO_API_KEY}` } },
);
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());curl "$CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL/runs/$CONTEXTUAL_SCHEMA_OPTIMIZATION_RUN_ID" \
--header "Authorization: Bearer $REDUCTO_API_KEY"{
"provider_run_id": "resume-optimize-001",
"workflow": "schema_optimize",
"status": "completed",
"artifacts": {
"refined_schema": {},
"refined_system_prompt": "...",
"accuracy": 0.97,
"accuracy_metric": "ground_truth_audited_accuracy",
"report_markdown": "...",
"completeness": []
},
"partial_reason": null,
"error": null
}| Status | Meaning |
|---|---|
accepted |
The request is durable and waiting to start |
running |
Contextual Schema Optimization is processing the workspace |
completed |
Contextual Schema Optimization produced all required output artifacts |
partial |
Contextual Schema Optimization produced a usable result with warnings in partial_reason |
failed |
Contextual Schema Optimization produced no usable result; inspect error |
Result artifacts differ by workflow. Setup returns a new schema/system prompt or split configuration. Schema optimization returns the refined configuration and evaluation evidence.
Completion webhooks
Completion webhooks notify your service when a setup or schema-optimization run finishes. The event contains identifiers and status only; fetch the run from status_url to retrieve its results.
Register a destination
Contextual Schema Optimization uses the same Svix-backed webhook destinations as other Reducto asynchronous jobs. Register an HTTPS endpoint for your organization before requesting notifications.
Open the webhook portal
Call
POST https://platform.reducto.ai/configure_webhookwith the same Reducto API key you use for Contextual Schema Optimization. The response contains a short-lived URL for your organization’s webhook portal.import os import requests response = requests.post( "https://platform.reducto.ai/configure_webhook", headers={"Authorization": f"Bearer {os.environ['REDUCTO_API_KEY']}"}, ) response.raise_for_status() print(response.json())const response = await fetch("https://platform.reducto.ai/configure_webhook", { method: "POST", headers: { Authorization: `Bearer ${process.env.REDUCTO_API_KEY}` }, }); if (!response.ok) throw new Error(await response.text()); console.log(await response.json());curl --request POST "https://platform.reducto.ai/configure_webhook" \ --header "Authorization: Bearer $REDUCTO_API_KEY"Add your destination
Open the returned portal URL, add your HTTPS endpoint, and save its signing secret. Events are delivered only to destinations registered for the authenticated organization, not to an arbitrary URL in an optimization request.
Request notifications
Add the
webhookobject shown in Common request fields to eitherPOST /setup-use-caseorPOST /schema-optimize.
Event contract
One workflow-specific event is published after the run reaches completed, partial, or failed:
workflow |
event_type |
|---|---|
schema_optimize |
schema_optimization.completed |
setup_use_case |
use_case_setup.completed |
Health-check webhooks are coming soon and are not part of the current design-partner contract.
The .completed suffix means the workflow finished, not that it necessarily succeeded. Treat status as the authoritative outcome.
{
"event_id": "evt_142bb88644ba5ea7ab1ec12d9e95dc76",
"event_type": "schema_optimization.completed",
"run_id": "run-5a0ec96d9b724339ab5cb1071ddf602e",
"provider_run_id": "run-5a0ec96d9b724339ab5cb1071ddf602e",
"workflow": "schema_optimize",
"status": "completed",
"completed_at": "2026-09-02T19:30:00Z",
"status_url": "/runs/run-5a0ec96d9b724339ab5cb1071ddf602e"
}The webhook does not include schemas, prompts, document contents, or temporary artifact URLs.
Verify the signature
Svix signs each request with the endpoint secret from the webhook portal. Verify the raw request body before parsing JSON.
import os
from flask import Flask, request
from svix.webhooks import Webhook
app = Flask(__name__)
@app.post("/webhooks/contextual-schema-optimization")
def contextual_schema_optimization_webhook():
event = Webhook(os.environ["REDUCTO_WEBHOOK_SECRET"]).verify(
request.get_data(), request.headers
)
handle_contextual_schema_optimization_event(event)
return "", 204import express from "express";
import { Webhook } from "svix";
const app = express();
app.post("/webhooks/contextual-schema-optimization", express.raw({ type: "application/json" }), (req, res) => {
const event = new Webhook(process.env.REDUCTO_WEBHOOK_SECRET).verify(
req.body,
req.headers,
);
handleContextualSchemaOptimizationEvent(event);
res.sendStatus(204);
});Reject requests whose signature verification fails. Do not verify a parsed and re-serialized body because byte changes invalidate the signature.
Retries and idempotency
Reducto tries to publish the event to Svix up to three times with exponential backoff. Svix manages delivery to your registered endpoint after accepting the event. A crash after delivery but before acknowledgement can produce a duplicate.
Store event_id with a uniqueness constraint before processing the event or fetching and applying the result. All attempts for one run use the same event_id, body, and Svix idempotency key. Return a 2xx response after durably accepting the event.
Webhook delivery never changes the run’s final status. If Reducto cannot publish the event, retrieve the result by polling status_url as described in Poll a run.
Recommended processing flow
- Verify the signature and deduplicate on
event_id. - Fetch
status_urland inspectstatus. - Download or copy the result within its 24-hour availability window.
- Promote a refined configuration only after your own validation when the status is
completedorpartial. - Keep the previous configuration active when the status is
failed.
Treat each run as immutable. Do not reuse a run_id for different inputs.
Troubleshooting webhooks
- No completion event: Confirm that the webhook portal lists the endpoint under the same organization as the run. If the request specifies
channels, confirm that the endpoint subscribes to one of them. Pollstatus_urlwhile correcting the destination. - Signature verification fails: Verify the exact raw request body with the endpoint’s current
whsec_secret. Do not parse or re-serialize the body first. - An event is processed twice: Store
event_idwith a uniqueness constraint before applying the result, and return2xxonly after durable acceptance.
Error behavior
401means the bearer credential is missing, invalid, or expired.403means the credential does not grant access to the submitted organization.404on run retrieval means the run does not exist or the caller cannot access it.422means the JSON body failed validation.503means Contextual Schema Optimization could not authenticate, launch, store, or deliver the requested run at that time.
Correct validation errors before retrying. For launch or service failures, keep the same run_id only when retrying the same immutable input.