Making Requests - Endprompt

This page covers the HTTP request format for calling your endpoints.

Request Format

URL Structure

POST https://{tenant}.api.endprompt.ai{endpoint-path}

Component	Description	Example
`{tenant}`	Your tenant subdomain	`acme`
`{endpoint-path}`	Your endpoint path	`/api/v1/summarize`

Full example:

POST https://acme.api.endprompt.ai/api/v1/summarize

Required Headers

Header	Value	Description
`Content-Type`	`application/json`	Request body format
`x-api-key`	Your API key	Authentication

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

const response = await fetch('https://acme.api.endprompt.ai/api/v1/summarize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'ep_live_xxxxxxxxxxxxxxxxxxxx'
  },
  body: JSON.stringify({
    text: 'Endprompt is a platform for building LLM-powered APIs...',
    max_length: 100
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://acme.api.endprompt.ai/api/v1/summarize',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'ep_live_xxxxxxxxxxxxxxxxxxxx'
    },
    json={
        'text': 'Endprompt is a platform for building LLM-powered APIs...',
        'max_length': 100
    }
)

data = response.json()
print(data)

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

Header	Description
`X-Request-Id`	Unique request identifier for debugging
`X-RateLimit-Limit`	Your rate limit
`X-RateLimit-Remaining`	Requests remaining
`X-RateLimit-Reset`	When 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.

Image Inputs

For endpoints with image input fields, send images as base64 data URIs in the JSON body:

{
  "photo": "data:image/png;base64,iVBORw0KGgo...",
  "instructions": "Describe what you see in this image"
}

Content-Type remains application/json — no multipart form data needed. Images are embedded as base64 data URI strings.

Image Generation Responses

When an endpoint generates images (has image output fields), the response includes a generatedImages array instead of standard JSON output fields:

{
  "generatedImages": [
    {
      "base64Data": "iVBORw0KGgo...",
      "revisedPrompt": "A photorealistic product shot of..."
    }
  ],
  "usage": {
    "inputTokens": 120,
    "outputTokens": 4096
  }
}

Decode the base64Data to get the raw image bytes (typically PNG format).

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

Handle errors gracefully

Always check for error responses and handle them appropriately.

Set reasonable timeouts

Configure your HTTP client with appropriate timeout values.

Log request IDs

Save the X-Request-Id header for debugging support requests.

Respect rate limits

Check rate limit headers and implement backoff when approaching limits.

Finding Your Endpoint URL

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

Next Steps

Code Examples

Complete examples in multiple languages

Error Handling

Understand error responses

​Request Format

​URL Structure

​Required Headers

​Request Body

​Complete Request Example

​Response Format

​Success Response

​Response Headers

​Request Options

​Specifying a Prompt

​Bypassing Cache

​Input Validation

​Image Inputs

​Image Generation Responses

​Required Fields

​Type Validation

​Constraint Validation

​Timeouts

​Idempotency

​Best Practices

​Finding Your Endpoint URL

​Next Steps

Code Examples

Error Handling

Request Format

URL Structure

Required Headers

Request Body

Complete Request Example

Response Format

Success Response

Response Headers

Request Options

Specifying a Prompt

Bypassing Cache

Input Validation

Image Inputs

Image Generation Responses

Required Fields

Type Validation

Constraint Validation

Timeouts

Idempotency

Best Practices

Finding Your Endpoint URL

Next Steps