API Introduction

Overview

BetterPrompt API lets you run published prompt versions (text and image prompts), retrieve outputs, and integrate the results into your applications. This reference documents the stable v1 endpoints and the standard response format used across the API.

Base URL

All endpoints in this reference are relative to the v1 base path:

https://api.betterprompt.me/v1

For example, the Runs endpoints are available at:

• POST /v1/runs — Create a run
• GET /v1/runs/:runId — Retrieve a run

Authentication

Authenticate using an API key via the HTTP Authorization header with the Bearer scheme. Keep your key secret and never embed it in client-side code.

Authorization: Bearer <YOUR_API_KEY>

Example request using curl:

curl -X GET \
  "https://api.betterprompt.me/v1/runs/<RUN_ID>" \
  -H "Authorization: Bearer $BETTERPROMPT_API_KEY" \
  -H "Content-Type: application/json"

Standard response format

All endpoints return a unified JSON envelope.

Success:

{
  "status": "SUCCESS",
  "data": {
    "...": "resource payload"
  }
}

Error:

{
  "status": "NOT_FOUND_ERROR",
  "message": "Run not found",
  "data": null
}

Notes:

• status is "SUCCESS" for successful operations; otherwise it is an error code (for example, "VALIDATION_ERROR", "NOT_FOUND_ERROR", "GATEWAY_TIMEOUT_ERROR").
• message is present on errors and describes the failure.
• data contains the response payload on success, or optional context on errors.

See also: Error codes, Output item types, Run status.

Support and contact

Need help? Contact the team at developers@betterprompt.me.