Update an agent

Replace the agent’s configuration (instructions, dimensions, etc.). If the change invalidates already-extracted results (e.g. editing the prompt), the affected extraction results are cleared automatically. Returns the updated agent.

On this page

HTTP request 

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

URI Parameters

Name In Required Type Description
agent_id path Yes string (uuid)  
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
name Yes string Human-readable name shown for the agent (e.g. “Contract value”).
extraction_instructions Yes string Natural-language instructions describing what the agent should extract from each document.
value_type No ValueTypeF41Enum Type of value the agent produces.
unit No string Optional unit for numeric values (e.g. USD, %, kg). Used to normalise extracted values into a consistent unit and for display.
examples No string Free-form examples of expected values, used to steer the agent towards the right kind of answer.
inconsistency_instructions No string Custom instructions for inconsistency checking. If empty, default instructions will be used.
resolution_instructions No string Custom instructions for entity resolution. If empty, default instructions will be used.
enable_complex_calculations_in_resolution No boolean Enable advanced computational analysis for complex resolution tasks involving calculations or data transformations.
enable_web_search No boolean Enable web search to supplement extraction results with data from the web.
dimensions No array<V1AgentDimensionRequest> Dimensions to configure on the agent, in declaration order. Each entry attaches an existing project dimension to the agent and configures its values. Omit to create the agent with no dimensions; on update, omit to leave existing dimensions untouched and pass an empty array to remove them all.

Responses

Status Type Description
200 TopicInstance —

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"

agent_id = "<uuid>"
project_id = "<uuid>"

body = {
    "name": "...",
    "extraction_instructions": "...",
    "value_type": "string",  # optional
    "unit": "...",  # optional
    "examples": "...",  # optional
    "inconsistency_instructions": "...",  # optional
    "resolution_instructions": "...",  # optional
    "enable_complex_calculations_in_resolution": False,  # optional
    "enable_web_search": False,  # optional
    "dimensions": [],  # optional
}

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

Definitions

ExtractionStatusEnum

Type: string. One of:

  • Pending
  • Processed
  • No Result

NullEnum

Type: any. One of:

  • None

TopicInstance

Name Required Type Description
id Yes string (uuid) Stable identifier for the agent (UUID).
project_id Yes string (uuid) Identifier of the project this agent belongs to.
template_id Yes string (uuid) (nullable) Identifier of the agent template this agent was created from, or null if the agent was created from scratch.
dimensions Yes array<V1AgentDimensionResponse> Dimensions configured on this agent, in display order. Each dimension carries its dimension id, mapping id, name, ordered list of values, and whether values are dynamically discovered from documents (are_values_dynamic=true) or static.
created_at Yes string (date-time) Timestamp when the agent was created.
extraction_status Yes ExtractionStatusEnum Whether the agent has finished extracting against the project’s current documents. Pending while extractions are missing or in flight, Processed once all expected resolutions are present, and No Result when the agent has completed but produced no resolved values.
requires_attention Yes boolean True if any of this agent’s resolved values need attention (for example, unresolved inconsistencies between source documents).
improvement_tip_summary Yes string (nullable) Summary of the selected active improvement suggestion, or null when none is available.
name No string Human-readable name shown for the agent (e.g. “Contract value”).
extraction_instructions No string Natural-language instructions describing what the agent should extract from each document.
value_type No ValueTypeF41Enum Type of value the agent produces.
unit No string Optional unit for numeric values (e.g. USD, %, kg). Used to normalise extracted values into a consistent unit and for display.
examples No string Free-form examples of expected values, used to steer the agent towards the right kind of answer.
inconsistency_instructions No string Custom instructions for inconsistency checking. If empty, default instructions will be used.
resolution_instructions No string Custom instructions for entity resolution. If empty, default instructions will be used.
enable_complex_calculations_in_resolution No boolean Enable advanced computational analysis for complex resolution tasks involving calculations or data transformations.
enable_web_search No boolean Enable web search to supplement extraction results with data from the web.
inconsistency_summary No string (nullable) AI-generated summary of why extracted values disagree across documents. Populated when inconsistencies are detected; null otherwise.
is_draft No boolean Whether the agent is a draft. Should always be false for API callers; drafts are not returned in V1 list or retrieve responses.

