<%= @presentation["title"] %>

<%= @presentation["description"] %>

<%= @presentation["message"] %>

<%= for option <- @presentation["options"] || [] do %> <% end %>

<%= @presentation["message"] %>

<%= @field["label"] %> <%= if @field["required"], do: "*" %> <%= case @field["type"] do %> <% "string" -> %> <%= if @field["multiline"] do %> <% else %> <% end %> <% "number" -> %> <% "boolean" -> %> <% "select" -> %> <% "date" -> %> <% _ -> %> <% end %>

Workflow: <%= @instance["workflow_name"] %>

Status: <%= @instance["status"] %>

Current State: <%= @instance["current_state"] %>

<%= if @instance["status"] == "halted" do %> <.workflow_form presentation={@instance["halting_presentation"]} form={@form} /> <% end %> <%= if @instance["status"] in ["running", "halted"] do %> <% end %>

{ return this.client.request('POST', '/workflows', definition); } async validateWorkflow(definition: WorkflowDefinition): Promise { return this.client.request('POST', '/workflows/validate', definition); } async listWorkflows(): Promise { const result = await this.client.request<{ workflows: Workflow[] }>('GET', '/workflows'); return result.workflows; } async listVersions(workflowName: string): Promise { const result = await this.client.request<{ versions: WorkflowVersion[] }>( 'GET', `/workflows/${workflowName}/versions` ); return result.versions; } async publishVersion(workflowName: string, versionId: string): Promise { return this.client.request( 'POST', `/workflows/${workflowName}/versions/${versionId}/publish` ); } // ============ Instances ============ async createInstance( workflowName: string, userId: string, input: Record ): Promise { return this.client.request('POST', `/workflows/${workflowName}/instances`, { namespace: `user_${userId}`, input }); } async getInstance(instanceId: string): Promise { return this.client.request('GET', `/workflows/instances/${instanceId}`); } async listInstances(filters?: { userId?: string; workflowName?: string; status?: InstanceStatus; }): Promise { const params = new URLSearchParams(); if (filters?.userId) params.set('namespace', `user_${filters.userId}`); if (filters?.workflowName) params.set('workflow_name', filters.workflowName); if (filters?.status) params.set('status', filters.status); const query = params.toString(); const result = await this.client.request<{ instances: WorkflowInstance[] }>( 'GET', `/workflows/instances${query ? '?' + query : ''}` ); return result.instances; } async resumeInstance( instanceId: string, input: Record ): Promise { return this.client.request('POST', `/workflows/instances/${instanceId}/resume`, { input }); } async cancelInstance(instanceId: string): Promise { await this.client.request('POST', `/workflows/instances/${instanceId}/cancel`); } // ============ Threads ============ async listThreads(instanceId: string): Promise { const result = await this.client.request<{ threads: WorkflowThread[] }>( 'GET', `/workflows/instances/${instanceId}/threads` ); return result.threads; } async resumeThread( instanceId: string, threadId: string, input: Record ): Promise { return this.client.request( 'POST', `/workflows/instances/${instanceId}/threads/${threadId}/resume`, { input } ); } // ============ Helpers ============ async waitForCompletion( instanceId: string, timeoutMs: number = 300000, pollIntervalMs: number = 2000 ): Promise { const startTime = Date.now(); while (Date.now() - startTime < timeoutMs) { const instance = await this.getInstance(instanceId); if (instance.status === 'completed') { return instance; } if (instance.status === 'failed') { throw new Error(`Workflow failed: ${instance.error}`); } if (instance.status === 'cancelled') { throw new Error('Workflow was cancelled'); } if (instance.status === 'halted') { // Workflow is waiting for input return instance; } await new Promise(resolve => setTimeout(resolve, pollIntervalMs)); } throw new Error('Workflow completion timed out'); } } // Types interface WorkflowDefinition { name: string; initial_state: string; ai_guidance?: string; states: Record; } interface StateDefinition { type: 'action' | 'halting' | 'terminal'; logic?: LogicDefinition; presentation?: PresentationDefinition; transitions?: TransitionDefinition[]; on_enter?: LogicDefinition; // Optional - verify availability with your Interactor version } interface LogicDefinition { type: 'script' | 'http'; code?: string; // For script type method?: string; // For http type url?: string; // For http type headers?: Record; // For http type body?: any; // For http type timeout?: number; // Optional - for http type retry?: { attempts: number; backoff: 'exponential' | 'linear' }; // Optional - for http type } interface PresentationDefinition { type: 'form' | 'choice' | 'message'; title?: string; // Optional - for better UX description?: string; // Optional - for better UX message?: string; // For choice and message types fields?: FieldDefinition[]; // For form type options?: OptionDefinition[]; // For choice type show_progress?: boolean; // Optional - for message type (UI hint) } interface FieldDefinition { name: string; type: 'string' | 'number' | 'boolean' | 'select' | 'date' | 'file'; label: string; required?: boolean; default?: any; // String type properties multiline?: boolean; placeholder?: string; maxLength?: number; // Number type properties min?: number; max?: number; step?: number; // Select type properties options?: OptionDefinition[]; // Date type properties minDate?: string; maxDate?: string; // File type properties accept?: string; maxSize?: number; } interface OptionDefinition { value: string; label: string; description?: string; } interface TransitionDefinition { target: string; condition?: ConditionDefinition; } interface ConditionDefinition { field?: string; operator?: 'equals' | 'not_equals' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'in'; equals?: any; not_equals?: any; value?: any; and?: ConditionDefinition[]; or?: ConditionDefinition[]; } interface Workflow { name: string; latest_version_id: string; published_version_id?: string; created_at: string; } interface WorkflowVersion { version_id: string; status: 'draft' | 'published'; created_at: string; published_at?: string; } interface ValidationResult { valid: boolean; errors?: Array<{ path: string; message: string }>; } type InstanceStatus = 'running' | 'halted' | 'completed' | 'failed' | 'cancelled'; interface WorkflowInstance { id: string; workflow_name: string; version_id: string; namespace: string; status: InstanceStatus; current_state: string; workflow_data: Record; halting_presentation?: PresentationDefinition; threads: WorkflowThread[]; history: HistoryEntry[]; error?: string; created_at: string; } interface WorkflowThread { id: string; status: 'running' | 'halted' | 'completed'; current_state: string; } interface HistoryEntry { state: string; entered_at: string; exited_at?: string; transition?: string; } ``` ### Usage Example ```typescript const workflowManager = new WorkflowManager(interactorClient); // Create and publish a workflow const version = await workflowManager.createWorkflow(purchaseApprovalDefinition); await workflowManager.publishVersion('purchase_approval', version.version_id); // Start a new instance const instance = await workflowManager.createInstance( 'purchase_approval', 'user_123', { id: 'PO-2026-001', amount: 5500, requester: 'john@example.com', description: 'Development laptop' } ); console.log(`Workflow started: ${instance.id}`); console.log(`Current state: ${instance.current_state}`); console.log(`Status: ${instance.status}`); if (instance.status === 'halted') { console.log('Waiting for approval...'); console.log('Presentation:', instance.halting_presentation); // Simulate manager approval const resumed = await workflowManager.resumeInstance(instance.id, { approved: true, comment: 'Approved for Q1 budget' }); console.log(`New status: ${resumed.status}`); console.log(`New state: ${resumed.current_state}`); } ``` --- ## Error Handling ### Workflow-Specific Errors Common workflow errors and their resolutions: | Error Code | HTTP Status | Description | Resolution | |------------|-------------|-------------|------------| | `workflow_not_found` | 404 | Workflow definition doesn't exist | Check workflow name | | `workflow_not_published` | 400 | No published version available | Publish a version first | | `version_not_found` | 404 | Version doesn't exist | Check version ID | | `instance_not_found` | 404 | Instance doesn't exist | Check instance ID | | `instance_not_halted` | 400 | Cannot resume - not halted | Check instance status | | `invalid_transition` | 400 | Input doesn't match any condition | Check transition conditions | | `script_error` | 500 | Error executing workflow script | Check script syntax | | `http_error` | 500 | HTTP action failed | Check endpoint and auth | > **See Also**: The [API Reference](#api-reference) section contains the complete canonical error table with all endpoint-specific error codes. --- ## Webhook Events & Subscription Management ### Available Events | Event | Description | Triggered When | |-------|-------------|----------------| | `workflow.instance.created` | New instance started | Instance created via API | | `workflow.instance.halted` | Waiting for input | Instance reaches halting state | | `workflow.instance.resumed` | Instance resumed | Resume called with input | | `workflow.instance.completed` | Finished successfully | Instance reaches terminal state | | `workflow.instance.failed` | Terminated with error | Script/HTTP error or invalid transition | | `workflow.instance.cancelled` | Manually cancelled | Cancel endpoint called | ### Create Webhook Subscription ```bash curl -X POST https://core.interactor.com/api/v1/webhooks/subscriptions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "url": "https://yourapp.com/api/webhooks/workflows", "events": [ "workflow.instance.halted", "workflow.instance.completed", "workflow.instance.failed" ], "secret": "whsec_your_webhook_secret_min_32_chars", "namespace_filter": "user_123" }' ``` **Response:** ```json { "data": { "id": "whsub_abc123", "url": "https://yourapp.com/api/webhooks/workflows", "events": ["workflow.instance.halted", "workflow.instance.completed", "workflow.instance.failed"], "namespace_filter": "user_123", "status": "active", "created_at": "2026-01-20T12:00:00Z" } } ``` ### List Webhook Subscriptions ```bash curl https://core.interactor.com/api/v1/webhooks/subscriptions \ -H "Authorization: Bearer " ``` ### Delete Webhook Subscription ```bash curl -X DELETE https://core.interactor.com/api/v1/webhooks/subscriptions/whsub_abc123 \ -H "Authorization: Bearer " ``` ### Webhook Delivery Headers Every webhook delivery includes these headers: | Header | Description | Example | |--------|-------------|---------| | `X-Interactor-Event` | Event type | `workflow.instance.halted` | | `X-Interactor-Signature` | HMAC-SHA256 signature | `sha256=abc123...` | | `X-Interactor-Delivery` | Unique delivery ID | `del_01F8B6XY...` | | `X-Interactor-Timestamp` | Unix timestamp | `1705752000` | | `X-Interactor-Retry-Count` | Retry attempt (0-based) | `0` | | `Content-Type` | Always JSON | `application/json` | ### Webhook Payload Example (`workflow.instance.halted`) ```json { "event": "workflow.instance.halted", "delivery_id": "del_01F8B6XY...", "timestamp": "2026-01-20T12:00:01Z", "data": { "instance_id": "inst_xyz", "workflow_name": "approval_workflow", "version_id": "v_abc123", "namespace": "user_123", "current_state": "await_approval", "workflow_data": { "request_id": "req_456", "amount": 5000, "status": "pending" }, "halting_presentation": { "type": "form", "title": "Approval Required", "fields": [ {"name": "approved", "type": "boolean", "label": "Approve this request?"}, {"name": "comment", "type": "string", "label": "Comment"} ] } } } ``` ### Webhook Payload Example (`workflow.instance.completed`) ```json { "event": "workflow.instance.completed", "delivery_id": "del_02G9C7ZW...", "timestamp": "2026-01-20T12:05:00Z", "data": { "instance_id": "inst_xyz", "workflow_name": "approval_workflow", "version_id": "v_abc123", "namespace": "user_123", "current_state": "approved", "workflow_data": { "request_id": "req_456", "amount": 5000, "status": "approved", "approved_at": "2026-01-20T12:05:00Z" } } } ``` ### Webhook Signature Verification **Always verify webhook signatures** to ensure requests are from Interactor. **Node.js/TypeScript:** ```typescript import crypto from 'crypto'; function verifyWebhookSignature( payload: string | Buffer, signature: string, secret: string, timestamp: string ): boolean { // Protect against replay attacks (reject if older than 5 minutes) const timestampAge = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10); if (timestampAge > 300) { return false; } // Compute expected signature const signedPayload = `${timestamp}.${payload}`; const expectedSignature = 'sha256=' + crypto .createHmac('sha256', secret) .update(signedPayload) .digest('hex'); // Constant-time comparison to prevent timing attacks return crypto.timingSafeEqual( Buffer.from(expectedSignature), Buffer.from(signature) ); } // Express middleware example app.post('/webhooks/workflows', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.headers['x-interactor-signature'] as string; const timestamp = req.headers['x-interactor-timestamp'] as string; if (!verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET!, timestamp)) { return res.status(401).json({ error: 'Invalid signature' }); } const event = JSON.parse(req.body.toString()); // Process event... res.status(200).json({ received: true }); }); ``` **Elixir/Phoenix:** ```elixir defmodule MyAppWeb.WebhookController do use MyAppWeb, :controller @webhook_secret Application.compile_env(:my_app, :webhook_secret) @max_age_seconds 300 def handle(conn, _params) do signature = get_req_header(conn, "x-interactor-signature") |> List.first() timestamp = get_req_header(conn, "x-interactor-timestamp") |> List.first() {:ok, body, conn} = read_body(conn) case verify_signature(body, signature, timestamp) do :ok -> event = Jason.decode!(body) process_event(event) json(conn, %{received: true}) {:error, reason} -> conn |> put_status(401) |> json(%{error: reason}) end end defp verify_signature(payload, signature, timestamp) do with :ok <- verify_timestamp(timestamp), :ok <- verify_hmac(payload, signature, timestamp) do :ok end end defp verify_timestamp(timestamp) do timestamp_int = String.to_integer(timestamp) age = System.system_time(:second) - timestamp_int if age <= @max_age_seconds do :ok else {:error, "Timestamp too old"} end end defp verify_hmac(payload, signature, timestamp) do signed_payload = "#{timestamp}.#{payload}" expected = "sha256=" <> Base.encode16( :crypto.mac(:hmac, :sha256, @webhook_secret, signed_payload), case: :lower ) if Plug.Crypto.secure_compare(expected, signature) do :ok else {:error, "Invalid signature"} end end defp process_event(%{"event" => "workflow.instance.halted"} = event) do # Handle halted workflow - notify user, etc. IO.inspect(event, label: "Workflow halted") end defp process_event(%{"event" => "workflow.instance.completed"} = event) do # Handle completed workflow IO.inspect(event, label: "Workflow completed") end defp process_event(event) do IO.inspect(event, label: "Unknown event") end end ``` ### Webhook Retry Policy | Attempt | Delay | Cumulative Time | |---------|-------|-----------------| | 1 | Immediate | 0s | | 2 | 30 seconds | 30s | | 3 | 2 minutes | 2m 30s | | 4 | 8 minutes | 10m 30s | | 5 | 30 minutes | 40m 30s | | 6 | 2 hours | 2h 40m 30s | - Webhooks are retried up to **6 times** with exponential backoff - Return `2xx` status to acknowledge receipt - Non-2xx responses or timeouts (30s) trigger retries - After all retries fail, the event is moved to a dead-letter queue - Use the webhook dashboard to replay failed events See `interactor-webhooks` skill for complete webhook management. --- ## Authentication & Authorization ### Required OAuth Scopes | Scope | Description | Required For | |-------|-------------|--------------| | `workflows:read` | Read workflow definitions and instances | GET endpoints | | `workflows:write` | Create/modify workflows and instances | POST/PUT/DELETE endpoints | | `workflows:execute` | Create and resume instances | Instance operations | | `webhooks:manage` | Manage webhook subscriptions | Webhook endpoints | ### Token Format ```http Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... ``` ### Token Refresh Tokens expire after 1 hour. Refresh before expiry: ```bash curl -X POST https://auth.interactor.com/oauth/token \ -H "Content-Type: application/json" \ -d '{ "grant_type": "refresh_token", "refresh_token": "", "client_id": "" }' ``` ### Namespace Authorization - Instances are isolated by `namespace` - Tokens can only access instances in namespaces they own - Use `user_{user_id}` convention for user-specific workflows - Use `org_{org_id}` convention for organization-wide workflows - Service accounts can access all namespaces within their account See `interactor-auth` skill for complete authentication setup. --- ## Idempotency & Concurrency ### Idempotency Keys Use `Idempotency-Key` header to prevent duplicate operations: ```bash curl -X POST https://core.interactor.com/api/v1/workflows/approval_workflow/instances \ -H "Authorization: Bearer " \ -H "Idempotency-Key: order_123_approval_v1" \ -H "Content-Type: application/json" \ -d '{ "namespace": "user_123", "input": {"order_id": "order_123", "amount": 5000} }' ``` **Behavior:** - If the same `Idempotency-Key` is used within 24 hours, the original response is returned - Keys are scoped to the authenticated account - Use deterministic keys based on business identifiers (e.g., `{order_id}_approval`) **Supported Endpoints:** - `POST /workflows/{name}/instances` (create instance) - `POST /workflows/instances/{id}/resume` (resume instance) - `POST /workflows/instances/{id}/threads/{thread_id}/resume` (resume thread) ### Concurrent Resume Handling When multiple resume requests arrive simultaneously: | Scenario | Behavior | |----------|----------| | Same instance, same input | Second request returns same result (idempotent) | | Same instance, different input | First request wins, second gets `409 Conflict` | | Different threads, same instance | Both processed (parallel execution) | **Conflict Response:** ```json { "error": { "code": "concurrent_modification", "message": "Instance was modified by another request", "details": { "current_state": "approved", "expected_state": "await_approval" }, "request_id": "req_01F8B6..." } } ``` --- ## Limits & Quotas ### Workflow Definition Limits | Limit | Value | Notes | |-------|-------|-------| | Max states per workflow | 100 | Including terminal states | | Max transitions per state | 20 | Evaluated in order | | Max workflow name length | 64 chars | Alphanumeric, underscores, hyphens | | Max script code size | 64 KB | Per script logic block | | Max presentation fields | 50 | Per halting state | | Max workflow definition size | 1 MB | Total JSON size | ### Instance Limits | Limit | Value | Notes | |-------|-------|-------| | Max `workflow_data` size | 256 KB | Accumulated across states | | Max input payload size | 64 KB | Per resume/create call | | Max concurrent threads | 10 | Per instance | | Instance TTL (running) | 30 days | Auto-cancelled after | | Instance TTL (halted) | 90 days | Auto-cancelled after | | Max instances per namespace | 10,000 | Active instances | ### File Upload Limits (for `file` field type) | Limit | Value | |-------|-------| | Max file size | 10 MB | | Allowed MIME types | Configurable per field | | Max files per field | 5 | | File retention | 7 days after instance completion | ### Rate Limits | Endpoint Category | Limit | Window | |-------------------|-------|--------| | Read operations | 1000 req | per minute | | Write operations | 100 req | per minute | | Instance creation | 50 req | per minute | | Webhook deliveries | 1000 events | per minute per subscription | **Rate Limit Headers:** ```http X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1705752060 ``` --- ## Script Execution Environment ### Runtime Specification | Property | Value | |----------|-------| | Runtime | JavaScript (ES2020) | | Engine | QuickJS sandbox | | Execution timeout | 5 seconds | | Memory limit | 16 MB | | Network access | **Disabled** (use HTTP logic instead) | ### Available Globals ```javascript // Available in script context input // Object: Input from create/resume call workflow_data // Object: Accumulated workflow data context // Object: { namespace, instance_id, workflow_name, state_name } // Standard JavaScript JSON // JSON.parse, JSON.stringify Date // Date constructor and methods Math // Math utilities console // console.log (for debugging, logged to instance history) Array // Array methods Object // Object methods String // String methods Number // Number methods Boolean // Boolean type RegExp // Regular expressions // NOT available (for security) fetch // Use HTTP logic instead require // No module imports eval // Disabled Function // Constructor disabled setTimeout // Async not supported setInterval // Async not supported ``` ### Accessing Secrets in Scripts Secrets are accessed via the `secrets` object (read-only): ```javascript // In script logic const apiKey = secrets.MY_API_KEY; return { ...workflow_data, api_key_present: !!apiKey }; ``` > **Security**: Secrets are injected at runtime and never logged. Use HTTP logic for external calls requiring secrets. ### Script Best Practices - Keep scripts simple and fast (<100ms recommended) - Avoid loops over large datasets - Delegate heavy computation to HTTP endpoints - Use `console.log` sparingly (logs are stored in instance history) - Return plain objects (no functions or circular references) --- ## Observability & Tracing ### Correlation IDs Every API request returns a unique request ID: ```http X-Request-Id: req_01F8B6XY9Z... ``` Include this ID when contacting support or debugging issues. ### Propagating Trace Context Pass trace context to correlate across services: ```bash curl -X POST https://core.interactor.com/api/v1/workflows/approval_workflow/instances \ -H "Authorization: Bearer " \ -H "X-Request-Id: your-correlation-id-123" \ -H "traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" ``` The `traceparent` header (W3C Trace Context) is propagated to HTTP logic actions. ### Instance History & Logs Each instance maintains a detailed execution history: ```json { "history": [ { "state": "request", "entered_at": "2026-01-20T12:00:00Z", "exited_at": "2026-01-20T12:00:01Z", "transition": "await_approval", "logs": ["Processing request req_456"], "duration_ms": 45 }, { "state": "await_approval", "entered_at": "2026-01-20T12:00:01Z", "input_received": {"approved": true, "comment": "LGTM"}, "resumed_at": "2026-01-20T12:05:00Z", "resumed_by": "user_789" } ] } ``` ### Metrics Available | Metric | Description | |--------|-------------| | `workflow.instance.created` | Counter: instances created | | `workflow.instance.completed` | Counter: instances completed | | `workflow.instance.failed` | Counter: instances failed | | `workflow.state.duration` | Histogram: time in each state | | `workflow.script.duration` | Histogram: script execution time | | `workflow.http.duration` | Histogram: HTTP action duration | Access metrics via the Interactor dashboard or export to your observability platform. --- ## Best Practices ### DO - **Start simple** - Begin with linear workflows, add complexity as needed - **Use meaningful state names** - `await_manager_approval` over `state_3` - **Validate early** - Use `/validate` endpoint during development - **Version carefully** - Publish new versions rather than modifying existing ones - **Handle all paths** - Ensure every state has a valid transition or is terminal - **Use namespaces** - Isolate workflow instances per user - **Add AI guidance** - Help AI assistants understand your workflow's purpose ### DON'T - **Don't modify published versions** - Create new versions instead - **Don't create orphan states** - Every state should be reachable - **Don't forget error handling** - Add appropriate error states - **Don't use complex scripts** - Keep logic simple, move complexity to HTTP endpoints --- ## Output Format When implementing workflows, provide this summary: ```markdown ## Workflow Implementation Report **Date**: YYYY-MM-DD **Workflow**: purchase_approval ### Definition | Property | Value | |----------|-------| | Name | purchase_approval | | Version | v_abc123 | | Status | Published | | States | 7 | | Halting States | 2 | ### State Flow ``` submit → manager_approval → [vp_approval] → approved → notify → complete ↘ rejected → notify → complete ``` ### Implementation Checklist - [ ] Workflow definition created - [ ] Validation passed - [ ] Version published - [ ] Instance creation tested - [ ] Resume functionality tested - [ ] All transitions verified - [ ] Webhook handlers configured - [ ] Error handling implemented ### Test Scenarios | Scenario | Input | Expected Path | Status | |----------|-------|---------------|--------| | Auto-approve | amount: 500 | submit → auto_approved → complete | ✓ | | Manager only | amount: 5000 | submit → manager → approved → complete | ✓ | | VP required | amount: 15000 | submit → manager → vp → approved → complete | ✓ | | Rejected | amount: 5000, approved: false | submit → manager → rejected → complete | ✓ | ``` --- ## API Reference ### Endpoint Summary | Method | Endpoint | Auth | Success | Description | |--------|----------|------|---------|-------------| | `POST` | `/workflows` | `workflows:write` | `201` | Create workflow definition | | `POST` | `/workflows/validate` | `workflows:read` | `200` | Validate without saving | | `GET` | `/workflows` | `workflows:read` | `200` | List all workflows | | `GET` | `/workflows/{name}/versions` | `workflows:read` | `200` | List workflow versions | | `POST` | `/workflows/{name}/versions/{id}/publish` | `workflows:write` | `200` | Publish a version | | `POST` | `/workflows/{name}/instances` | `workflows:execute` | `201` | Create instance | | `GET` | `/workflows/instances` | `workflows:read` | `200` | List instances | | `GET` | `/workflows/instances/{id}` | `workflows:read` | `200` | Get instance details | | `POST` | `/workflows/instances/{id}/resume` | `workflows:execute` | `200` | Resume halted instance | | `POST` | `/workflows/instances/{id}/cancel` | `workflows:execute` | `200` | Cancel instance | | `GET` | `/workflows/instances/{id}/threads` | `workflows:read` | `200` | List threads | | `POST` | `/workflows/instances/{id}/threads/{tid}/resume` | `workflows:execute` | `200` | Resume thread | | `POST` | `/webhooks/subscriptions` | `webhooks:manage` | `201` | Create webhook | | `GET` | `/webhooks/subscriptions` | `webhooks:manage` | `200` | List webhooks | | `DELETE` | `/webhooks/subscriptions/{id}` | `webhooks:manage` | `204` | Delete webhook | ### Error Response Format All errors follow this standardized format: ```json { "error": { "code": "workflow_not_found", "message": "Workflow 'invalid_workflow' not found", "details": null, "request_id": "req_01F8B6XY9Z..." } } ``` ### Error Codes by Endpoint | Endpoint | Error Code | HTTP | Description | |----------|------------|------|-------------| | All | `unauthorized` | 401 | Missing or invalid token | | All | `forbidden` | 403 | Insufficient scopes | | All | `rate_limited` | 429 | Rate limit exceeded | | All | `internal_error` | 500 | Server error | | `POST /workflows` | `invalid_workflow` | 400 | Schema validation failed | | `POST /workflows` | `workflow_exists` | 409 | Name already taken | | `GET /workflows/{name}/*` | `workflow_not_found` | 404 | Workflow doesn't exist | | `POST /.../publish` | `version_not_found` | 404 | Version doesn't exist | | `POST /.../publish` | `already_published` | 400 | Version already published | | `POST /.../instances` | `workflow_not_published` | 400 | No published version | | `POST /.../instances` | `namespace_quota_exceeded` | 429 | Too many instances | | `GET /instances/{id}` | `instance_not_found` | 404 | Instance doesn't exist | | `POST /.../resume` | `instance_not_halted` | 400 | Instance not in halted state | | `POST /.../resume` | `invalid_transition` | 400 | Input doesn't match conditions | | `POST /.../resume` | `concurrent_modification` | 409 | Race condition | | `POST /.../cancel` | `instance_not_active` | 400 | Already completed/failed | | Script execution | `script_error` | 500 | Runtime error in script | | Script execution | `script_timeout` | 500 | Script exceeded 5s limit | | HTTP logic | `http_error` | 500 | External request failed | | HTTP logic | `http_timeout` | 500 | External request timed out | --- ## React Component Example Render `halting_presentation` in React applications: ```tsx import React from 'react'; interface Field { name: string; type: 'string' | 'number' | 'boolean' | 'select' | 'date' | 'file'; label: string; required?: boolean; default?: any; multiline?: boolean; placeholder?: string; options?: { value: string; label: string }[]; min?: number; max?: number; } interface Option { value: string; label: string; description?: string; } interface Presentation { type: 'form' | 'choice' | 'message'; title?: string; description?: string; message?: string; fields?: Field[]; options?: Option[]; show_progress?: boolean; } interface WorkflowFormProps { presentation: Presentation; onSubmit: (input: Record) => void; onCancel?: () => void; isSubmitting?: boolean; } export function WorkflowForm({ presentation, onSubmit, onCancel, isSubmitting = false }: WorkflowFormProps) { const [formData, setFormData] = React.useState>(() => { // Initialize with defaults const defaults: Record = {}; presentation.fields?.forEach(field => { if (field.default !== undefined) { defaults[field.name] = field.default; } }); return defaults; }); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); onSubmit(formData); }; const handleChoice = (value: string) => { onSubmit({ choice: value }); }; const updateField = (name: string, value: any) => { setFormData(prev => ({ ...prev, [name]: value })); }; return (

