Playground API

Base URL:

https://api.provon.dev/v1

Authentication#

Playground routes are project-qualified. Each route accepts either an API-key capability or the corresponding signed-in project permission: writes require models:manage (API key) or project:data:write (signed-in user); reads require workspace:read (API key) or project:data:read (signed-in user).

Objects#

Playgrounds#

Create a Playground:

curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/playgrounds" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Compare reasoning models", "enabled_tool_names": ["web_search"]}'

enabled_tool_names is canvas-scoped: every Agent in the Playground runs against the same tool set, so a comparison differs only in the model and request. Omit it to accept the deployment default.

Tools#

Agents#

Create an Agent:

curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/playgrounds/$PLAYGROUND_ID/agents" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "request": {
      "system_prompt": "You are a helpful assistant.",
      "messages": [
        { "role": "user", "content": "What is 2 + 2?" }
      ],
      "params": {
        "temperature": 0.5,
        "max_tokens": 256
      }
    }
  }'

Agent fields:

messages use { "role": "system" | "user" | "assistant", "content": "..." } objects. params supports temperature, top_p, and max_tokens (each nullable).

execution_limits bounds (defaults shown):

Executions#

Starting an Execution streams Server-Sent Events (event: <kind>\ndata: <json>). Event kinds include execution.started, model.started, model.completed, tool.call.started, tool.call.completed, tool.call.failed, assistant.output, execution.completed, execution.failed, execution.limit_reached, and execution.cancelled. A final done event carries the finished Execution record.

Execution statuses are queued, running, completed, failed, cancelled, and limit_reached. The Execution record exposes a snapshot (model, request, tools, limits), metrics (model_calls, tool_calls, duration_ms), final_output, and error.

Instant Execution#

For a one-off comparison without persisting an Agent:

curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/playgrounds/instant-executions" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "request": {
      "messages": [{"role": "user", "content": "What is 2 + 2?"}],
      "params": { "max_tokens": 256 }
    },
    "stream": true
  }'

The body uses the same request shape as an Agent column: { system_prompt?, messages, params }, plus the top-level model and optional stream. The endpoint folds system_prompt into the messages array and spreads params onto the Gateway /v1/chat/completions request. The response is the raw Gateway response; set stream: true to receive the upstream SSE stream. Errors surface as 502 gateway_execution_failed.

Errors#

Playground errors use either the common API error envelope or a compact { error, message } body.