# PDF Craft: API access and first request

## Choose the documented interface

PDF Craft's public conversion interface is REST at `https://fusion-api.oomol.com/v1`. The supported operations are PDF-to-Markdown and PDF-to-EPUB submission and result retrieval. Use the [OpenAPI specification](https://pdfcraft.ai/openapi.json) and [API reference](https://pdfcraft.ai/en/api/).

Website translation and internal workspace APIs are separate capabilities. This site does not publish a GraphQL contract. An HTTP 401 from a guessed path does not establish that a GraphQL or MCP service exists there.

## Obtain a credential

1. Sign in to the [OOMOL Console API key page](https://console.oomol.com/api-key).
2. Create a key with a recognizable name. Store the key in a server-side secret manager or environment variable; do not embed it in a browser bundle or source repository.
3. Use `Authorization: Bearer YOUR_API_KEY`. A successful format check is not proof that a key is valid or has enough balance.
4. Review [current pricing](https://pdfcraft.ai/en/pricing/) before submitting a conversion. This guide does not promise anonymous access or a free conversion.

## Run the complete example

Download and inspect the [Python 3 standard-library example](https://pdfcraft.ai/examples/api-quickstart.py). Set `PDF_CRAFT_API_KEY` securely in your environment, then run:

```bash
python3 api-quickstart.py
```

This submits one real conversion and may consume credits. It stores `sessionID` in `pdf-craft-task.json`, polls with bounded backoff for up to ten minutes, downloads `pdf-craft-result.md`, and checks the sample phrase. The state file is created exclusively before submission; an existing state or output file stops a new run. To resume an accepted task without submitting again:

```bash
python3 api-quickstart.py --resume pdf-craft-task.json
```

If submission times out before a task ID is received, the state file records `submission_unknown`. Investigate that request before starting another conversion. The example never retries a submit and never sends your API key to the output download URL.

## Make a first conversion

Use the [one-page integration sample](https://pdfcraft.ai/examples/api-quickstart.pdf). This is an input fixture, not a benchmark or a claimed conversion result.

```bash
# Set PDF_CRAFT_API_KEY securely in your environment before running this command.
curl --fail-with-body --request POST \
  'https://fusion-api.oomol.com/v1/pdf-transform-markdown/submit' \
  --header "Authorization: Bearer ${PDF_CRAFT_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"pdfURL":"https://pdfcraft.ai/examples/api-quickstart.pdf","model":"gundam"}'
```

Save the returned `sessionID`. Query the corresponding result operation with the same credential and that task ID, using bounded backoff. Stop on a terminal state. On completion, download `data.downloadURL` and check for the phrase `Paper to structured text.`. Keep the source for comparison. The [quickstart](https://pdfcraft.ai/en/docs/getting-started/quickstart/) has both request examples.

Do not blindly retry a submit after a timeout: it may have created a task even if you missed its response. A rate-limit request ID used internally is not a public idempotency-key contract.

## Recover from errors

- **401**: missing or invalid credentials. The JSON response contains `code: UNAUTHENTICATED`, `message` and `resolution`; use the Bearer challenge to correct authentication. Repeating the same invalid credential will not help.
- **429**: a rate, quota or concurrency rule rejected the operation. Use bounded backoff with a deadline; do not spin or assume a fixed wait.
- **Other errors**: inspect status and content type before parsing. HTTP errors and a failed conversion task are different states; use the [error guide](https://pdfcraft.ai/en/docs/api/error-handling/).

Honor Retry-After when present. RateLimit-Policy and RateLimit provide optional hints for the evaluated operation, not a guarantee of available capacity. Missing hints do not mean unlimited usage.

## Related services

Website login and other OOMOL services use separate credentials. See the [interface comparison](https://pdfcraft.ai/related-services.md) when choosing an integration. The PDF REST contract above uses a Bearer API Key.