{presentation.title && (

{presentation.title}

)} {presentation.description && (

{presentation.description}

)} {presentation.type === 'form' && (

{presentation.fields?.map(field => ( updateField(field.name, value)} /> ))}

{onCancel && ( )}

)} {presentation.type === 'choice' && (

{presentation.message && (

{presentation.message}

)}

{presentation.options?.map(option => ( ))}

)} {presentation.type === 'message' && (

{presentation.message}

{presentation.show_progress && (

)}

); } function FormField({ field, value, onChange }: { field: Field; value: any; onChange: (value: any) => void; }) { const baseInputClass = "w-full border rounded-lg p-2 focus:ring-2 focus:ring-[#4CD964] focus:border-transparent"; return (

{field.label} {field.required && *} {field.type === 'string' && !field.multiline && ( onChange(e.target.value)} placeholder={field.placeholder} required={field.required} className={baseInputClass} /> )} {field.type === 'string' && field.multiline && (

onChange(e.target.value)}
          placeholder={field.placeholder}
          required={field.required}
          rows={4}
          className={baseInputClass}
        />
      )}

{field.type === 'number' && (
        <input
          type="number"
          value={value ?? ''}
          onChange={(e) => onChange(e.target.valueAsNumber)}
          min={field.min}
          max={field.max}
          required={field.required}
          className={baseInputClass}
        />
      )}

