---
title: "Set output schema"
method: PUT
path: "/projects/{project_id}/schema/"
tags: ["Projects"]
---

# Set output schema

`PUT /projects/{project_id}/schema/`

## Request

- Base URL: `https://api.parsewise.ai/api/v1`
- URL: `https://api.parsewise.ai/api/v1/projects/{project_id}/schema/`
- Auth: API key in header `X-API-Key`

Set the target JSON output schema and choose automatic or manual mapping. Automatic mapping clears any stored mapping and regenerates agents and the mapping in the background. Manual mapping can be provided in the same request, explicitly cleared with `null`, or omitted only for a new or changed schema that has no usable mapping.

## Path parameters

- `project_id` string, uuid, required

## Request body

- V1SchemaSetRequestRequest
  - `schema` unknown, required
  - `auto_map` boolean, required: When true, clear any stored mapping and generate agents and a new mapping in the background. When false, manage the mapping manually in this request.
  - `mapping` unknown

## Response `200`

- V1SchemaResponse: Target schema and output mapping state.
  - `schema` unknown, required
  - `auto_map` boolean, required: Whether automatic agent and mapping generation is active for the current mapping state.
  - `mapping` unknown, required
  - `status` 'pending' | 'success' | 'failed', required: * `pending` - pending * `success` - success * `failed` - failed
  - `source` 'llm' | 'manual', required: * `llm` - llm * `manual` - manual
  - `error` string, nullable, required: Failure detail when `status` is `failed`, otherwise null.
  - `generated_at` string, date-time, nullable, required: When the mapping was last saved or generated.
  - `schema_in_sync` boolean, required: True when the mapping was saved against the current output schema. False after the schema changes, meaning the mapping should be re-saved or regenerated.
  - `diagnostics` V1MappingDiagnostic[], required: Validation findings for the stored mapping against the current schema and agents.
    - `path` string, required: Position in the schema tree using `a/b/[*]/c` notation (`[*]` for array items, `{*}` for dimension-keyed object values). Empty string for the root.
    - `severity` 'error' | 'warning', required: * `error` - error * `warning` - warning
    - `code` 'node_kind_mismatch' | 'property_not_in_schema' | 'required_unmapped' | 'agent_not_found' | 'agent_ambiguous' | 'dimension_not_found' | 'dimension_not_on_agent' | 'dimension_not_in_scope' | 'dimension_value_unknown' | 'type_incompatible', required: * `node_kind_mismatch` - node_kind_mismatch * `property_not_in_schema` - property_not_in_schema * `required_unmapped` - required_unmapped * `agent_not_found` - agent_not_found * `agent_ambiguous` - agent_ambiguous * `dimension_not_found` - dimension_not_found * `dimension_not_on_agent` - dimension_not_on_agent * `dimension_not_in_scope` - dimension_not_in_scope * `dimension_value_unknown` - dimension_value_unknown * `type_incompatible` - type_incompatible
    - `message` string, required: Human-readable explanation of the finding.

---

[API](https://skmtc.dev/parsewise/apis/parsewise-api.md) - [All operations](https://skmtc.dev/parsewise/apis/parsewise-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parsewise/apis/parsewise-api/revisions/5db46512debf?raw)