Workflow assessment API¶

Submit a workflow as connected steps and retrieve obligations for each step in one combined JSON response. Workflow components do not appear in standalone Agents or consume standalone-agent slots.

For a complete submission → polling → results → v2 walkthrough, see Generate obligations for every workflow step.

Authentication¶

Use your key from Eli → Settings → API access in X-API-Key. Your account and primary organisation membership must be active. Base URL: https://app.carveragents.ai/api/v1/eli.

Submit a workflow¶

Send a full JSON snapshot with Idempotency-Key. The following example is fictional; replace its facts with your actual deployment context.

{
  "schema_version": "1.0",
  "base_version": 0,
  "workflow": {
    "client_ref": "patient-follow-up",
    "name": "Patient follow-up",
    "description": "Prepare follow-up communications after appointments.",
    "context": {
      "jurisdictions": ["GB"],
      "sector": "healthcare",
      "data_categories": ["health_information"]
    },
    "steps": [
      {
        "id": "prepare-message",
        "name": "Prepare message",
        "description": "Draft a follow-up for clinical staff review.",
        "system_prompt": "Draft a message using the appointment record. Do not send it.",
        "tools": ["read_appointment", "draft_message"],
        "next": ["send-message"]
      },
      {
        "id": "send-message",
        "name": "Send message",
        "description": "Send the approved message to the patient.",
        "tools": ["send_message"],
        "next": []
      }
    ]
  }
}

Save as workflow.json, set ELI_API_KEY in your environment, then submit:

curl --fail-with-body -X POST \
  -H "X-API-Key: $ELI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: patient-follow-up-initial-v1' \
  --data-binary @workflow.json \
  'https://app.carveragents.ai/api/v1/eli/workflows'

The response is 202 and includes workflow_id, assessment_id, version, status, complete, completed_steps, total_steps, and components. Preparation and assessment continue asynchronously. We assess supplied descriptions; we do not execute your steps or tools.

Step IDs must remain stable across revisions. They may contain letters, numbers, underscores, and hyphens, up to 100 characters. Each step requires a name and a nonblank description or system prompt. IDs must be unique and next references must resolve. Branches, cycles, and independent components are supported. Array order is presentation order, not identity.

Unknown schema fields are rejected. Maximum request size is 2 MB; descriptions and system prompts are limited to 30,000 characters each per step. The schema permits at most 100 steps, subject to your organisation allowance. Provide business context explicitly; missing facts remain uncertain.

Routes¶

Method	Route relative to base	Purpose
GET	`/workflows`	Workflows, progress, and current allowances
POST	`/workflows`	Create and assess an initial snapshot
GET	`/workflows/{id}`	Latest snapshot, selected assessment, version history
GET	`/workflows/{id}?version=1`	A particular historical snapshot
POST	`/workflows/{id}/assessments`	Submit a revised full snapshot
GET	`/workflow-assessments/{assessment_id}`	Progress of one exact submission
GET	`/workflow-assessments/{assessment_id}/result`	Combined per-step results, including explicitly partial results
POST	`/workflow-assessments/{assessment_id}/retry`	Retry a failed/stalled step using `{ "component_id": "send-message" }`
GET	`/workflows/{id}/components/{step_id}/obligations?version=1`	One step’s assessment and obligation list

All IDs except customer step IDs are UUIDs. Other organisations’ IDs return 404. Results include each component’s internal agent_id and description version for traceability; use Workflow routes to read those components, not the standalone /agents routes.

Results and failures¶

Poll progress until complete: true or action is needed. Statuses are queued, processing, completed, failed, needs_input, and stalled. A run becomes complete only after every required component succeeds. If one fails, successful component results remain readable and you can retry the failing component. Work without progress for 30 minutes is reported as stalled.

The combined result contains components[], each with its own status, assessment, obligations, and coverage. Partial results are returned with complete: false. A completed run can still have partial legal coverage; inspect component coverage before treating a result as exhaustive. Obligation totals are associations with steps: the same legal duty may occur on several steps.