{field.type === 'boolean' && (
        <input
          type="checkbox"
          checked={value || false}
          onChange={(e) => onChange(e.target.checked)}
          className="h-5 w-5 text-[#4CD964] rounded focus:ring-[#4CD964]"
        />
      )}

{field.type === 'select' && (
        <select
          value={value || ''}
          onChange={(e) => onChange(e.target.value)}
          required={field.required}
          className={baseInputClass}
        >
          <option value="">Select...</option>
          {field.options?.map(opt => (
            <option key={opt.value} value={opt.value}>{opt.label}</option>
          ))}
        </select>
      )}

{field.type === 'date' && (
        <input
          type="date"
          value={value || ''}
          onChange={(e) => onChange(e.target.value)}
          required={field.required}
          className={baseInputClass}
        />
      )}

{field.type === 'file' && (
        <input
          type="file"
          onChange={(e) => onChange(e.target.files?.[0])}
          required={field.required}
          className={baseInputClass}
        />
      )}
    </div>
  );
}

// Usage example
function ApprovalPage({ instanceId }: { instanceId: string }) {
  const [instance, setInstance] = React.useState<any>(null);
  const [isSubmitting, setIsSubmitting] = React.useState(false);

React.useEffect(() => {
    fetch(`/api/workflows/instances/${instanceId}`)
      .then(res => res.json())
      .then(data => setInstance(data.data));
  }, [instanceId]);

if (!instance) return <div>Loading...</div>;
  if (instance.status !== 'halted') return <div>Workflow not awaiting input</div>;

return (
    <WorkflowForm
      presentation={instance.halting_presentation}
      onSubmit={handleSubmit}
      isSubmitting={isSubmitting}
    />
  );
}
```

---

## JSON Schema Appendix

### Workflow Definition Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://core.interactor.com/schemas/workflow-definition.json",
  "title": "Workflow Definition",
  "type": "object",
  "required": ["name", "initial_state", "states"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_-]{0,63}$",
      "description": "Unique workflow identifier"
    },
    "initial_state": {
      "type": "string",
      "description": "Starting state name"
    },
    "ai_guidance": {
      "type": "string",
      "maxLength": 1000,
      "description": "Instructions for AI assistants"
    },
    "states": {
      "type": "object",
      "additionalProperties": { "$ref": "#/$defs/state" },
      "minProperties": 1,
      "maxProperties": 100
    }
  },
  "$defs": {
    "state": {
      "type": "object",
      "required": ["type"],
      "properties": {
        "type": { "enum": ["action", "halting", "terminal"] },
        "logic": { "$ref": "#/$defs/logic" },
        "presentation": { "$ref": "#/$defs/presentation" },
        "transitions": {
          "type": "array",
          "items": { "$ref": "#/$defs/transition" },
          "maxItems": 20
        },
        "on_enter": {
          "$ref": "#/$defs/logic",
          "description": "Optional (v2.0.0+): Logic to execute when entering this state"
        }
      }
    },
    "logic": {
      "type": "object",
      "required": ["type"],
      "oneOf": [
        {
          "properties": {
            "type": { "const": "script" },
            "code": { "type": "string", "maxLength": 65536 }
          },
          "required": ["type", "code"]
        },
        {
          "properties": {
            "type": { "const": "http" },
            "method": { "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"] },
            "url": { "type": "string", "format": "uri" },
            "headers": { "type": "object" },
            "body": {},
            "timeout": { "type": "integer", "minimum": 1000, "maximum": 30000 },
            "retry": {
              "type": "object",
              "properties": {
                "attempts": { "type": "integer", "minimum": 1, "maximum": 5 },
                "backoff": { "enum": ["linear", "exponential"] }
              }
            }
          },
          "required": ["type", "method", "url"]
        }
      ]
    },
    "presentation": {
      "type": "object",
      "required": ["type"],
      "oneOf": [
        {
          "properties": {
            "type": { "const": "form" },
            "title": { "type": "string" },
            "description": { "type": "string" },
            "fields": {
              "type": "array",
              "items": { "$ref": "#/$defs/field" },
              "maxItems": 50
            }
          },
          "required": ["type", "fields"]
        },
        {
          "properties": {
            "type": { "const": "choice" },
            "title": { "type": "string" },
            "message": { "type": "string" },
            "options": {
              "type": "array",
              "items": { "$ref": "#/$defs/option" },
              "minItems": 2,
              "maxItems": 20
            }
          },
          "required": ["type", "options"]
        },
        {
          "properties": {
            "type": { "const": "message" },
            "title": { "type": "string" },
            "message": { "type": "string" },
            "show_progress": { "type": "boolean" }
          },
          "required": ["type", "message"]
        }
      ]
    },
    "field": {
      "type": "object",
      "required": ["name", "type", "label"],
      "properties": {
        "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" },
        "type": { "enum": ["string", "number", "boolean", "select", "date", "file"] },
        "label": { "type": "string" },
        "required": { "type": "boolean", "default": false },
        "default": {},
        "placeholder": { "type": "string" },
        "multiline": { "type": "boolean" },
        "maxLength": { "type": "integer" },
        "min": { "type": "number" },
        "max": { "type": "number" },
        "step": { "type": "number" },
        "minDate": { "type": "string", "format": "date" },
        "maxDate": { "type": "string", "format": "date" },
        "accept": { "type": "string" },
        "maxSize": { "type": "integer" },
        "options": {
          "type": "array",
          "items": { "$ref": "#/$defs/option" }
        }
      }
    },
    "option": {
      "type": "object",
      "required": ["value", "label"],
      "properties": {
        "value": { "type": "string" },
        "label": { "type": "string" },
        "description": { "type": "string" }
      }
    },
    "transition": {
      "type": "object",
      "required": ["target"],
      "properties": {
        "target": { "type": "string" },
        "condition": { "$ref": "#/$defs/condition" }
      }
    },
    "condition": {
      "type": "object",
      "oneOf": [
        {
          "properties": {
            "field": { "type": "string" },
            "equals": {}
          },
          "required": ["field", "equals"]
        },
        {
          "properties": {
            "field": { "type": "string" },
            "not_equals": {}
          },
          "required": ["field", "not_equals"]
        },
        {
          "properties": {
            "field": { "type": "string" },
            "operator": { "enum": ["gt", "gte", "lt", "lte", "contains", "in"] },
            "value": {}
          },
          "required": ["field", "operator", "value"]
        },
        {
          "properties": {
            "and": {
              "type": "array",
              "items": { "$ref": "#/$defs/condition" }
            }
          },
          "required": ["and"]
        },
        {
          "properties": {
            "or": {
              "type": "array",
              "items": { "$ref": "#/$defs/condition" }
            }
          },
          "required": ["or"]
        }
      ]
    }
  }
}
```

