API Introduction

Overview

BetterPrompt API lets you run published prompt versions (text, image, and video prompts), retrieve outputs, manage credits, and integrate the results into your applications. The API is available to Pro subscribers — see Authentication for details.

This reference documents the stable v1 endpoints and the standard response format used across the API.

Available resources

Resource	Description
Prompts	Search and retrieve published prompts.
Prompt versions	Inspect prompt versions.
Runs	Execute prompts and retrieve outputs.
User	Account info and credit balance.
Resources	Available models and capabilities.

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 every request with an API key via the Authorization header using the Bearer scheme. Create keys at betterprompt.me/api-keys. See the full Authentication guide for details.

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 Handling, Output item types, Run status.

Support and contact

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