# API introduction

> Base URL, authentication, rate limits and errors for the Hiresweep REST API.

The Hiresweep API lets you read and change your resumes, track job applications, run job searches and start applications from your own code. Every endpoint in this reference is generated from the live OpenAPI specification.

## Base URL

```text
https://hiresweep.com/api/openapi
```

The specification itself is at `https://hiresweep.com/api/openapi/spec.json`.

## Authentication

Send an API key in the `x-api-key` header. Create one in **Settings → Developers → API keys**. A key has full access to your account, so keep it secret.

```bash
curl https://hiresweep.com/api/openapi/resumes \
  -H "x-api-key: $HIRESWEEP_API_KEY"
```

See [Using the API](https://docs.hiresweep.com/guides/using-the-api) for creating keys and a walkthrough. To connect an AI assistant with limited permissions instead of a key, use the [MCP server](https://docs.hiresweep.com/guides/using-the-mcp-server).

## Rate limits

| Requests                       | Limit                  |
| ------------------------------ | ---------------------- |
| Any request with an API key    | 1,000 an hour per key  |
| AI endpoints                   | 20 a minute            |
| Resume changes                 | 300 a minute           |
| PDF export                     | 5 a minute             |

Requests over a limit are refused until the window resets, so wait and retry. When a key goes over its hourly limit, requests with it return `401` as if the key were missing.

## Errors

Errors return a JSON body with a `code` and a `message`. Common codes:

| HTTP  | Code                                                                      | Meaning                                              |
| ----- | ------------------------------------------------------------------------- | ---------------------------------------------------- |
| `401` | `UNAUTHORIZED`                                                            | The API key is missing, wrong, expired or over its hourly limit. |
| `402` | `AI_LIMIT_REACHED`, `APPLY_LIMIT_REACHED`, `DISCOVERY_LIMIT_REACHED`      | Your plan's allowance is used up. See [Plans and usage](https://docs.hiresweep.com/guides/plans-and-usage). |
| `403` | `EMAIL_NOT_VERIFIED`                                                      | Verify your email address before using this feature. |
| `404` | `NOT_FOUND`                                                               | The resource doesn't exist or isn't yours.           |
| `409` | `RESUME_VERSION_CONFLICT`                                                 | The resume changed since you read it. See [Using the Patch API](https://docs.hiresweep.com/guides/using-the-patch-api). |