Set output schema

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.

On this page

HTTP request 

PUT https://api.parsewise.ai/api/v1/projects/{project_id}/schema/

URI Parameters

Name In Required Type Description
project_id path Yes string (uuid)  

Request Header

Name Required Type Description
X-API-Key Yes string API key with the pw_live_ prefix. See Authentication.

Request Body

Supported content types: application/json, application/x-www-form-urlencoded, multipart/form-data.

Name Required Type Description
schema Yes any A valid JSON Schema (Draft 2020-12) describing the desired output shape.
auto_map Yes boolean 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 No any (nullable) Manual declarative mapping node tree. With auto_map=false, provide an object to save it or null to clear it. With auto_map=true, omit this field or set it to null.

Responses

Status Type Description
200 V1SchemaResponse —

Security

  • ApiKeyAuth — apiKey — in X-API-Key header. API key with pw_live_ prefix.

Python example 

import os
import requests

API_KEY = os.environ["PARSEWISE_API_KEY"]
BASE_URL = "https://api.parsewise.ai/api/v1"

project_id = "<uuid>"

body = {
    "schema": "...",
    "auto_map": False,
    "mapping": "...",  # optional
}

resp = requests.put(
    f"{BASE_URL}/projects/{project_id}/schema/",
    headers={"X-API-Key": API_KEY},
    json=body,
)
resp.raise_for_status()
print(resp.json() if resp.content else None)

Definitions

CodeEnum

Type: string. One of:

  • 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

SeverityEnum

Type: string. One of:

  • error
  • warning

Status56fEnum

Type: string. One of:

  • pending
  • success
  • failed

V1MappingDiagnostic

One validation finding at a schema position of the output mapping.

Name Required Type Description
path Yes string Position in the schema tree using a/b/[*]/c notation ([*] for array items, {*} for dimension-keyed object values). Empty string for the root.
severity Yes SeverityEnum How serious the finding is. error findings make the mapping unsaveable; warning findings are informational — the mapping can be saved and affected fields are omitted from the output.
code Yes CodeEnum Machine-readable finding type.
message Yes string Human-readable explanation of the finding.

V1SchemaResponse

Target schema and output mapping state.

Name Required Type Description
schema Yes any The project target JSON Schema (Draft 2020-12).
auto_map Yes boolean Whether automatic agent and mapping generation is active for the current mapping state.
mapping Yes any (nullable) The declarative mapping node tree, or null when no mapping has been saved yet. Nodes reference agents and dimensions by name, so a mapping can be reused across projects with the same agent names.
status Yes Status56fEnum Lifecycle of the mapping. pending while no usable mapping exists, success when a mapping is saved, failed when automatic generation failed.
source Yes V1SchemaResponseSourceEnum Whether the mapping was generated automatically (llm) or authored manually (manual).
error Yes string (nullable) Failure detail when status is failed, otherwise null.
generated_at Yes string (date-time) (nullable) When the mapping was last saved or generated.
schema_in_sync Yes boolean 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 Yes array<V1MappingDiagnostic> Validation findings for the stored mapping against the current schema and agents.

V1SchemaResponseSourceEnum

Type: string. One of:

  • llm
  • manual

V1SchemaSetRequestRequest

Name Required Type Description
schema Yes any A valid JSON Schema (Draft 2020-12) describing the desired output shape.
auto_map Yes boolean 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 No any (nullable) Manual declarative mapping node tree. With auto_map=false, provide an object to save it or null to clear it. With auto_map=true, omit this field or set it to null.