DocumentationProduction
Open console
Docs/Quickstarts/Call the Workflow API from a service
GET STARTED

Call the Workflow API from a service

Resolve, preflight, invoke, launch, and consume a governed workflow.

Before you begin

  • A Midfleet Cloud workspace and project with an active versioned workflow contract.
  • A ready team and supported runtime path for the required capabilities.
  • A server-side API key with workflow-contracts:read, workflows:run, workflows:read, and workflow-artifacts:read.
  • A stable logical request identifier for idempotency.

1. Configure the server environment

dotenv
MIDFLEET_API=https://app.midfleet.ai
MIDFLEET_PROJECT_ID=<project-id>
MIDFLEET_API_KEY=<server-side-secret>

2. Resolve and preflight without creating work

Resolution selects and explains the deterministic contract match. Preflight independently checks route, roster, runtime, relay, console, and policy readiness. Neither call creates a draft, invocation, or run.

bash
curl -fsS "$MIDFLEET_API/api/v1/projects/$MIDFLEET_PROJECT_ID/workflow/resolve-intent"   -H "X-API-Key: $MIDFLEET_API_KEY"   -H "Content-Type: application/json"   --data '{"intent":"Prepare the release readiness report","required_capabilities":["reporting"]}'

curl -fsS "$MIDFLEET_API/api/v1/projects/$MIDFLEET_PROJECT_ID/workflow/preflight"   -H "X-API-Key: $MIDFLEET_API_KEY"   -H "Content-Type: application/json"   --data '{"intent":"Prepare the release readiness report","required_capabilities":["reporting"]}'

3. Invoke once and launch only when ready

Persist the returned invocation ID before launch. Reuse an idempotency key only for the same normalized logical request; changed content under the same key is a conflict.

bash
curl -fsS "$MIDFLEET_API/api/v1/projects/$MIDFLEET_PROJECT_ID/workflow/invocations"   -H "X-API-Key: $MIDFLEET_API_KEY"   -H "Idempotency-Key: release-readiness:<request-id>"   -H "Content-Type: application/json"   --data '{"intent":"Prepare the release readiness report","workflow_contract_id":"<contract-id>"}'

curl -fsS -X POST   "$MIDFLEET_API/api/v1/projects/$MIDFLEET_PROJECT_ID/workflow/invocations/<invocation-id>/launch"   -H "X-API-Key: $MIDFLEET_API_KEY"

4. Consume status and the strict artifact

Poll with a bounded timeout or consume verified signed delivery. Fetch the artifact only after the invocation exposes an artifact identity and reaches completed. waiting_for_artifact is not success.

http
GET /api/v1/projects/<project-id>/workflow/invocations/<invocation-id>
GET /api/v1/projects/<project-id>/workflow/invocations/<invocation-id>/artifact

5. Use the maintained TypeScript example

Continue with the Workflow API TypeScript example for a tested client with injected fetch, typed responses, and idempotency checks.