Endpoint reference

Text generation

POST /v1/text/generate · Synchronous

This route accepts strict JSON. Unknown fields, malformed values, wrong-operation keys, and package settings outside the locked configuration are rejected before provider execution.

Required headers

Header	Value	Notes
`Authorization`	`Bearer $URTHEPRODUCT_API_KEY`	Required. Must be sent from a trusted server.
`Idempotency-Key`	8–128 safe characters	Required on POST. Reuse only for retries of the same logical request.
`Content-Type`	`application/json`	Required on POST.

Request fields

Field	Type	Required	Rules
`input`	string	Yes	1–64,000 characters; the source material or task.
`context`	string	No	Up to 16,000 characters of relevant supplied context.
`output_format`	enum	No	text, markdown, or json; must match locked package settings.

Request example

curl "https://urtheproduct.com/v1/text/generate" \
+  -X POST \
+  -H "Authorization: Bearer $URTHEPRODUCT_API_KEY" \
+  -H "Idempotency-Key: logical-request-001" \
+  -H "Content-Type: application/json" \
+  -d '{  "input": "Facts: Acme mug, 350 ml, ceramic. Write a concise description.",  "context": "Do not add claims that are not supplied.",  "output_format": "markdown"}'

{
  "input": "Facts: Acme mug, 350 ml, ceramic. Write a concise description.",
  "context": "Do not add claims that are not supplied.",
  "output_format": "markdown"
}

Success response

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

Operation-specific behavior

Token and output-structure limits are enforced by the purchased engine.
JSON output is still untrusted input to your application and must be schema-validated.

Failures and retries

Schema failures return 422 validation_error without charging quota. Wrong scope returns 403 forbidden. Rate/concurrency pressure returns 429 rate_limited. Provider safety pauses return 503 provider_unavailable. Follow the error and retry table and reuse the same idempotency key for the same logical request.