# API overview

> Base URL, authentication, request and response formats, the job flow and the OpenAPI description of the Solvecha API.

The Solvecha API is a JSON API over HTTPS. It follows the NopeCHA recognition API.

| | |
|---|---|
| Base URL | `https://api.solvecha.com` |
| Authentication | `Authorization: Bearer YOUR_API_KEY`. See [Authentication](https://solvecha.com/docs/authentication.md). |
| Request bodies | JSON, or url-encoded form data. Multipart is not supported. Up to 4.5 MB. |
| Answers | JSON |
| OpenAPI | [`https://solvecha.com/openapi.json`](https://solvecha.com/openapi.json) (OpenAPI 3.1) |

## The job flow

Every captcha type works the same way:


1. `POST /v1/recognition/<type>` with the pictures. The answer is a job id: `{"data": "1234567"}`.
2. `GET /v1/recognition/<type>?id=<job id>`. While the job runs, the answer is error `14` with HTTP status `409`. Poll about once per second, for up to about 30 seconds.
3. When the job is ready, the `GET` request returns `{"data": ...}`. The first answer you fetch counts against your daily quota. Fetching it again is free.


The `<type>` is one of `recaptcha`, `textcaptcha`, `geetest`, `funcaptcha` and `funcaptcha_match`.

## Endpoints

| Method and path | Purpose |
|---|---|
| [`POST /v1/recognition/recaptcha`](https://solvecha.com/docs/api/create-recaptcha-job.md) | Create a reCAPTCHA grid job |
| [`POST /v1/recognition/textcaptcha`](https://solvecha.com/docs/api/create-text-captcha-job.md) | Create a text captcha job |
| [`POST /v1/recognition/geetest`](https://solvecha.com/docs/api/create-geetest-job.md) | Create a GeeTest slider job |
| [`POST /v1/recognition/funcaptcha`](https://solvecha.com/docs/api/create-funcaptcha-job.md) | Create a FunCAPTCHA tile job |
| [`POST /v1/recognition/funcaptcha_match`](https://solvecha.com/docs/api/create-funcaptcha-match-job.md) | Create a FunCAPTCHA match job |
| [`GET /v1/recognition/{type}`](https://solvecha.com/docs/api/get-job-result.md) | Fetch the answer of a job |
| [`GET /v1/status`](https://solvecha.com/docs/api/get-status.md) | Plan and quota of your key |
| [`POST /v1/feedback`](https://solvecha.com/docs/api/send-feedback.md) | Report whether Google accepted an answer (optional) |
| [`POST /`](https://solvecha.com/docs/api/legacy-create-job.md) | Legacy: create a job, `type` in the body |
| [`GET /`](https://solvecha.com/docs/api/legacy-get-job-result.md) | Legacy: fetch the answer, `?id=` |
| [`GET /status`](https://solvecha.com/docs/api/legacy-get-status.md) | Legacy: status |

## Errors

Errors on the `/v1` paths have the HTTP status of the error and this body:

```json
{"error": 14, "code": 14, "message": "Incomplete job", "type": null}
```

The legacy paths answer errors with HTTP status 200 and this body:

```json
{"error": 14, "message": "Incomplete job"}
```

See [Errors](https://solvecha.com/docs/errors.md) for all codes.

## Limits

- The body of a create request is limited to 4.5 MB.
- Create, poll and status requests are rate limited per key. See [Rate limits and quotas](https://solvecha.com/docs/rate-limits.md).
- Only successful answers count against your daily quota.

## Use the OpenAPI file

Import `https://solvecha.com/openapi.json` into Postman, Insomnia, Bruno or a code generator. The file describes every endpoint on this page group, with parameters, answers and error responses.