Each Workflow version pins its component description versions. Accepted results are preserved as historical artifacts. A later description update does not rewrite them. Assessing separate steps is not a guarantee of exhaustive analysis of all cross-step interactions.

Revisions and retries¶

To revise, use the same client_ref, set base_version to the latest Workflow version, and POST the complete body to /workflows/{id}/assessments with a new Idempotency-Key. This creates a new version and reassesses every step. Changed prompts are assessed only after explicit submission.

Repeat the same key and body to recover an accepted submission after a network interruption. Reusing a key with different input or submitting an obsolete base version returns 409. Idempotency keys are scoped to your organisation; use unique keys across workflow operations.

Allowances¶

Default Free allowance: one Workflow with up to 20 steps, separate from the standalone-agent allowance. Paid defaults: 100 Workflows and 100 steps per Workflow. Workflow submissions are limited to 24 per organisation per day by default. Administrators can configure organisation allowances. Scope limits on acts/obligations apply per component. Successful account approval does not remove assessment limits.

Errors¶

401 means authentication is missing or invalid; 403 means account/membership access is unavailable; 404 means a Workflow, assessment, or component is unavailable in your organisation. 402 indicates an allowance is exceeded, 409 a version/idempotency/retry conflict, 413 oversized JSON, 422 invalid input, and 429 a submission/retry limit.

Mixed releases¶

The following routes require organisation review access. They are available at both the customer-key base and the Eli bearer-session base /api/v2/eli:

Method	Route	Purpose
GET	`/release-portfolio`	Separate standalone agents and Workflows, with per-component review states
GET	`/releases`	Organisation release batches
POST	`/releases`	Pin named standalone and Workflow versions; Release manager only
GET	`/releases/{release_id}`	Exact scope, readiness, stale-version detection, and sign-off record
POST	`/releases/{release_id}/signoff`	Final sign-off after every included component passes review; Release manager only

Create body: { "name": "Patient follow-up release", "agent_version_ids": [], "workflow_version_ids": ["WORKFLOW_VERSION_UUID"] }. The Workflow version UUID is its assessment_id. Select one version per standalone agent or Workflow. At least one scope item is required.

Workflow components use the existing versioned review endpoints at /api/v2/agent-compliance/workflow/agents/{agent_id}/..., with the same Legal/Engineering/Release roles and evidence gates as standalone agents. Their review listing includes workflow_context and version-level is_current. Component description edits go through parent Workflow submission. Final release sign-off returns 409 if an item is outdated or not ready; it does not automatically advance component reviews.

Customer metadata¶

Both workflow.metadata and workflow.steps[].metadata accept optional JSON objects. Their values may contain free-form text, Markdown, lists, nested objects, numbers, booleans, or null. They count toward the existing 2 MB request limit and are preserved with the exact Workflow version.

For each step, shared workflow metadata is merged with that step’s metadata and placed in the existing mapper metadata field. Step values override workflow values for duplicate keys. This is a shallow merge: an overriding nested value replaces that value as a whole; its contents are not rewritten or deep-merged.

Example submission fragment (include the other required Workflow/step fields):

{
  "workflow": {
    "metadata": { "source": "Interactly", "region": "GB", "notes": "Shared context" },
    "steps": [
      {
        "id": "prepare-message",
        "metadata": { "source": "CRM export", "owner_team": "Clinic operations" }
      }
    ]
  }
}

For that step, the mapper receives its ordinary prepared description/facts in input and this existing metadata field:

{
  "metadata": {
    "source": "CRM export",
    "region": "GB",
    "notes": "Shared context",
    "owner_team": "Clinic operations"
  }
}

The /twin routes, envelope, routing identities, and contract version are unchanged. No workflow/step metadata wrappers or system routing keys are injected. Workflow identity and step association remain in our internal records. Other metadata conventions on ordinary funnel agents are unchanged.

Metadata is preserved from the exact submitted Workflow version, including for historical reads and retries. Missing metadata behaves as an empty object. Metadata is passed separately rather than being folded into or inferred as structured description facts.