### Instance Response Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://core.interactor.com/schemas/workflow-instance.json",
  "title": "Workflow Instance",
  "type": "object",
  "required": ["id", "workflow_name", "status", "current_state", "created_at"],
  "properties": {
    "id": { "type": "string", "pattern": "^inst_[a-z0-9]+$" },
    "workflow_name": { "type": "string" },
    "version_id": { "type": "string" },
    "namespace": { "type": "string" },
    "status": { "enum": ["running", "halted", "completed", "failed", "cancelled"] },
    "current_state": { "type": "string" },
    "workflow_data": { "type": "object" },
    "halting_presentation": { "$ref": "workflow-definition.json#/$defs/presentation" },
    "threads": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "status": { "enum": ["running", "halted", "completed"] },
          "current_state": { "type": "string" }
        }
      }
    },
    "history": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "state": { "type": "string" },
          "entered_at": { "type": "string", "format": "date-time" },
          "exited_at": { "type": "string", "format": "date-time" },
          "transition": { "type": "string" },
          "duration_ms": { "type": "integer" }
        }
      }
    },
    "error": { "type": "string" },
    "created_at": { "type": "string", "format": "date-time" }
  }
}
```

---

## Quick Reference

### Common cURL Commands

```bash
# Create and publish a workflow
curl -X POST https://core.interactor.com/api/v1/workflows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @workflow.json

