# Convert Guru x402 API Documentation

Welcome to Convert Guru. This service provides AI agents and machine-to-machine integrations with payable file-type detection and file conversion APIs.

## API Specification
The API endpoints are described in detail in the [OpenAPI Spec](https://convert.guru/openapi.json) or [OpenAPI Spec (YAML)](https://convert.guru/openapi.yaml).

## General Design
- **Base URL:** `https://convert.guru/api/x402/v1`
- **Protocol:** x402 (HTTP 402 Payment Required). Payments are accepted in USDC on Base Mainnet and Solana Mainnet.
- **Facilitator:** Coinbase CDP Facilitator
- **Developer Wallet:** `0x222c4F009c63E24cE9176C0f7f3b64E7Da0f0699`

## Endpoints

### 1. Health check
- **Endpoint:** `GET /api/x402/v1/health`
- **Pricing:** Free
- **Description:** Verifies service health before executing operations.

### 2. Detect File Type
- **Endpoint:** `POST /api/x402/v1/detect-file-type`
- **Pricing:** 0.002 USDC ($0.002) exact
- **Request Body:** JSON containing:
  - `filename`: Original filename string
  - `size_bytes`: File size integer
  - `header_first_200_bytes_base64`: Base64 string of first 200 bytes of the file
  - `created_at`: Optional file creation time string (ISO 8601)
- **Response:** JSON detailing the detected canonical format, confidence level, and convertible output target extensions.

### 3. Convert File
- **Endpoint:** `POST /api/x402/v1/convert-file`
- **Pricing:** 0.002 USDC ($0.002) exact
- **Request Body:** multipart/form-data containing:
  - `file`: Raw binary file content
  - `target_format`: Desired output extension (e.g., pdf, docx, png)
  - `filename`: Original filename string
  - `size_bytes`: Original file size integer
  - `created_at`: File creation time string (ISO 8601)
- **Response:** JSON returning a `job_id`, `status_url`, and `retry_after_seconds`.

### 4. Poll Conversion Status
- **Endpoint:** `GET /api/x402/v1/convert-file/{job_id}/status`
- **Pricing:** Free
- **Description:** Poll this endpoint until status is `done` or `failed`.
- **Response when done:** Includes `price_for_result` and `result_url` to purchase the conversion result.

### 5. Purchase Result
- **Endpoint:** `GET /api/x402/v1/convert-file/{job_id}/result`
- **Pricing:** Tiered based on input file size:
  - Files <= 10 MB: 0.02 USDC ($0.02)
  - Files > 10 MB and <= 40 MB: 0.04 USDC ($0.04)
- **Response:** JSON returning a short-lived, secure, random `download_url` (valid for 1 hour; backend file cleanup is performed automatically after 24 hours).

### 6. Delete Result
- **Endpoint:** `DELETE /api/x402/v1/convert-file/{job_id}/delete`
- **Pricing:** Free
- **Description:** Deletes the conversion job files immediately. Recommended after a successful download for security and privacy.