Local Server API Reference

This quickstart uses the built-in echo provider and keeps the result on your machine. Use a Bash-compatible shell with Node.js 22.22 or later, curl 7.82 or later, and jq. No API key is required.

1. Start the server. Run this in one terminal and leave it running.

npx --yes promptfoo@latest view -n --port 15500

2. Submit the eval. In a second terminal, send the request and save the job ID.

promptfoo_url=http://localhost:15500
job_id=$(curl -fsS "$promptfoo_url/api/eval/job" --json '{
  "prompts": ["ping"],
  "providers": ["echo"],
  "tests": [{"assert":[{"type":"equals","value":"ping"}]}],
  "sharing": false
}' | jq -er '.id')

3. Get the result. Run this in the same terminal. If the status is in-progress, repeat the command.

curl -fsS "$promptfoo_url/api/eval/job/$job_id" | jq '{
  status, evalId, output: .result.results[0].response.output,
  passed: .result.stats.successes, failed: .result.stats.failures
}'

A successful run returns complete, an evalId for the saved result, output ping, one pass, and zero failures.

The job commands above work with [email protected]. That release predates the local spec endpoint. On builds that include #8978, you can also inspect the spec for the version you’re running:

curl -fsS "$promptfoo_url/api/openapi.json" | jq '.info'

For Enterprise On-Prem, start jobs with POST /api/v1/jobs. With hosted Promptfoo Cloud, run the eval locally or in CI and upload the results. See the Cloud and Enterprise API reference.