# Public API Gateway

The gateway gives developers one stable API base URL while DocuShell routes work to dedicated processing services behind the scenes.

Source: https://docs.docushell.com/public-api-gateway
Category: Gateway
Read time: 5 min

## Related

- [Getting started](/getting-started.md): Submit a job, poll status, and download the result.
- [Rate Limits](/rate-limits.md): Understand the default 10 requests per minute throttle and retry behavior.
- [Parse playground](/playgrounds/parse): Run the Parse playground with a sample PDF or your own API key.

## Summary

| Label | Value | Description |
| --- | --- | --- |
| Base URL | https://api.docushell.com/api | Append `/v1/...` paths for public API calls. |
| Auth | API Key / JWT bearer | API keys are recommended; JWT support depends on the active deployment. |
| Default rate | 10 req/min | The default limiter is per API key or caller fingerprint unless configured otherwise. |

## Gateway Overview

The critical integration details in one place.

| Topic | Value | Notes |
| --- | --- | --- |
| Base URL | https://api.docushell.com/api | Use with documented `/v1/...` routes. |
| Authentication | Bearer API key; JWT where enabled | Attach to every submit, status, and download request. |
| Rate limit | 10 requests/minute default | Configurable per deployment and enforced before queue handoff. |
| Request formats | JSON and multipart/form-data | JSON for Markdown and URL rendering; multipart for file uploads. |
| Response format | JSON | Queued submits return `job_id`, `request_id`, and status/download links. |
| File retention | Ephemeral | Uploaded and generated files are swept within one hour and downloaded files are deleted after streaming where applicable. |

## Gateway Examples

### First request

```bash
curl -X POST "https://api.docushell.com/api/v1/markdown-to-pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-001" \
  -d '{
    "markdown": "# DocuShell\n\nRendered through the public API.",
    "file_name": "quickstart.md",
    "page_size": "A4"
  }'
```

### Health check

```bash
curl "https://api.docushell.com/api/health"
```

Health checks are for discovery and operations. Public API work still requires bearer auth.

## What The Gateway Handles

- Authentication and request identity.
- Rate limiting before expensive processing begins.
- Validation and request normalization before queueing work.
- Shared `job_id`, `request_id`, status polling, and download routes.
- One-time output streaming while internal services stay private.