Runs

Universal execution primitive for agentic apps.

POST /v1/runs

Creates a capability run (agent target reserved).

curl -s -X POST https://api.skilleo.org/v1/runs \
  -H "Authorization: Bearer $SKILLEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"capability","name":"research.gather","version":"1","input":{"topic":"Kenya wildlife"},"options":{"optimize_for":"cost"}}'

Options

Field	Applies to	Description
optimize_for	LLM capabilities	cost, quality, or balanced — influences default provider order
provider	LLM, voice	Pin a connected provider (openai, minimax, elevenlabs, …)
compute_id	GPU capabilities	RunPod pod target
endpoint_id	GPU capabilities	RunPod serverless endpoint

Options are stored on the run and passed to the underlying job. Infrastructure targets in options are stripped from the public run record but still used for execution.

Response (202): envelope with id = run_…, data.run_id, data.status, data.output, data.artifacts, data.usage (skilleo vs provider_usage).

Examples

LLM with provider pin

curl -s -X POST https://api.skilleo.org/v1/runs \
  -H "Authorization: Bearer $SKILLEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"capability","name":"llm.generate","version":"1","input":{"objective":"Plan a 60-second wildlife short"},"options":{"provider":"anthropic","optimize_for":"quality"}}'

Speech

curl -s -X POST https://api.skilleo.org/v1/runs \
  -H "Authorization: Bearer $SKILLEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"capability","name":"speech.generate","version":"1","input":{"text":"Welcome to the Mara at dawn."},"options":{"provider":"elevenlabs"}}'

GET /v1/runs/{run_id}

Poll until completed | failed | cancelled.

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

SDK

from skilleo import Client

client.capabilities.run(
    "llm.generate",
    input={"objective": "Summarize Kenya wildlife"},
    version="1",
    options={"provider": "minimax"},
)
# or
client.runs.create(name="research.gather", input={"topic": "Kenya"})