Documentation Index
Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
Use this file to discover all available pages before exploring further.
BlueprintStep records a single atomic action taken by the Blueprint Analyzer AI agent during a web-navigation run. Each step belongs to exactly one BlueprintRun (cascade-deleted with it) and is sequenced by a monotonically increasing step_number. Steps capture the agent’s reasoning, the page URL at the time of execution, the action it chose (e.g. click, type, scroll), structured action parameters, the raw LLM response, screenshot storage references, and an outcome flag — forming the complete execution trace for a run. The table is written exclusively by the blueprint-analyzer.service.ts pipeline; no user-facing PATCH endpoint exists.
| Naming | Value |
|---|
| Object | BlueprintStep |
Resource type (JSON:API type) | blueprint_step |
| Collection / records root | — (not a records root) |
| REST base | /v1/blueprint-steps |
| Entity class | BlueprintStep |
Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.
API operations
| Operation | Method & path | Status |
|---|
| List | GET /v1/blueprint-steps | 🟡 Planned |
| Retrieve | GET /v1/blueprint-steps/{id} | 🟡 Planned |
| Create | POST /v1/blueprint-steps | 🟡 Planned |
| Update | PATCH /v1/blueprint-steps/{id} | 🟡 Planned |
| Delete | DELETE /v1/blueprint-steps/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| blueprint_step_id | string (UUID) 🔒 system | ✅ Yes | unique; generated by gen_random_uuid() at INSERT | Any valid UUID v4 | Public-facing stable identifier for the step. Exposed as the JSON:API id. Never reused. |
| step_number | integer | ✅ Yes | composite UNIQUE (blueprint_run_pk, step_number); composite partial index idx_blueprint_steps_run_step on (blueprint_run_pk, step_number) WHERE deleted_at IS NULL | Positive integer; 1-based sequence assigned by the analyzer service | 1-based ordinal position of this step within its parent run. Uniqueness is enforced at the DB level per run (soft-delete-aware index). |
| action_type | string (text) | ✅ Yes | NOT NULL | Free-form string set by the analyzer (e.g. ‘click’, ‘type’, ‘scroll’, ‘navigate’, ‘extract’, ‘wait’) | Identifies the category of browser action the agent decided to execute at this step. |
| reasoning | string (text) | ⚪ No | nullable | — | Free-text chain-of-thought produced by the LLM before committing to this action. Populated when the model includes a reasoning block in its response. |
| page_url | string (text) | ✅ Yes | NOT NULL | Full URL of the page at the time the step was executed | Captures the browser’s current URL when the step fired, enabling replay and debugging. |
| screenshot_path | string (text) | ⚪ No | nullable | GCS object path relative to the bucket, or null if no screenshot was captured | Path of the screenshot image stored in GCS at the time of this step. Paired with screenshot_bucket to form the full storage reference. |
| screenshot_bucket | string (text) | ⚪ No | nullable | GCS bucket name, or null | GCS bucket that holds the screenshot referenced by screenshot_path. Null when no screenshot was taken for this step. |
| action_details | jsonb | ⚪ No | nullable | Arbitrary JSON object; shape depends on action_type (e.g. selector, coordinates, input text, scroll delta) | Structured parameters needed to replay or audit the exact action that was executed (e.g. CSS selector, click coordinates, text typed). |
| ai_response | jsonb | ⚪ No | nullable | Arbitrary JSON; typically the raw Anthropic API response object | Full LLM response payload recorded for observability — includes model ID, stop_reason, token usage, and tool calls. Enables cost analysis and debugging. |
| dom_summary_length | integer | ⚪ No | nullable | Non-negative integer representing character count of the DOM summary sent to the LLM | Character length of the DOM summary fed to the model for this step. Useful for prompt-size analytics and detecting pages with unusually large DOMs. |
| action_success | boolean | ⚪ No | nullable | true | false | null | Whether the browser action completed without error. Null means the outcome was not recorded (e.g. the step was interrupted). false indicates the browser threw an exception, detailed in action_error. |
| action_error | string (text) | ⚪ No | nullable | Error message string, or null | Human-readable error message when action_success is false. Captures Playwright/browser errors (selector not found, navigation timeout, etc.). |
| created_at | timestamptz 🔒 system | ✅ Yes | NOT NULL; set by onCreate hook to new Date() | — | Timestamp when the row was inserted. Set automatically at creation; never updated. |
| updated_at | timestamptz 🔒 system | ⚪ No | nullable; set by onCreate and onUpdate hooks | — | Timestamp of the last mutation. Set automatically at creation and on every update by MikroORM lifecycle hooks. |
| deleted_at | timestamptz 🔒 system | ⚪ No | nullable | null (active) | ISO 8601 timestamp (soft-deleted) | Soft-delete sentinel. Non-null means the row is logically deleted. The partial index idx_blueprint_steps_run_step covers only rows WHERE deleted_at IS NULL. |
Relationships
| Name | Type | Required | Description |
|---|
| blueprint_run | to-one (ManyToOne) | Yes — NOT NULL FK with ON DELETE CASCADE | The parent BlueprintRun that owns this step. Deleting the run cascades and hard-deletes all its steps. This is the only relationship declared on BlueprintStep itself; the inverse collection (steps) is declared on BlueprintRun. |
System-computed
- blueprint_step_id — generated by gen_random_uuid() at INSERT, never caller-supplied
- created_at — set to new Date() by MikroORM onCreate hook
- updated_at — set to new Date() by both onCreate and onUpdate hooks
- deleted_at — soft-delete sentinel; written by the service layer when soft-deleting a step or its parent run
- step_number — assigned by blueprint-analyzer.service.ts before INSERT; not derived from a DB sequence but from the service’s step counter
- Cascade delete — when the parent BlueprintRun is deleted (hard or via cascade), all BlueprintStep rows are hard-deleted by the DB foreign-key constraint (ON DELETE CASCADE)
Example
{
"data": {
"id": "7e4c1a2b-d3f0-4e8a-b5c6-9d0e1f2a3b4c",
"type": "blueprint_step",
"attributes": {
"blueprint_step_id": "7e4c1a2b-d3f0-4e8a-b5c6-9d0e1f2a3b4c",
"step_number": 3,
"action_type": "click",
"reasoning": "The login button is visible and I need to authenticate before accessing the invoices page.",
"page_url": "https://app.example.com/login",
"screenshot_path": "blueprint-runs/run_abc123/step_003.png",
"screenshot_bucket": "well-blueprints-prod",
"action_details": {
"selector": "#login-submit-btn",
"coordinates": { "x": 640, "y": 420 }
},
"ai_response": {
"model": "claude-opus-4-6",
"stop_reason": "tool_use",
"usage": { "input_tokens": 4120, "output_tokens": 87 }
},
"dom_summary_length": 8432,
"action_success": true,
"action_error": null,
"created_at": "2026-02-24T14:23:01.000Z",
"updated_at": "2026-02-24T14:23:02.000Z",
"deleted_at": null
},
"relationships": {
"blueprint_run": {
"data": { "type": "blueprint_run", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
}
}
}
}
apps/api/src/database/entities/BlueprintStep.ts · domain: automation · tier: Activity
