> ## Documentation Index > Fetch the complete documentation index at: https://docs.zapier.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or update the declared intent for a workflow version > Upserts the natural-language intent for one workflow version. One row per version: a second call for the same version replaces the stored text, and a call for a different version records a separate intent. Agentic Management modes read the intent of the version their event batch ran on when they judge whether a proposed change still serves what the workflow is for. Omit `workflow_version_id` to write against the workflow's current published version. ## OpenAPI ````yaml /api-reference/specs/agentic-management.yaml put /agentic-management/v0/{workflow_id}/intent openapi: 3.1.0 info: title: Agentic Management description: >- Agentic Management for a next-gen Zap workflow — turn management on or off, read and update its modes and approval policy, list the runs it has taken, and record the owner-declared intent a version exists to serve. version: 1.0.0 contact: url: https://docs.zapier.com servers: - url: https://api.zapier.com description: Production security: - OAuth: [] tags: - name: Automations description: Background automation lifecycle and run management - name: Harness description: >- The agent-harness platform surface. Operations carrying this tag form the consumable slice the `@zapier/agent-harness-client` is generated from (chats / turns / tool-call resolution / events / files / model discovery). It is an additive selector layered on top of the functional tags (Chats, FS, Models, …): an operation keeps its functional tag for docs grouping and adds `Harness` to opt into tag-scoped client generation. Platform-management operations (VFS/Items/Spaces/Inbox/Automations/usage/ admin/MCP) deliberately do NOT carry this tag. One deliberate exception: the Agentic Management operations, which AGBR-1203 turned into an external contract consumed by Workflow Manager. They keep their `Automations` / `Agentic Management` functional tag and add `Harness` so Workflow Manager consumes one generated SDK for the whole flow rather than a generated client for the chat half and hand-rolled calls for the Agentic Management half. This exception is scoped to Agentic Management — the rest of the `Automations` surface is still excluded. Note that `v0_get_agma_activity` is excluded even within Agentic Management: it returns `InboxItemResponse`, and inbox items are a Sidekick implementation detail that must not enter a published package (AGBR-1206). paths: /agentic-management/v0/{workflow_id}/intent: put: tags: - Automations - Harness summary: Create or update the declared intent for a workflow version description: >- Upserts the natural-language intent for one workflow version. One row per version: a second call for the same version replaces the stored text, and a call for a different version records a separate intent. Agentic Management modes read the intent of the version their event batch ran on when they judge whether a proposed change still serves what the workflow is for. Omit `workflow_version_id` to write against the workflow's current published version. operationId: updateAgenticManagementIntent parameters: - name: workflow_id in: path required: true schema: type: string format: uuid description: Workflow ID to write intent for. - name: workflow_version_id in: query required: false schema: type: string format: uuid description: >- The workflow version the intent describes. Intent belongs to one immutable version, not to the workflow as a whole. When omitted, the workflow's current published version is used, and the response reports which version was written. A version that belongs to a different workflow returns 404, as does a workflow with nothing published: there is no version to attach the text to. requestBody: required: true content: application/json: examples: declare_intent: summary: Record what this workflow version is for value: intent: >- When Stripe reports a new charge, add one row to the finance sheet with the amount, the customer email, and the charge date. Never write a row twice for the same charge. schema: type: object required: - intent properties: intent: type: string minLength: 1 maxLength: 8000 description: >- What this version of the workflow is for, in the owner's own terms: the outcome it exists to produce, the trigger it responds to, and any constraint that must hold. Plain prose, not code. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AgenticManagementIntentResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorsResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorsResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorsResponse' '404': description: >- Not Found — the workflow has no published version to attach intent to, or the requested version does not belong to it content: application/json: schema: $ref: '#/components/schemas/ErrorsResponse' '429': description: >- Too Many Requests — the per-user rate limit for `/api/v0/agma/{workflow_id}/intent` was exceeded. This budget is shared with the GET operation on the same path. content: application/json: schema: $ref: '#/components/schemas/ErrorsResponse' '503': description: >- Service Unavailable — Agentic Management availability could not be determined, because the account's Next Gen Zaps entitlement could not be resolved. A feature flag cannot produce this status: a flag backend outage resolves to the flag's registered default, which is a definite answer. Nothing was read or changed, and the same request is safe to retry. Distinct from `403`, which is a definite answer that this account cannot use Agentic Management. content: application/json: schema: $ref: '#/components/schemas/ErrorsResponse' components: schemas: AgenticManagementIntentResponse: type: object required: - workflow_id - workflow_version_id - intent properties: workflow_id: type: string format: uuid description: The workflow the intent belongs to. workflow_version_id: type: string format: uuid nullable: true description: >- The workflow version this read or write targeted, so a caller that omitted the parameter learns which version answered. `null` only on a read of a workflow that has nothing published yet. intent: type: string nullable: true description: >- The intent recorded against this version, or `null` when this version has none. Intent is never carried over from another version: text recorded against one version never answers a read of another. updated_at: type: string format: date-time nullable: true description: When the intent was last written; `null` when never captured. ErrorsResponse: type: object properties: errors: description: A collection of the errors returned. type: array items: $ref: '#/components/schemas/ErrorObject' required: - errors description: | A JSON:API error response document containing an array of error objects. ErrorObject: type: object properties: id: description: A unique identifier for a specific instance of an error oneOf: - type: 'null' - type: string format: uuid description: > A unique identifier for this particular occurrence of the problem. links: description: Relevant links about the error oneOf: - type: 'null' - type: object properties: about: type: string format: uri description: > A link that leads to further details about this particular occurrence of the problem. additionalProperties: false status: type: string description: > The HTTP status code applicable to this problem, expressed as a string value. code: $ref: '#/components/schemas/ErrorCode' title: type: string description: > A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. detail: type: string description: > A human-readable explanation specific to this occurrence of the problem. Like `title`, this field's value can be localized. source: $ref: '#/components/schemas/ErrorSource' meta: description: | Optional structured metadata specific to the error code. For `cap-exceeded` this matches the `CapExceededMeta` schema; for `stale-version` it matches the `StaleVersionMeta` schema; for `queue-full` it matches the `QueueFullMeta` schema. oneOf: - type: 'null' - $ref: '#/components/schemas/CapExceededMeta' - $ref: '#/components/schemas/StaleVersionMeta' - $ref: '#/components/schemas/QueueFullMeta' - type: object additionalProperties: true additionalProperties: false required: [] description: > An error object provides additional information about problems encountered while performing an operation. Error objects MUST be returned as an array keyed by `errors` in the top level of a JSON:API document. ErrorCode: type: string enum: - bad-request - unauthorized - forbidden - not-found - conflict - payload-too-large - unprocessable-entity - unexpected-error - unsupported-extension - not-executable-shape - describe-failed - bundling-failed - sandbox-runtime-error - component-not-executable - execution-permission-denied - cap-exceeded - failed-dependency - stale-version - gone - service-unavailable - queue-full - event-stream-capacity - chat-too-large - chat-awaiting-approval - approval-attempt-mismatch - approval-generation-stale - approval-attempt-conflict description: > An application-specific error code, expressed as a string value. Error codes: - `bad-request`: Malformed request - `unauthorized`: Authentication required - `forbidden`: Permission denied - `not-found`: Resource not found - `conflict`: Resource conflict - `payload-too-large`: Request payload exceeds the allowed size - `unprocessable-entity`: Validation failed - `unexpected-error`: Internal server error - `unsupported-extension`: File extension not supported for execution - `not-executable-shape`: File structure not compatible with execution - `describe-failed`: Tool describe() method failed - `bundling-failed`: Code bundling failed - `sandbox-runtime-error`: Runtime execution error - `component-not-executable`: Component file requires render, not execute - `execution-permission-denied`: User lacks execute permission - `cap-exceeded`: Per-user usage cap exceeded; details in `meta` - `failed-dependency`: Required upstream prerequisite is unavailable - `stale-version`: Write rejected because the resource's head version no longer matches the caller's `expected_version`; details in `meta` - `gone`: Resource permanently removed or no longer accepting events - `service-unavailable`: A required backing service is unavailable or not configured - `queue-full`: The chat's queued-message backlog is at its per-chat depth cap; wait for the active turn to finish (which drains the queue), then retry - `event-stream-capacity`: Too many concurrent event streams for this user; close one or retry shortly. Not a usage cap - `chat-too-large`: The chat holds too many events for the requested operation to copy. Retrying cannot succeed - `chat-awaiting-approval`: The named message waits on a tool approval, so a copy of it cannot carry the tool's outcome. Answer the approval in the source chat first - `approval-attempt-mismatch`: The idempotency key was already accepted with a different decision or request body - `approval-generation-stale`: The request refers to a permission generation that is no longer current - `approval-attempt-conflict`: Another idempotency key already claimed this permission generation ErrorSource: description: > Identifies the source of the error within the request payload, if relevant. oneOf: - type: 'null' - type: object properties: pointer: type: string description: > A JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the associated entity in the request document [e.g. `/data` for a primary data object, or `/data/attributes/title` for a specific attribute]. parameter: type: string description: | A string indicating which URI query parameter caused the error. header: type: string description: | A string indicating the header that caused the error. additionalProperties: false CapExceededMeta: type: object description: | Structured metadata returned in the 429 `cap-exceeded` error response. Identifies which usage cap was hit, current usage, the cap's nominal value (soft cap, not hard cap × grace), and when the bucket resets. required: - cap - used - cap_value - reset_at properties: cap: type: string enum: - messages_per_day - tool_calls_per_day - cost_per_day - cost_per_month - cost_burst - automation_runs_per_hour description: | Which cap was hit. Closed enum so clients can dispatch on this without a translation table. used: type: number description: | Counter or USD value at the moment of rejection. Integer for count caps, USD float for cost caps. cap_value: type: number description: | Soft cap value (the cap before the 10% grace buffer). For cost caps, in USD. reset_at: type: string format: date-time description: | When the bucket clears. Daily caps reset at the next UTC midnight, monthly at the first of the next UTC month, burst at the next 5-minute window boundary. additionalProperties: false StaleVersionMeta: type: object description: | Structured metadata returned in the 409 `stale-version` error response. Lets clients reconcile their cached view of a file against the server's current head version without re-fetching the full content first. required: - current_version - expected_version properties: current_version: type: integer description: | The resource's head version at the moment the write was rejected. Clients can re-read the resource at this version (or higher) to reconcile, then retry the write with an updated `expected_version`. expected_version: type: integer description: | The `expected_version` value the client supplied, echoed back so clients can detect duplicate or out-of-order failure handling. additionalProperties: false QueueFullMeta: type: object description: > Structured metadata returned in the 429 `queue-full` error response. Reports the chat's queued-message backlog at the moment of rejection and the per-chat depth cap it hit. Unlike `CapExceededMeta`, there is no `reset_at`: the limit is structural, not time-based — the backlog drains when the active turn finishes, so a retry is gated on chat state, not a clock. required: - queue_depth - limit properties: queue_depth: type: number description: > Number of `queued` messages the chat held at the moment of rejection. limit: type: number description: | The per-chat queued-message depth cap that was hit. additionalProperties: false securitySchemes: OAuth: type: oauth2 description: OAuth 2.0 authentication. flows: authorizationCode: authorizationUrl: https://zapier.com/oauth/authorize tokenUrl: https://zapier.com/oauth/token scopes: {} clientCredentials: tokenUrl: https://zapier.com/oauth/token scopes: {} ````