Management API workflows

Use the management API to automate prompt lifecycle tasks. It authenticates a person through OAuth and checks current organization access. Application retrieval uses a different credential and endpoint; see retrieval.

Prepare credentials and files

Use an OAuth access token issued for the https://www.promptlens.io/api/v1 resource with the management scope. Follow API authentication for discovery and resource separation. This walkthrough assumes that token is already available in your private server environment; do not extract one from the CLI credential store.

The shell examples require cURL, jq, and uuidgen. Download ticket-router.prompt.json and ticket-routing.json into your working directory. Select an available model route in the prompt file before creating it.

export PROMPTLENS_API_URL='https://www.promptlens.io'
export PROMPTLENS_ACCESS_TOKEN='YOUR_MANAGEMENT_ACCESS_TOKEN'
export PROMPTLENS_ORG_ID='YOUR_ORGANIZATION_ID'

List organizations if you need their IDs:

curl --fail-with-body --silent --show-error \
  "$PROMPTLENS_API_URL/api/v1/organizations" \
  -H "Authorization: Bearer $PROMPTLENS_ACCESS_TOKEN"

Read items and follow nextCursor to continue a paginated list. Confirm the intended workspace before writing.

Create and populate the prompt

Generate a request key once for this action. Keep it with the exact request if you need to recover an uncertain response; generate another for a new action.

CREATE_REQUEST_KEY=$(uuidgen)
curl --fail-with-body --silent --show-error \
  "$PROMPTLENS_API_URL/api/v1/organizations/$PROMPTLENS_ORG_ID/prompts" \
  -H "Authorization: Bearer $PROMPTLENS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $CREATE_REQUEST_KEY" \
  --data-binary @ticket-router.prompt.json > created-prompt.json
PROMPTLENS_PROMPT_ID=$(jq -er '.id' created-prompt.json)
PROMPT_URL="$PROMPTLENS_API_URL/api/v1/organizations/$PROMPTLENS_ORG_ID/prompts/$PROMPTLENS_PROMPT_ID"

curl --fail-with-body --silent --show-error "$PROMPT_URL/dataset" \
  -H "Authorization: Bearer $PROMPTLENS_ACCESS_TOKEN" > dataset.json
jq --slurpfile cases ticket-routing.json \
  '{revision: .revision, mode: "append", rows: $cases[0]}' \
  dataset.json > import.json

IMPORT_REQUEST_KEY=$(uuidgen)
curl --fail-with-body --silent --show-error "$PROMPT_URL/dataset/import" \
  -H "Authorization: Bearer $PROMPTLENS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IMPORT_REQUEST_KEY" \
  --data-binary @import.json

Inspect each response before continuing. A stale revision requires reading and reviewing the current dataset, not replacing the revision automatically.

Establish version 1

Read your draft and initialize using expected scoring. Every routing case has a reference label. This scoring mode is the management interface's control; configured dashboard evaluator objects are not part of this request.

curl --fail-with-body --silent --show-error "$PROMPT_URL/draft" \
  -H "Authorization: Bearer $PROMPTLENS_ACCESS_TOKEN" > draft.json
jq '{draftRevision: .revision, scope: "quick", scoringMethod: "expected"}' \
  draft.json > initialize.json

INITIALIZE_REQUEST_KEY=$(uuidgen)
curl --fail-with-body --silent --show-error "$PROMPT_URL/initialize" \
  -H "Authorization: Bearer $PROMPTLENS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $INITIALIZE_REQUEST_KEY" \
  --data-binary @initialize.json > baseline.json
EVALUATION_ID=$(jq -er '.id' baseline.json)
EVALUATION_URL="$PROMPTLENS_API_URL/api/v1/organizations/$PROMPTLENS_ORG_ID/evals/$EVALUATION_ID"

curl --fail-with-body --silent --show-error "$EVALUATION_URL" \
  -H "Authorization: Bearer $PROMPTLENS_ACCESS_TOKEN"
curl --fail-with-body --silent --show-error "$EVALUATION_URL/results" \
  -H "Authorization: Bearer $PROMPTLENS_ACCESS_TOKEN"

Poll status with a delay between requests until terminal, honoring Retry-After when present. Do not treat the accepted response as completion. Inspect all result pages. A completed baseline establishes version 1 and initial labels; an execution failure needs resolution first.

Change, save, compare, and publish

For a later candidate, use this sequence. The operation pages provide exact request bodies:

1. Read your draft, edit content, and update it with its current revision.
2. Save a version with draftRevision from the updated draft. Keep the returned version id.
3. Start an evaluation with that versionId, scoringMethod: "expected", scope: "quick", and comparison: "reuse_production" or "rerun_both".
4. Poll the returned candidateRunId and productionRunId; inspect both sides and their results. productionReused indicates whether the baseline was reused.
5. Read labels and assign production with the target versionId and current label revision. If published is false, inspect the warnings and decide whether to repeat with the returned acknowledgment.

A complete shell version of this editing and publication sequence is in the CLI workflow. Keep request idempotency separate from revision checks: one protects recovery from duplicate writes, the other protects against overwriting newer state.