# Welcome, Developer

## Overview

The OCR API lets you submit images and receive extracted text back. All requests are handled asynchronously. You submit an image, receive a `task_id`, and poll for the result.

{% hint style="info" %}
You will need a valid API key to use any endpoint. Contact your administrator to obtain one.
{% endhint %}

## Authentication

Every request requires your API key as a query parameter:

```
?api=YOUR_API_KEY
```

## Endpoints

### Check Balance

<mark style="color:green;">`GET`</mark> `/api/balance`

Returns your remaining solve credits and usage in the last 24 hours.

**Query Parameters**

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `api`     | string | ✅ Yes    | Your API key |

**Example Request**

```http
GET /api/balance?api=YOUR_API_KEY
```

**Example Response**

```json
{
  "status": "ok",
  "solves": 950,
  "24h": 50
}
```

**Response Fields**

| Field    | Type    | Description                                |
| -------- | ------- | ------------------------------------------ |
| `status` | string  | `"ok"` if the request succeeded            |
| `solves` | integer | Total solve credits remaining              |
| `24h`    | integer | Number of solves used in the last 24 hours |

### Submit Image for OCR

<mark style="color:blue;">`POST`</mark> `/api/ocr/solve`

Upload an image to be processed. Returns a `task_id` to use when polling for the result.

**Query Parameters**

| Parameter | Type   | Required | Description  |
| --------- | ------ | -------- | ------------ |
| `api`     | string | ✅ Yes    | Your API key |

**Request Body**

| Field   | Type | Required | Description                      |
| ------- | ---- | -------- | -------------------------------- |
| `image` | file | ✅ Yes    | Image file (multipart/form-data) |

{% hint style="info" %}
Common formats like PNG, JPG, and BMP are supported.
{% endhint %}

**Example Request**

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://<host>/api/ocr/solve?api=YOUR_API_KEY" \
     -F "image=@/path/to/your/image.png"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

with open("image.png", "rb") as f:
    response = requests.post(
        "https://<host>/api/ocr/solve",
        params={"api": "YOUR_API_KEY"},
        files={"image": f}
    )

data = response.json()
task_id = data["task_id"]
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const form = new FormData();
form.append("image", fileInput.files[0]);

const response = await fetch("/api/ocr/solve?api=YOUR_API_KEY", {
  method: "POST",
  body: form,
});

const { task_id } = await response.json();
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "ok",
  "result": "in_process",
  "task_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "solves": 949
}
```

**Response Fields**

| Field     | Type    | Description                             |
| --------- | ------- | --------------------------------------- |
| `status`  | string  | `"ok"` if the task was accepted         |
| `result`  | string  | `"in_process"` while OCR is running     |
| `task_id` | string  | Use this to retrieve your result        |
| `solves`  | integer | Remaining credits after this submission |

{% hint style="warning" %}
One solve credit is deducted per successful OCR completion. Tasks and uploaded images are automatically deleted after **30 seconds** — retrieve your result promptly.
{% endhint %}

### Get OCR Result

<mark style="color:green;">`GET`</mark> `/api/ocr/result/{task_id}`

Poll this endpoint with the `task_id` from the submit step to retrieve your OCR result.

**Path Parameters**

| Parameter | Type   | Required | Description                                   |
| --------- | ------ | -------- | --------------------------------------------- |
| `task_id` | string | ✅ Yes    | The task ID returned from the submit endpoint |

**Example Request**

```http
GET /api/ocr/result/d290f1ee-6c54-4b01-90e6-d701748f0851
```

**Example Responses**

{% tabs %}
{% tab title="In Progress" %}

```json
{
  "status": "ok",
  "result": "in_process",
  "task_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "time": null,
  "solves": 949
}
```

{% endtab %}

{% tab title="Completed" %}

```json
{
  "status": "ok",
  "result": "Hello, this is the extracted text from the image.",
  "task_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "time": 1.23,
  "solves": 949
}
```

{% endtab %}

{% tab title="Failed" %}

```json
{
  "status": "fail",
  "result": "subprocess_timed_out",
  "task_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "time": null,
  "solves": 949
}
```

{% endtab %}
{% endtabs %}

**Response Fields**

| Field     | Type    | Description                                             |
| --------- | ------- | ------------------------------------------------------- |
| `status`  | string  | `"ok"` for success, `"fail"` if something went wrong    |
| `result`  | string  | Extracted text, `"in_process"`, or an error message     |
| `task_id` | string  | The task identifier                                     |
| `time`    | float   | Processing time in seconds (`null` if not yet complete) |
| `solves`  | integer | Your remaining credits                                  |

{% hint style="info" %}
Poll every 1–2 seconds until `result` is no longer `"in_process"`. Tasks expire after **30 seconds** — after that, this endpoint returns `404 Not Found`.
{% endhint %}

## Error Reference

| HTTP Status | Detail                      | Meaning                                                  |
| ----------- | --------------------------- | -------------------------------------------------------- |
| `401`       | `Invalid API key`           | Your API key is wrong or does not exist                  |
| `402`       | `No solves remaining`       | You have run out of credits — contact your administrator |
| `404`       | `Task not found or expired` | The task has expired (30s limit) or the ID is incorrect  |

## Quick Start

Here's the typical end-to-end flow:

{% stepper %}
{% step %}

### Step 1 — Check your balance

```http
GET /api/balance?api=YOUR_KEY
```

{% endstep %}

{% step %}

### Step 2 — Submit your image

```bash
curl -X POST "/api/ocr/solve?api=YOUR_KEY" -F "image=@image.png"
# Save the returned task_id
```

{% endstep %}

{% step %}

### Step 3 — Poll for the result

```bash
curl "/api/ocr/result/{task_id}"
# Repeat every 1-2 seconds until result != "in_process"
```

{% endstep %}

{% step %}

### Step 4 — Use the extracted text

The OCR output will be in the `result` field of the response.
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.solvora.xyz/welcome-developer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.