Getting Started

This quick start 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 code button to copy the prompt ID.

3. Understand prompt inputs — each prompt defines the inputs it expects (text fields and/or images). When you fetch a prompt, the response includes a config object describing the input configuration.

Run with the API

Locate the latest version of a prompt

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

Execute a run

Once you have your promptVersionId, send a POST /v1/runs request. The body must include the promptVersionId and an inputs object that matches the prompt's configuration. The inputs object contains textInputs and optionally imageInputs; runOptions is optional.

curl

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"
          }
        }
      }'

Node.js

const API_KEY = process.env.BETTERPROMPT_API_KEY || "YOUR_API_KEY";
const PROMPT_VERSION_ID =
  process.env.BP_PROMPT_VERSION_ID || "YOUR_PROMPT_VERSION_ID";

async function main() {
  const res = await fetch("https://api.betterprompt.me/v1/runs", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      promptVersionId: PROMPT_VERSION_ID,
      inputs: { textInputs: { yourField: "value" } },
    }),
  });

  const json = await res.json();
  console.log(json);
}

main().catch(console.error);

Python

import os
import requests

API_KEY = os.getenv("BETTERPROMPT_API_KEY", "YOUR_API_KEY")
PROMPT_VERSION_ID = os.getenv("BP_PROMPT_VERSION_ID", "YOUR_PROMPT_VERSION_ID")

resp = requests.post(
    "https://api.betterprompt.me/v1/runs",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "promptVersionId": PROMPT_VERSION_ID,
        "inputs": {"textInputs": {"yourField": "value"}},
    },
)
print(resp.json())

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 /v1/runs/{runId}. This returns the same fields as the initial run response: runId, outputs, runStatus, and token counts.

Run with the n8n node

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.