Skip to main content
This page covers the HTTP request format for calling your endpoints.

​
Request Format

​
URL Structure

POST https://{tenant}.api.endprompt.ai{endpoint-path}
ComponentDescriptionExample
{tenant}Your tenant subdomainacme
{endpoint-path}Your endpoint path/api/v1/summarize
Full example: 
POST https://acme.api.endprompt.ai/api/v1/summarize

​
Required Headers

HeaderValueDescription
Content-Typeapplication/jsonRequest body format
x-api-keyYour API keyAuthentication

​
Request Body

JSON object matching your endpoint’s input schema: 
{
  "text": "The content to process",
  "max_length": 100,
  "options": {
    "format": "bullets"
  }
}

​
Complete Request Example

curl -X POST https://acme.api.endprompt.ai/api/v1/summarize \
  -H "Content-Type: application/json" \
  -H "x-api-key: ep_live_xxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "text": "Endprompt is a platform for building LLM-powered APIs...",
    "max_length": 100
  }'

​
Response Format

​
Success Response

{
  "summary": "Endprompt enables teams to build production-ready LLM APIs with versioning and schema validation.",
  "word_count": 15
}
The response matches your endpoint’s output schema (if defined) or returns the raw LLM output.

​
Response Headers

HeaderDescription
X-Request-IdUnique request identifier for debugging
X-RateLimit-LimitYour rate limit
X-RateLimit-RemainingRequests remaining
X-RateLimit-ResetWhen limit resets (Unix timestamp)

​
Request Options

​
Specifying a Prompt

By default, requests use the endpoint’s default prompt. To use a specific prompt: 
curl -X POST "https://acme.api.endprompt.ai/api/v1/summarize?prompt=detailed-summary" \
  -H "x-api-key: ep_live_xxxxxxxxxxxxxxxxxxxx" \
  -d '{"text": "..."}'
Only Live prompts can be specified via the API. Draft prompts are test-only.

​
Bypassing Cache

Force a fresh LLM call even if cached: 
curl -X POST https://acme.api.endprompt.ai/api/v1/summarize \
  -H "x-api-key: ep_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "x-cache-bypass: true" \
  -d '{"text": "..."}'

​
Input Validation

Requests are validated against your input schema before processing.

​
Required Fields

If a required field is missing: 
{
  "error": "validation_error",
  "message": "Field 'text' is required",
  "field": "text"
}

​
Type Validation

If a field has the wrong type: 
{
  "error": "validation_error",
  "message": "Field 'max_length' must be an integer",
  "field": "max_length"
}

​
Constraint Validation

If a value violates constraints: 
{
  "error": "validation_error",
  "message": "Field 'max_length' must be between 10 and 1000",
  "field": "max_length"
}

​
Timeouts

Default timeout is 60 seconds. For long-running requests:
  • The connection stays open until the LLM responds
  • Very complex prompts may take 30-60 seconds
  • If timeout is exceeded, you’ll receive a 504 error
Set appropriate timeouts in your HTTP client. For most requests, 30-60 seconds is sufficient.

​
Idempotency

Endprompt requests are not idempotent by default. Each request:
  • Triggers a new LLM call (unless cached)
  • Is logged separately
  • Consumes tokens from the LLM provider
If you need idempotency, use caching with consistent input data.

​
Best Practices

Always check for error responses and handle them appropriately.
Configure your HTTP client with appropriate timeout values.
Save the X-Request-Id header for debugging support requests.
Check rate limit headers and implement backoff when approaching limits.

​
Finding Your Endpoint URL

  1. Open your endpoint in the dashboard
  2. Go to the OpenAPI tab
  3. Your full URL is shown at the top
  4. Code samples are provided in multiple languages

​
Next Steps

Code Examples

Complete examples in multiple languages

Error Handling

Understand error responses