Skip to content
Log in

Contextual Schema Optimization API

Submit setup and schema-optimization runs through the callable Contextual Schema Optimization API.

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_KEY

The 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.json

Schema 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.

  1. 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_id such as reducto://...zip and a one-hour presigned_url.

  2. 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 Authorization header.

  3. Submit the run

    Pass the response’s file_id as workspace_ref. Do not combine workspace_ref with 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  # optional

Each 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.

  1. Open the webhook portal

    Call POST https://platform.reducto.ai/configure_webhook with 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"
  2. 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.

  3. Request notifications

    Add the webhook object shown in Common request fields to either POST /setup-use-case or POST /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 "", 204
import 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.

  1. Verify the signature and deduplicate on event_id.
  2. Fetch status_url and inspect status.
  3. Download or copy the result within its 24-hour availability window.
  4. Promote a refined configuration only after your own validation when the status is completed or partial.
  5. 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. Poll status_url while 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_id with a uniqueness constraint before applying the result, and return 2xx only after durable acceptance.

Error behavior

  • 401 means the bearer credential is missing, invalid, or expired.
  • 403 means the credential does not grant access to the submitted organization.
  • 404 on run retrieval means the run does not exist or the caller cannot access it.
  • 422 means the JSON body failed validation.
  • 503 means 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.

Type to search…

escClose