Getting Started

1

Welcome to the BetterPrompt API. This quick‑start guide shows you how to authenticate, find the correct prompt version and execute a run using our REST API. Before you jump into the reference section, follow the steps below to make your first call.

2

This quick start is written for developers. It walks through creating an API key, finding the right prompt version and hitting the run endpoint. Follow the steps below to make your first call.

Prerequisites

1. Create an API key – log in to your BetterPrompt account and Create an API key. You will use this key to authenticate your HTTP requests via an Authorization: Bearer <API_KEY> header.

2. Get a prompt ID – On the prompt detail page you will find a button.

3. Understand JSON Type Definition (JTD) – each prompt's inputs are described using JSON Type Definition (JTD). When you fetch a prompt, the response includes an inputsJTD object describing the expected fields.

Run with the API

Locate the latest version of a prompt

Prompts can have multiple published versions. To find the latest one, call GET /api/v1/prompts/{promptId}. If you want a specific version, pass ?versionId= with the version UUID.

To list all available versions, call GET /api/v1/prompts/{promptId}/versions. This returns up to ten versions sorted by their publication date.

Execute a run

Once you have your promptVersionId, send a POST /api/v1/runs request. The body must include the promptVersionId and an inputs object that matches the inputsJTD. The handler defines the schema for textInputs and imageInputs:contentReference[oaicite:0]{index=0}; runOptions is optional.

imageInputs is an array of ImageInputs, and the number of images is defined in the prompt's inputsJTD. Currently supporting url or base64 .

curl -X POST https://api.betterprompt.me/v1/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "promptVersionId": "YOUR_PROMPT_VERSION_ID",
        "inputs": {
          "textInputs": {
            "yourField": "value"
          }
        }
      }'

When the run completes, the API returns a JSON object containing a unique runId, the generated outputs, a runStatus field and token usage.

Retrieve run status

To poll or fetch a running/completed run, call GET /api/v1/runs/{runId}. This route validates a UUID v7 runId and returns the same fields as the initial run response: runId, outputs, runStatus and token counts.

Run with the n8n node

Version 1

BetterPrompt provides a pre‑configured node for n8n, a popular open‑source automation platform. On each prompt's detail page you will find a Copy n8n node button. Clicking this copies a JSON representation of the node to your clipboard. In n8n, open your workflow, paste the node into the canvas and configure it with your API key. The node automatically handles authentication and maps the required promptVersionId and inputs fields based on the selected prompt. Use this option if you prefer a no‑code/low‑code integration instead of direct HTTP calls.

VERSION 2

If you prefer low code, we provide an n8n node. On the prompt detail page click Copy n8n node to copy the node definition. Paste it into your n8n workflow and set your API key. The node wires up the promptVersionId and inputs automatically.

---

With these steps you can quickly create an API key, locate the correct version of your prompt and execute runs via HTTP or through n8n. The API reference contains detailed information about request parameters, response schemas, error handling and rate limits.