Quickstart

This guide walks through the end-to-end shape of a Wishfleet integration: select a workflow, start an instance, inspect state, work with goals and tasks, and advance the workflow through to completion.

Prerequisite. You need a Wishfleet account. If you don't have one yet, register at the Wishfleet dashboard.

The integration shape

A Wishfleet integration sits between your application and the workflow service. Your application provides domain context and signals; Wishfleet holds the workflow state, runs the decision engine, and emits events.

Your app  <──  events out      ─── [Wishfleet workflow service + decision engine]
          ──>  signals in       ───
          ──>  control calls    ───
                                 ↑
              [Specifications + Skills bundles]

Three message classes flow across the boundary:

  • Control calls in — your app tells Wishfleet to mutate state: start a workflow, close a task, add work to a goal.
  • Signals in — external facts that the workflow cares about: "credit pull returned," "vendor confirmed."
  • Events out — Wishfleet tells your app what changed: "workflow closed," "process advanced," "goal unblocked."

1. Select or author a workflow

Wishfleet workflows are built from specifications — JSON documents declaring processes, goals, tasks, tools, and dependency edges. You have two options:

Choose a library workflow. In the dashboard, browse the workflow library and click Enable on the workflow that fits your use case. Library workflows are ready to use immediately.

Author your own. Publish a custom specification via the REST API:

POST /v1/specifications
{
  "name": "apartment-turn",
  "version": "1.0.0",
  "processes": [ ... ],
  "goals": [ ... ],
  "tasks": [ ... ]
}

→ { "id": "spec_xyz789", "name": "apartment-turn", "version": "1.0.0" }

Specifications are immutable once published — versioned by (author, name, version). To iterate, bump the version and publish again.

2. Start a workflow

Start a workflow for a work item — the real-world thing the workflow is about. The work item is your domain object; Wishfleet treats it as opaque context.

POST /v1/workflow-instances
{
  "specificationId": "spec_xyz789",
  "workItem": {
    "type": "unit",
    "id": "unit-4b",
    "displayName": "1240 Broadway, Unit 4B"
  }
}

→ { "publicId": "wf_qrs456", "currentProcess": "vacated", "status": "open" }

3. Inspect state

Read the full workflow state — current process (stage), all processes with status, goals and tasks with their dependencies and status:

GET /v1/workflow-instances/wf_qrs456

→ {
    "publicId": "wf_qrs456",
    "status": "open",
    "stageName": "condition_documented",
    "stageIndex": 2,
    "specification": "[email protected]",
    "workItem": { "type": "unit", "id": "unit-4b" },
    "processes": [
      { "name": "vacated", "status": "closed", "reason": "success" },
      { "name": "condition_documented", "status": "open" },
      { "name": "work_identified", "status": null }
    ],
    "goals": [
      { "publicId": "wf_qrs456.con.d21485", "name": "document_condition",
        "status": "open", "required": true }
    ],
    "tasks": [
      { "publicId": "wf_qrs456.con.d21485.1", "name": "photograph_unit",
        "status": "open" },
      { "publicId": "wf_qrs456.con.d21485.2", "name": "complete_checklist",
        "status": "open", "dependsOn": ["wf_qrs456.con.d21485.1"] }
    ]
  }

Query what is actionable right now — unblocked goals, unblocked tasks, and available tools:

GET /v1/workflow-instances/wf_qrs456/work

→ {
    "stageName": "condition_documented",
    "unblockedGoals": [
      { "publicId": "wf_qrs456.con.d21485", "name": "document_condition",
        "required": true }
    ],
    "unblockedTasks": [
      { "publicId": "wf_qrs456.con.d21485.1", "name": "photograph_unit" }
    ],
    "tools": []
  }

The /work endpoint returns the dependency-gated view: only goals and tasks whose dependsOn edges are satisfied appear as unblocked. This is the primary query an agent or integration uses to decide what to do next.

4. Work with goals and tasks

Goals are declared outcomes within a process. Tasks are planned work that advances goals. Multiple goals and tasks can be open concurrently; sequencing comes from dependsOn edges.

Close a task when the work it represents is done:

PATCH /v1/workflow-tasks/wf_qrs456.con.d21485.1
{ "status": "closed", "reason": "success" }

Add a task dynamically — new work discovered during execution:

POST /v1/workflow-goals/wf_qrs456.con.d21485/tasks
{ "name": "document_damage", "dependsOn": ["wf_qrs456.con.d21485.1"] }

Deprecate a task that is no longer needed:

PATCH /v1/workflow-tasks/wf_qrs456.con.d21485.2
{ "status": "closed", "reason": "deprecated" }

Close a goal explicitly:

PATCH /v1/workflow-goals/wf_qrs456.con.d21485
{ "status": "closed", "reason": "success" }

Or let a goal auto-close — if the goal opts in (autoClose: true), it closes with success when all non-deprecated tasks under it are closed with success:

POST /v1/workflow-goals/wf_qrs456.con.d21485/auto-close

5. Evidence and authorization

Evidence (structured proof — photo sets, signed documents, attestations) and authorization rules are part of the workflow grammar. Specifications declare evidence requirements and authorization constraints per process and per goal. See Composable Workflows for the full grammar.

6. Advance the workflow

Process advancement is emergent: when all required goals in the current process close with success, the workflow automatically advances to the next process (or closes if the final process is complete). There is no explicit "submit transition" call.

To drive the workflow forward with the decision engine, feed a task result and let the engine decide what to do next:

POST /v1/workflow-instances/wf_qrs456/advance
{
  "taskId": "wf_qrs456.con.d21485.1",
  "result": { "coverage": ["kitchen", "bathroom", "bedroom", "living_room"] }
}

The decision engine reads state, evaluates the task result, and takes appropriate actions — closing tasks, closing goals, or letting process advancement occur naturally. Every decision is recorded with a reasoning trace.

What's next