> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endprompt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Making Requests

> How to call your Endprompt endpoints

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:

```json theme={null}
{
  "text": "The content to process",
  "max_length": 100,
  "options": {
    "format": "bullets"
  }
}
```

## Complete Request Example

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

## Response Format

### Success Response

```json theme={null}
{
  "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:

```bash theme={null}
curl -X POST "https://acme.api.endprompt.ai/api/v1/summarize?prompt=detailed-summary" \
  -H "x-api-key: ep_live_xxxxxxxxxxxxxxxxxxxx" \
  -d '{"text": "..."}'
```

<Note>
  Only Live prompts can be specified via the API. Draft prompts are test-only.
</Note>

### Bypassing Cache

Force a fresh LLM call even if cached:

```bash theme={null}
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:

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

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

### Image Generation Responses

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "error": "validation_error",
  "message": "Field 'text' is required",
  "field": "text"
}
```

### Type Validation

If a field has the wrong type:

```json theme={null}
{
  "error": "validation_error",
  "message": "Field 'max_length' must be an integer",
  "field": "max_length"
}
```

### Constraint Validation

If a value violates constraints:

```json theme={null}
{
  "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

<Tip>
  Set appropriate timeouts in your HTTP client. For most requests, 30-60 seconds is sufficient.
</Tip>

## 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

<AccordionGroup>
  <Accordion title="Handle errors gracefully" icon="shield-check">
    Always check for error responses and handle them appropriately.
  </Accordion>

  <Accordion title="Set reasonable timeouts" icon="clock">
    Configure your HTTP client with appropriate timeout values.
  </Accordion>

  <Accordion title="Log request IDs" icon="file-lines">
    Save the `X-Request-Id` header for debugging support requests.
  </Accordion>

  <Accordion title="Respect rate limits" icon="gauge">
    Check rate limit headers and implement backoff when approaching limits.
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Code Examples" icon="code" href="/api/code-examples">
    Complete examples in multiple languages
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api/error-handling">
    Understand error responses
  </Card>
</CardGroup>