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

# API reference

> Base URL, Bearer authentication, the response envelope, status codes, and the async job model of the Importly REST API.

The REST API is what the MCP server uses under the hood, and what your app calls in production. Every endpoint page here has a **Try it** button that sends a real request with your key.

> [!WARNING]
>
> **Try it** runs real jobs and spends real credits. An import costs at least \$0.03. Status checks and `GET /balance` are free.

## Base URL

```text theme={null}
https://api.importly.io
```

## Authentication

Send your API key as a Bearer token on every request. Get it from the [API key page](https://www.importly.io/dashboard/api-key), and keep it on your server.

```bash theme={null}
curl https://api.importly.io/balance \
  -H "Authorization: Bearer $IMPORTLY_API_KEY"
```

## Responses

Every response uses the same envelope. On success:

```json theme={null}
{ "success": true, "data": { "jobId": "a824760e-ece1-4415-8838-ce2a7785ea6b", "status": "queued" } }
```

On failure, with the HTTP status set to match:

```json theme={null}
{ "success": false, "error": "Missing required parameter: url" }
```

| Status | Meaning |
| - | - |
| `200` | Success. For a job, it was accepted, not finished |
| `400` | A parameter is missing or invalid |
| `401` | The API key is missing or invalid |
| `402` | Your balance is too low to start the job |
| `404` | No job with that ID |
| `429` | Rate limited. Wait `retryAfter` seconds |
| `500` | Server error. Retry with backoff |

More detail, and every rate limit, is on [Errors & rate limits](/docs/error-handling.md).

## Jobs are async

**1. Start a job**

`POST /import`, `/transcribe`, `/metadata`, or `/metadata/basic` returns a `jobId` immediately.

**2. Wait for the result**

Pass `webhookUrl` and Importly POSTs the result to you when the job succeeds, with the fields directly on `data`. Or poll the matching `/status?id=` endpoint every few seconds, where the fields are under `result`.

**3. Handle failures**

A failed job has `status: "failed"`, a `message`, and usually a `code`. Failed jobs don't send webhooks, so keep polling as a fallback.

## Limits

Limits apply per API key, per hour: 240 imports, 240 transcriptions, 1,000 metadata requests, 3,600 status checks per job type, and 600 balance checks. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `X-RateLimit-Window` headers.

## OpenAPI spec

The full spec is at [`/docs/openapi.yaml`](https://www.importly.io/docs/openapi.yaml). Point a client generator or your coding agent at it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.