Plans

Objective in, validated capability-driven DAG out. Plans do not execute work — use the returned workflow_definition with workflows or start a task for end-to-end execution.

POST /v1/plans

Create a plan synchronously. Returns 201 with a pln_ id.

Field	Type	Description
objective	string	Required. What to produce
constraints	object	Optional prompt, width, height, steps, format, max_cost_usd, max_latency_ms, optimize_for, etc.
context	object	Reserved for audience, locale, and other planner hints
optimize_for	string	Optional. cost, latency, or balanced (default balanced)

curl -s -X POST https://api.skilleo.org/v1/plans \
  -H "Authorization: Bearer $SKILLEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"objective":"Generate image of a red cube","optimize_for":"cost","constraints":{"max_cost_usd":0.08}}'

Response data

Field	Description
objective	Echo of the request
template	Rule template used (illustrated_post, image_only)
optimize_for	Policy used for execution scoring
nodes	Planned DAG nodes with capability_status, and for GPU steps execution_candidates / execution_preferred
execution	Workflow-level execution summary (policy, preferred, by_node)
validation	dag_valid, executable, capability lists, issues
estimates	cost_usd, duration_ms, gpu_steps (available steps only)
quality_criteria	Review checklist for a future manager
workflow_definition	Same node shape as workflows, including execution_preferred on GPU nodes

Plan status (top-level status)

Status	Meaning
executable	DAG valid; every capability is available
planned	DAG valid; one or more capabilities missing
invalid	Invalid dependencies or cycle

Capability status (per node)

Value	Meaning
available	Registered at /v1/capabilities
missing	Capability not yet available on this deployment
unknown	Not in the planner catalog

GET /v1/plans/{id}

Retrieve a stored plan.

curl -s https://api.skilleo.org/v1/plans/pln_abc123 \
  -H "Authorization: Bearer $SKILLEO_API_KEY"

Example

curl -s -X POST https://api.skilleo.org/v1/plans \
  -H "Authorization: Bearer $SKILLEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"objective":"Create an illustrated wildlife post about Kenya"}'

Returns a four-node DAG: research.gather → llm.generate → image.generate → composition.layout. All four are available; executable is true. Copy and image prompts come from llm.generate.

SDK

plan = client.plans.create(
    objective="Generate image of a red cube",
    optimize_for="cost",
    constraints={"max_cost_usd": 0.08},
)
preferred = plan["data"]["nodes"][0]["execution_preferred"]
if plan["data"]["validation"]["executable"]:
    wf = client.workflows.create(**plan["data"]["workflow_definition"])

Plans produce a validated DAG and cost estimate. Submit workflow_definition to /v1/workflows, or use /v1/tasks for a fully managed outcome loop.