Start here

Quickstart

Use this sequence after purchasing an engine. The text route below is an example; replace the route and request body with the contract on your purchased product page.

1. Save the revealed key

Copy the key during the ten-minute reveal and store it immediately in a password manager and your server deployment environment. The raw value cannot be recovered after confirmation or reveal expiry.

2. Set server environment variables

URTHEPRODUCT_BASE_URL=https://urtheproduct.com
URTHEPRODUCT_API_KEY=utp_live_publicid.secret

Restart the local server after changing environment variables. In Vercel, add both values to the intended environments and redeploy; do not paste the key into source files.

3. Send the first request

cURL

export URTHEPRODUCT_BASE_URL="https://urtheproduct.com"
export URTHEPRODUCT_API_KEY="your-revealed-key"

curl --fail-with-body --silent --show-error   "$URTHEPRODUCT_BASE_URL/v1/text/generate"   --request POST   --header "Authorization: Bearer $URTHEPRODUCT_API_KEY"   --header "Idempotency-Key: first-request-001"   --header "Content-Type: application/json"   --data '{"input":"Rewrite this description using only the supplied facts.","output_format":"markdown"}'

Server-side JavaScript or TypeScript

// Run on your server, never in a browser component.
const response = await fetch(
  process.env.URTHEPRODUCT_BASE_URL + "/v1/text/generate",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.URTHEPRODUCT_API_KEY}`,
      "Idempotency-Key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      input: "Rewrite this description using only the supplied facts.",
      output_format: "markdown",
    }),
  },
);

const body = await response.json();
if (!response.ok) {
  console.error(body.error.request_id, body.error.code);
  throw new Error(body.error.message);
}
console.log(body.output, body.usage.remaining_units);

Python

import os
import uuid
import requests

response = requests.post(
    os.environ["URTHEPRODUCT_BASE_URL"] + "/v1/text/generate",
    headers={
        "Authorization": "Bearer " + os.environ["URTHEPRODUCT_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
        "input": "Rewrite this description using only the supplied facts.",
        "output_format": "markdown",
    },
    timeout=90,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]}')
print(body["output"])
print("remaining units:", body["usage"]["remaining_units"])

4. Read the success response

{
  "id": "usage-event-id",
  "object": "generation",
  "operation": "text.generate",
  "output": { "text": "Normalized engine output" },
  "usage": { "charged_units": 1, "remaining_units": 199 }
}

output is normalized for the engine operation. charged_units is the amount settled for this successful request; remaining_units is the key balance after settlement.

5. Production checklist

• Create a new idempotency key for each new user action.
• Reuse the original key on timeouts and network retries.
• Set an application timeout appropriate to the engine and keep the error body.
• Log only request_id, operation, status, and safe application metadata—never the bearer key or private input.
• Handle every documented non-2xx status instead of assuming every failure is retryable.
• Keep generated file URLs private; they expire and must not be treated as permanent storage.