Impact Levels

Every agent action is classified into an impact level that determines how it executes. Higher-impact operations require progressively more explicit confirmation. This graduated safety model ensures that the agent can be used freely for exploration and analysis while preventing accidental modifications to live data.

The read impact level covers the vast majority of agent interactions. Searching documents, inspecting extraction results, browsing the field registry, and checking job status all execute instantly with no side effects. These read operations give you a fast way to explore your workspace without navigating through multiple pages.

The draft_mutation level is used when the agent creates or modifies schemas. Because all schema changes go through the workshop system, the agent can freely draft schemas without risk — nothing goes live until you explicitly review and publish. This makes the agent especially useful for rapid schema prototyping: describe the fields you need in plain language, and the agent creates a draft you can refine.

The live_mutation and irreversible levels provide escalating safety gates for operations that affect production data. A live_mutation — such as triggering a job run or publishing a schema — presents a confirmation dialog that you must accept. An irreversible action — such as deleting a source or purging documents — requires you to type a confirmation keyword (e.g., "DELETE") to proceed, preventing accidental data loss.

Common Actions by Impact Level

• read — "Show me the fields in this document", "What schemas do I have?", "How many invoices were processed today?"
• draft_mutation — "Create a schema for invoices with these fields", "Add a 'due date' field to my schema draft"
• live_mutation — "Publish this schema draft", "Run extraction on these 50 documents"
• irreversible — "Delete this source and all its documents", "Purge all data for this document type"

The impact level system also respects your team role. Team members with the Viewer role can only trigger read level actions through the agent — attempting commands that would modify data will be rejected with a clear permissions error. Members, Admins, and Owners can trigger higher impact levels according to their role permissions.

When the agent classifies a message as a command rather than a question, it evaluates the impact level before executing. The classification happens transparently — you see which impact level was assigned and what action the agent intends to take before any confirmation is requested. This transparency lets you understand exactly what will happen and make an informed decision about whether to proceed. If the agent misclassifies a question as a command, you can simply decline the confirmation and rephrase your request.

Impact Levels and API Operations

The impact level system mirrors the permission model of the REST API. Read-level agent actions correspond to GET requests, draft mutations correspond to POST/PATCH operations on draft resources, and live mutations correspond to POST operations that affect published schemas or trigger job runs. When building automations that combine the agent with API calls, keep this mapping in mind — the same permission boundaries apply regardless of the interface you use.

For example, when the agent creates a schema draft, it internally calls the same endpoint as the API. You can subsequently retrieve or modify that draft through the API if you prefer. This interoperability means you can start exploring in the agent, then switch to the API for scripted workflows without losing any work. Draft schemas created by the agent appear in the same list as drafts created through the UI or API.

curl "https://api.talonic.com/v1/schemas?status=draft" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

{
  "data": [
    {
      "id": "sch_draft_001",
      "name": "Purchase Order - Draft",
      "status": "draft",
      "fields_count": 8,
      "created_by": "agent",
      "created_at": "2026-05-07T09:15:00Z"
    }
  ],
  "meta": { "total": 3 }
}