curl -X POST https://core.interactor.com/api/v1/workflows/my_workflow/versions/v_abc123/publish \
  -H "Authorization: Bearer $TOKEN"

# Start a workflow instance
curl -X POST https://core.interactor.com/api/v1/workflows/my_workflow/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{"namespace": "user_123", "input": {"key": "value"}}'

# Check instance status
curl https://core.interactor.com/api/v1/workflows/instances/inst_xyz \
  -H "Authorization: Bearer $TOKEN"

# Resume a halted instance
curl -X POST https://core.interactor.com/api/v1/workflows/instances/inst_xyz/resume \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: resume-unique-key" \
  -H "Content-Type: application/json" \
  -d '{"input": {"approved": true, "comment": "LGTM"}}'

# List halted instances for a user
curl "https://core.interactor.com/api/v1/workflows/instances?namespace=user_123&status=halted" \
  -H "Authorization: Bearer $TOKEN"

# Cancel an instance
curl -X POST https://core.interactor.com/api/v1/workflows/instances/inst_xyz/cancel \
  -H "Authorization: Bearer $TOKEN"
```

### Elixir Quick Start

```elixir
# Start instance
{:ok, instance} = MyApp.Interactor.Workflows.create_instance("approval", user_id, %{amount: 5000})

# Resume when halted
{:ok, resumed} = MyApp.Interactor.Workflows.resume_instance(instance["id"], %{approved: true})

