# MacStrong API

Document & asset engine for AI agents and developers. Generate PDFs and convert PDFs to images.

## Base URL

`https://api.macstrong.net`

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

Get an API key at https://macstrong.net (free tier: 1,000 credits/month, 10 credits per request = 100 requests).

## Endpoints

### POST /pdf

Generate a PDF from HTML.

```bash
curl -X POST https://api.macstrong.net/pdf \
  -H "Authorization: Bearer ms_your_key" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello</h1><p>World</p>","options":{"format":"A4"}}'
```

**Body:**
- `html` (string, required) — HTML content
- `options.format` — A4, A3, A5, Letter, Legal
- `options.margin` — `{ top, right, bottom, left }` in mm
- `options.landscape` — boolean
- `options.printBackground` — boolean (default: true)
- `options.scale` — 0.1–2.0
- `options.headerTemplate` / `options.footerTemplate` — HTML
- `action` — output action (see below)

**Response:** Binary PDF (Content-Type: application/pdf) with default action.

### POST /pdf-to-img

Convert a PDF to images.

```bash
curl -X POST https://api.macstrong.net/pdf-to-img \
  -H "Authorization: Bearer ms_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/doc.pdf","options":{"format":"png","pages":"1"}}'
```

**Body:**
- `url` (string) — URL to PDF (provide url OR data)
- `data` (string) — base64-encoded PDF
- `options.format` — png or jpeg (default: png)
- `options.pages` — e.g. "1", "1-3", "1,3,5" (default: all)
- `options.scale` — scale factor (default: 2.0)
- `action` — output action (see below)

**Response:** JSON with base64 images per page.

## Actions

Control output delivery via the `action` field:

**Return (default):** Result in response body.
```json
{ "action": { "name": "return" } }
```

**Upload:** PUT result to a pre-signed URL (S3, R2, GCS, etc).
```json
{ "action": { "name": "upload", "url": "SIGNED_URL" } }
```

## Credits

- 10 credits per request
- Free: 1,000 credits/month (100 requests)
- Pro ($19/mo): 5,000 credits
- Scale ($99/mo): 50,000 credits

## Errors

JSON: `{"success": false, "error": "message"}`

| Status | Meaning |
|--------|---------|
| 400 | Bad request / missing params |
| 401 | Invalid or missing API key |
| 429 | Credit limit exceeded |
| 500 | Server error |