Execute an approved effect

What you will build

An external effect, gated by workflow, authority, and policy, run as a simulated effect in the test environment. Every effect produces a receipt.

Architecture preview

In a test environment effects are simulated or allowlisted; in production they run for real. Irreversible effects are never shown complete before their receipt is recorded.

Prerequisites

• A resolved approval decision (see the previous quickstart)

Steps

1. Confirm the command is legal

   Read the legal actions for the artifact in its current state. The command must be listed before you issue it.

   curl --url "$CRESCEVO_BASE_URL/v1/artifacts/a_123/legal-actions" \
     --header "Authorization: Bearer $CRESCEVO_API_KEY"

   { "legal_actions": ["artifact.deliver"] }

2. Issue the command

   Issue the approved command with an idempotency key so a retry applies at most once. In test, the effect targets a simulated destination.

   curl --request POST \
     --url "$CRESCEVO_BASE_URL/v1/commands" \
     --header "Authorization: Bearer $CRESCEVO_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: quickstart-deliver-001" \
     --data '{ "command": "artifact.deliver", "target": { "type": "artifact", "id": "a_123" }, "arguments": { "destination": "mock://inbox" } }'

   { "command_id": "cmd_1", "effect_id": "eff_1", "status": "running" }

3. Observe the effect and receipt

   Poll the effect until it completes, then read its receipt.

   curl --url "$CRESCEVO_BASE_URL/v1/effects/eff_1" \
     --header "Authorization: Bearer $CRESCEVO_API_KEY"

   { "effect_id": "eff_1", "status": "succeeded", "receipt_id": "rcpt_1" }

Verify success

• The command was accepted because it was a legal action.
• A simulated effect ran and reached the mock destination.
• A receipt was produced with the idempotency key.

Clean up

Simulated effects touch only the mock target. Test-tenant resources expire automatically.

Next: Inspect a receipt →