# Poll for completion
{:ok, final} = MyApp.Interactor.Workflows.wait_for_completion(instance["id"])
```

### TypeScript Quick Start

```typescript
const workflow = new WorkflowManager(client);

// Start instance
const instance = await workflow.createInstance('approval', 'user_123', { amount: 5000 });

// Resume when halted
if (instance.status === 'halted') {
  await workflow.resumeInstance(instance.id, { approved: true });
}

// Wait for completion
const final = await workflow.waitForCompletion(instance.id);
```

---

## FAQ

### Common Issues & Solutions

**Q: My workflow is stuck in "running" status**
- **A**: Check that all action states have transitions. A state without transitions will halt the workflow engine. Add a transition to a terminal state or fix the logic.

**Q: Transitions are not firing as expected**
- **A**: Transitions are evaluated in order. The first matching condition wins. Ensure your conditions are ordered from most specific to least specific. The last transition should typically have no condition (default path).

**Q: Script logic is timing out**
- **A**: Scripts have a 5-second limit. Move complex computations to HTTP endpoints. Use scripts only for simple data transformations and routing decisions.

**Q: Form field validation fails on the client but succeeds on the server**
- **A**: Client-side validation should match server expectations. Use the JSON Schema to generate client validators. Test with the `/validate` endpoint during development.

**Q: Webhook events are not being delivered**
- **A**: Check: (1) Subscription is active, (2) URL is publicly accessible, (3) Endpoint returns 2xx within 30s, (4) Signature verification is correct. Use webhook dashboard to see delivery logs and retry failed events.

**Q: I get "concurrent_modification" errors**
- **A**: Multiple requests tried to resume the same instance. Use idempotency keys to prevent duplicates. Design your UI to disable buttons after submission. Check instance status before resuming.

**Q: How do I handle long-running external operations?**
- **A**: Use a halting state that waits for a webhook callback. Start the operation via HTTP logic, then transition to a halting state. When your external system completes, call the resume endpoint via webhook.

### Best Practices Checklist

- [ ] Use `/validate` endpoint during development
- [ ] Test all transition paths before publishing
- [ ] Implement idempotency keys for create/resume calls
- [ ] Verify webhook signatures in your handler
- [ ] Use namespaces to isolate user data
- [ ] Keep scripts under 100ms execution time
- [ ] Monitor rate limit headers and implement backoff
- [ ] Store `request_id` for debugging and support tickets

### Version Compatibility

| Feature | Introduced | Notes |
|---------|------------|-------|
| Core workflow API | v1.0.0 | Stable |
| Webhook subscriptions | v1.1.0 | Stable |
| `on_enter` for terminal states | v2.0.0 | Optional |
| Idempotency keys | v1.2.0 | Recommended |
| Thread parallelism | v1.3.0 | Stable |
| File field type | v2.1.0 | Beta |

> **Note**: The `on_enter` property for terminal states is available in Interactor v2.0.0+. Check your version before using this feature.

---

## Related Skills

- **interactor-auth**: Setup authentication (prerequisite)
- **interactor-credentials**: Use credentials in workflow HTTP actions
- **interactor-agents**: Combine AI agents with workflows
- **interactor-webhooks**: Real-time workflow status updates