# Getting Started

The public DocuShell API is a queued job system: submit work, keep the returned `job_id`, poll status, then stream the finished file or artifact.

Source: https://docs.docushell.com/getting-started
Category: Overview
Read time: 3 min

## Related

- [Parse PDF reference](/parse-pdf.md): File upload, parser fields, batch parse, artifacts, and parse-specific failures.
- [Authentication](/authentication.md): Bearer headers, API key handling, and idempotent retries.
- [Error codes](/error-codes.md): Typed errors, status codes, and retry guidance.

## Summary

| Label | Value | Description |
| --- | --- | --- |
| Base URL | https://api.docushell.com/api | Append `/v1/...` paths to call public API routes. |
| Auth | Bearer API key | Send `Authorization: Bearer YOUR_API_KEY` on submit, status, and download routes. |
| Job flow | submit, poll, download | Most routes return `202` with a `job_id`; completed files are streamed through the gateway. |

## Quickstart Checklist

Use this page to make one working API call. Endpoint-specific options live in each reference page.

Start with Markdown to PDF because it is a small JSON request and still exercises the full queued job lifecycle.

- **Create an API key** in the dashboard Developer tab. The raw key is shown once.
- **Send bearer auth** with `Authorization: Bearer YOUR_API_KEY` on every public API route.
- **Add `Idempotency-Key`** on submit requests when callers may retry after a timeout.
- **Store `job_id` and `request_id`** from the queued response. Use `request_id` when debugging with support.
- **Poll before download**. The download link is valid after the job reaches `done`.

> Keep API keys in server-side code, workers, CI, or trusted automation. Do not ship them in browser bundles.

## First Request

Submit a tiny Markdown document and save the returned `job_id`.

### 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"
  }'
```

## Queued Job Lifecycle

A successful submit returns `202` immediately. The worker finishes the file asynchronously.

### Queued response

```json
{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 5,
  "service": "markdown-to-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}
```

Do not assume the file is ready when this response arrives. Poll the status link first.

### Poll status

```bash
curl "https://api.docushell.com/api/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Done response

```json
{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "done",
  "service": "markdown-to-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "result": {
    "filename": "quickstart.pdf",
    "sizeBytes": 184322,
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  },
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}
```

### Download result

```bash
curl "https://api.docushell.com/api/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output quickstart.pdf
```

Downloads are one-time streams where applicable. Fetch the artifact only after the job is terminal.

## Request Basics

These fields apply across the public API unless an endpoint page says otherwise.

| Item | Required | Notes |
| --- | --- | --- |
| Authorization | Yes | Bearer API key. Send on submit, status, and download requests. |
| Idempotency-Key | Recommended | Use a fresh value for each logical submit. Reuse it only for the exact same retry. |
| Content-Type | Depends | `application/json` for JSON routes; `multipart/form-data` for file uploads. |
| job_id | Response | Store it after submit and poll `GET /v1/jobs/:jobId`. |
| request_id | Response | Trace id returned in JSON and `x-request-id`; include it in support reports. |

## Common Error Envelope

Errors are typed and include a request identifier.

### Error response

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}
```

The same `request_id` is also returned in the `x-request-id` response header for easier tracing.

## Common First-Run Errors

| Status | Code | Fix |
| --- | --- | --- |
| 401 | invalid_api_key | Check the bearer token, key status, and account API access. |
| 409 | idempotency_key_reused | Use a new key when the payload changes. |
| 429 | rate_limit_exceeded | Back off and retry after the documented window. |
| 503 | server_busy | Retry later with the same `Idempotency-Key` only for the same request. |

## Next Steps

Move from the generic job flow to the endpoint you plan to ship.

- [Parse PDF](/parse-pdf.md): Use `/v1/parse` for structured JSON, Markdown, text, HTML, annotated PDF, and batch parse workflows.
- [Resume Parse](/resume-parse.md): Use `/v1/resume/parse` for ATS-oriented candidate, contact, skills, experience, and confidence fields.
- [Playgrounds](/playgrounds.md): Inspect sample output or run Parse and Resume Parse with your own API key.