V1AgentDimensionRequest

One dimension to attach to an agent, used inside the dimensions array of an agent create/update request.

A dimension breaks an agent’s extraction down by a categorical axis (for example, by document type or by a tag). Reference the dimension you want to attach by its dimension_id and supply the allowed values (or set are_values_dynamic to discover them from the documents at extraction time). To remove all dimensions from an agent on update, send dimensions: [].

Name Required Type Description
dimension_id Yes string (uuid) ID of the dimension to attach to the agent.
are_values_dynamic No boolean When true, allowed values for this dimension are discovered dynamically from the project’s documents during extraction. When false, values defines the fixed set of allowed values.
values No array<string> Allowed values for this dimension. Required (and must be non-empty) when are_values_dynamic is false; ignored when values are dynamic.
description No string Optional update to the dimension’s description. Note: this updates the dimension across every agent in the project that shares it.
value_type No ValueTypeF41Enum | NullEnum Optional update to the dimension’s value type. Only string (free text) and number (numeric, pair with a unit) are supported. Note: this updates the dimension across every agent in the project that shares it.
add_to_all_agents No boolean When true, this dimension is also attached to every other agent in the project (and applied to any future agents created in the project).

V1AgentDimensionResponse

One dimension attached to an agent, as returned in the dimensions list of an agent response.

A dimension breaks an agent’s extraction down by a categorical axis (for example, by document type or by a tag). Each entry here pairs the dimension definition (dimension_id) with how it is configured on this specific agent (allowed values, whether values are discovered dynamically from the documents, etc.).

Name Required Type Description
dimension_id Yes string (uuid) Identifier of the dimension (project-scoped dimension definition this instance attaches to the agent).
dimension_mapping_id Yes string (uuid) Identifier of this dimension’s attachment to the agent. Carries the agent-specific settings for the dimension, such as order and are_values_dynamic.
name Yes string Human-readable dimension name (e.g. “Region”, “Year”).
description Yes string Free-text description of the dimension, or empty string if none was provided.
values Yes array<string> Dimension values used to key extraction results. When are_values_dynamic is true these are discovered from the source documents; otherwise they are the static values configured on the agent.
value_count Yes integer Number of entries in values.
order Yes integer Display/declaration order of this dimension relative to the agent’s other dimensions.
are_values_dynamic Yes boolean True when the dimension’s values are dynamically discovered from documents; false when the values are statically configured.

V1AgentRequest

Configuration for an agent: the natural-language instructions and options that tell the extraction pipeline what to pull out of the project’s documents.

Used as the request body for POST /agents/ (creating a new agent) and PATCH /agents/{agent_id}/ (updating one). On PATCH, only the fields you supply are changed; omitted fields are left untouched. dimensions is special: omit it to leave the existing dimensions in place, or pass an empty array to remove them all.

Successful responses return the full agent representation (including server-managed fields such as id, created_at, and extraction_status); see the response schema for that endpoint for the exact shape.

Name Required Type Description
name Yes string Human-readable name shown for the agent (e.g. “Contract value”).
extraction_instructions Yes string Natural-language instructions describing what the agent should extract from each document.
value_type No ValueTypeF41Enum Type of value the agent produces.
unit No string Optional unit for numeric values (e.g. USD, %, kg). Used to normalise extracted values into a consistent unit and for display.
examples No string Free-form examples of expected values, used to steer the agent towards the right kind of answer.
inconsistency_instructions No string Custom instructions for inconsistency checking. If empty, default instructions will be used.
resolution_instructions No string Custom instructions for entity resolution. If empty, default instructions will be used.
enable_complex_calculations_in_resolution No boolean Enable advanced computational analysis for complex resolution tasks involving calculations or data transformations.
enable_web_search No boolean Enable web search to supplement extraction results with data from the web.
dimensions No array<V1AgentDimensionRequest> Dimensions to configure on the agent, in declaration order. Each entry attaches an existing project dimension to the agent and configures its values. Omit to create the agent with no dimensions; on update, omit to leave existing dimensions untouched and pass an empty array to remove them all.

ValueTypeF41Enum

Type: string. One of:

  • string
  • number