Skip to content

Playground API

The Playground API manages project-scoped model comparison canvases. Each Playground contains multiple Runs; each Run captures model selection, messages, parameters, and execution

View as Markdown Open the plain-text version of this page.

Base URL:

text
https://api.provon.dev/v1

Authentication#

Playground routes are project-qualified. API-key callers need models:manage (or workspace:write) for writes and workspace:read for reads. Signed-in Workbench users need the corresponding project permission (project:data:read or project:data:write).

Playgrounds#

Method Path Purpose
GET /v1/projects/:projectId/playgrounds List Playgrounds
POST /v1/projects/:projectId/playgrounds Create a Playground
GET /v1/projects/:projectId/playgrounds/:playgroundId Read one Playground
PATCH /v1/projects/:projectId/playgrounds/:playgroundId Update label
DELETE /v1/projects/:projectId/playgrounds/:playgroundId Delete Playground

Create a Playground:

bash
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"}'

Runs#

Method Path Purpose
POST /v1/projects/:projectId/playgrounds/:playgroundId/runs Create a Run
PATCH /v1/projects/:projectId/playgrounds/:playgroundId/runs/:runId Update a Run
DELETE /v1/projects/:projectId/playgrounds/:playgroundId/runs/:runId Delete a Run
POST /v1/projects/:projectId/playgrounds/:playgroundId/runs/:runId/execute Execute a Run

Create a Run:

bash
curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/playgrounds/$PLAYGROUND_ID/runs" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "gpt-5-mini tool call",
    "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
      }
    }
  }'

Run fields:

Field Type Notes
label string Optional display name; defaults to "Run".
model string Required. Any Gateway-resolvable model such as openai/gpt-5-mini.
request object Required. Contains system_prompt, messages, params.

messages use { "role": "system" | "user" | "assistant", "content": "..." } objects. params supports temperature, top_p, max_tokens, frequency_penalty, presence_penalty, seed, and stop_sequences.

Execute A Run#

Execute a Run against the Gateway. The response is the raw Gateway response for the requested path (/v1/chat/completions).

bash
curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/playgrounds/$PLAYGROUND_ID/runs/$RUN_ID/execute" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stream": false}'

Request body:

Field Type Notes
stream boolean Optional. Return a streaming SSE response when true.
request object Optional. Override the Run's stored request.

When stream is false and the Gateway returns a JSON response, the result is stored on the Run as lastResult and lastRunAt is updated.

Errors#

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

json
{
  "error": "not_found",
  "message": "playground \"pg_123\" not found"
}
Status Meaning
400 Invalid request body or missing field
401 Missing or invalid credential
403 Credential lacks capability/permission
404 Playground or Run not found
502 Gateway execution failed