---
title: "Contextual Schema Optimization API"
description: "Submit setup and schema-optimization runs through the callable Contextual Schema Optimization API."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/contextual-schema-optimization/reducto-beta) 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:

```bash
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 |

> **Note:** Health checks are coming soon. Do not integrate with `POST /health-check` yet; its request and response contract may change before release.

## 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`:

```json
{
  "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:

```json
{
  "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](#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.

**Python**

```python
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())
```

**Node.js**

```javascript
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**

```bash
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`:

```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:

**Python**

```python
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())
```

**Node.js**

```javascript
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**

```bash
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**

   **Python**

   ```python
   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)
   ```

   **Node.js**

   ```javascript
   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);
   ```

   **cURL**

   ```bash
   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**

   **Python**

   ```python
   with open("schema-optimization-workspace.zip", "rb") as workspace:
       response = requests.put(upload["presigned_url"], data=workspace)
   response.raise_for_status()
   ```

   **Node.js**

   ```javascript
   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**

   ```bash
   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.

   **Python**

   ```python
   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())
   ```

   **Node.js**

   ```javascript
   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**

   ```bash
   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:

```text
requirements/
  what_we_want.md
documents/
  <document_id>/
    <document>
```

For schema optimization, the ZIP must contain:

```text
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`.

**Python**

```python
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())
```

**Node.js**

```javascript
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**

```bash
curl "$CONTEXTUAL_SCHEMA_OPTIMIZATION_API_URL/runs/$CONTEXTUAL_SCHEMA_OPTIMIZATION_RUN_ID" \
  --header "Authorization: Bearer $REDUCTO_API_KEY"
```

```json
{
  "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.

   **Python**

   ```python
   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())
   ```

   **Node.js**

   ```javascript
   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**

   ```bash
   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](#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.

```json
{
  "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.

**Python**

```python
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
```

**Node.js**

```javascript
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](#poll-a-run).

### Recommended processing flow

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.

Source: https://docs.reducto.ai/contextual-schema-optimization/api/index.mdx
