# INI Opt — agent integration guide

Contract version: 1.3.2 (API v1). Last reviewed: 2026-09-24.

## Changes in contract 1.3.2

Multipart filenames now default to UTF-8 decoding, preserving Cyrillic and other Unicode names in job responses and activity. Send ordinary `filename` parameters as UTF-8; explicitly encoded extended parameters continue to follow their declared charset. Individual downloads include a UTF-8 `filename*` parameter in Content-Disposition. ZIP entries preserve Unicode letters, numbers, combining marks and spaces, replacing unsafe/unsupported punctuation with underscores. ZIP names remain prefixed with a sequence number and use the actual output extension. No new request fields or endpoints are required.

## Changes in contract 1.3.1

PNG output now receives an additional lossless OxiPNG optimization pass. No new request fields or endpoints are required. The service keeps the smaller encoded candidate, then applies the existing safe original-PNG reuse rule. All decoded pixel values, including transparency and hidden RGB values, are preserved by this additional pass. Resizing and the existing color-space conversion can still change pixels before encoding. Metadata removal remains enabled.

The additional pass is best-effort: outputs up to 16 million pixels and 64 MiB of encoded data are eligible, with a 10-second limit. Larger images, timeout, or optimizer failure use the existing Sharp PNG output. The overall input limit remains 40 megapixels / 25 MiB. Quality does not affect PNG; target size remains best-effort. Always use the returned byte counts and `target_met`; file-size reductions are not guaranteed.

## Changes in contract 1.3.0

`preserve_transparency` now defaults to `auto` (also used when omitted or empty). Protection activates only for PNG inputs that actually contain transparent or translucent pixels. An opaque PNG, even with an alpha channel, does not trigger it; neither do JPEG, WebP or AVIF inputs. When protection applies to a JPEG request, output becomes PNG. The dashboard starts unchecked and checks itself when a selected transparent PNG is detected; removing/clearing those files resets it. Mixed batches use auto detection per file.

Explicit `true` and `false` remain supported as manual overrides. True protects all inputs with an alpha channel, as before; false permits JPEG flattening onto white. PNG/WebP/AVIF outputs continue to retain transparency inherently. Inspect `result.format`. Metadata removal is unchanged.

## Changes in contract 1.2.0

Per-product activity history is now available at `GET /api/v1/activity` with the same bearer key. It covers only that product, defaults to 50 events per page (limit 1–100), and uses `before=<next_cursor>` for older events. `next_cursor: null` means no more retained events.

Events record key creation/revocation, image submission/settings, processing start/completion/failure, requeue, file expiry, downloads/previews/ZIP transfers, and authenticated product-request failures or disconnects. Successful status polling is omitted to avoid noise. Timestamps are Unix milliseconds. `download.sent` records a finished server response, not proof of permanent storage by the caller. Unknown/revoked credentials are not attributed to a product.

History is retained for 90 days independently of 24-hour file expiry. No requests from before this update are reconstructed. Logs contain operational metadata including filenames, job IDs, sizes, settings and errors, but never API secrets, authorization headers or image content. Treat filenames and errors as private product data. Event details vary by type; tolerate unknown future event types.

The administrator can open **Product access → View activity** for any product, including revoked keys. The dashboard-only endpoint is `GET /api/keys/{id}/activity` (session required; same pagination). Product keys cannot access this endpoint or another product’s logs. “Last request” records the latest authenticated request by that product key; dashboard views do not update it.

## Changes in contract 1.1.0

- No preset is now the default in both the dashboard and API: original format, original dimensions, quality 82. To retain the former implicit WebP/1600px behavior, explicitly send `preset=product-photo`.
- `resize_percent` scales dimensions relative to each image after EXIF orientation. `70` means 70% of original width (30% smaller), `50` means half width and height. This is not a byte-size reduction guarantee. Width rounds to the nearest pixel, minimum 1; height follows aspect ratio. It overrides preset width. Supplying it with an explicit positive `width` returns 400.
- In contract 1.1.0, `preserve_transparency=true` was the default (changed to `auto` in 1.3.0). PNG/WebP/AVIF retain alpha. If JPEG is requested for an input with an alpha channel, the output becomes PNG. Set false to permit JPEG flattening onto white; always inspect `result.format`.
- `progressive_jpeg=true` by default. False selects baseline JPEG. Ignored for non-JPEG output. Multipart boolean values must be `true` or `false`.
- New jobs report `result.has_alpha` and `result.progressive_jpeg` (null for non-JPEG). These fields may be absent on older persisted jobs.
- EXIF/GPS and other source metadata are always stripped; no privacy toggle is necessary.

## Start here

- Documentation index: https://opt.iniapp.com/docs/
- OpenAPI 3.0.3 JSON: https://opt.iniapp.com/docs/openapi.json
- This guide: https://opt.iniapp.com/docs/integration.md
- Discovery: https://opt.iniapp.com/llms.txt
- Service origin: `https://opt.iniapp.com`
- Product API base: `https://opt.iniapp.com/api/v1`

Documentation and health are readable without credentials. All product API operations require a dedicated product key. Obtain one from the owner through **Product access** in the dashboard and store it in the integrating backend's secret configuration as `OPT_API_KEY`. Do not ask for administrator credentials, create keys autonomously, commit keys, or place them in frontend code. Documentation contains no usable credentials.

## Integration workflow

1. Read the OpenAPI contract and GET `/api/v1/presets` with your product key.
2. Upload a local image as multipart `file`, plus a preset and any overrides. Do not manually set the multipart Content-Type; let your HTTP library set its boundary. The API accepts bytes, not an image URL.
3. Persist the job ID returned with HTTP 202. Treat it as accepted, not finished.
4. Poll GET `/api/v1/jobs/{id}` initially around once a second, then back off to a few seconds with jitter. Apply a bounded overall deadline appropriate to your workflow; queue time is additional to the 120-second worker deadline.
5. On `completed`, inspect `result.format`, `result.output_bytes`, and `result.target_met`. A completed output may be larger or may miss its target size. Choose whether to use it based on your product requirements.
6. Resolve `download_url` against `https://opt.iniapp.com` (it already begins with `/api/v1/`). Download with the same bearer key. Save bytes in your product's permanent storage before expiry and set the extension/content type from `result.format`.
7. On `failed`, surface the job error and preserve the original. On `expired` or HTTP 410, the output is no longer available; resubmit the retained original only when your workflow requires it.

Run submissions in a bounded background queue. Retry polling/download transport errors with backoff; stop on authentication failures. Respect Retry-After when supplied for 429/503. An upload connection failure can occur after acceptance: do not blindly retry POST, because there is no idempotency key. Save known job IDs and reconcile uncertain submissions where possible. There are no webhooks, cancellation, URL ingestion, or multi-file upload endpoints in v0.1.

## Minimal curl flow

Requires curl and jq. `OPT_API_KEY` must already be set through your backend secret configuration. Use a non-sensitive test image for the first integration.

```bash
OPT_ORIGIN=https://opt.iniapp.com
curl --fail-with-body -sS "$OPT_ORIGIN/api/v1/presets" \
  -H "Authorization: Bearer $OPT_API_KEY"

# Save the response; do not repeat this request just to check its status.
curl --fail-with-body -sS "$OPT_ORIGIN/api/v1/jobs" \
  -H "Authorization: Bearer $OPT_API_KEY" \
  -F 'file=@product.jpg' -F 'preset=product-photo' > job.json
JOB_ID=$(jq -er '.id' job.json)

# Repeat this GET with a bounded polling loop until a terminal status.
curl --fail-with-body -sS "$OPT_ORIGIN/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $OPT_API_KEY" > status.json
jq '{status, error, result, download_url}' status.json

# Only after status is completed; this example used the WebP product-photo preset.
curl --fail-with-body -sS "$OPT_ORIGIN/api/v1/jobs/$JOB_ID/download" \
  -H "Authorization: Bearer $OPT_API_KEY" -o product.webp
```

## Integration acceptance checks

- A supported test image reaches completed and downloads to permanent storage.
- The stored extension and MIME type match the returned format.
- A corrupt image reaches failed without breaking the caller's workflow.
- Missing/revoked keys and unavailable/expired outputs are handled explicitly.
- The caller retains originals, bounds polling/concurrency, and does not duplicate jobs through automatic POST retries.
- Product keys remain server-side; one product cannot retrieve another product's jobs.

## API v1 reference

Base: `https://opt.iniapp.com/api/v1`. Authenticate every request with `Authorization: Bearer <product-key>`. `/healthz` is the unauthenticated health endpoint; `/docs/`, `/docs/openapi.json`, `/docs/integration.md`, and `/llms.txt` are public documentation. Browser sessions can also use the API with their CSRF token for mutations.

| Method | Path | Purpose |
|---|---|---|
| GET | `/presets` | Presets and upload limits |
| POST | `/jobs` | Multipart upload; returns HTTP 202 |
| GET | `/jobs` | Latest 200 accessible jobs |
| GET | `/jobs/{id}` | Job status and output details |
| GET | `/jobs/{id}/download` | Authenticated output attachment |
| GET | `/jobs/{id}/preview/source` | Original image preview for a completed job |
| GET | `/jobs/{id}/preview/output` | Optimized image preview |
| POST | `/archive` | JSON `{ "ids": ["..."] }`, 1–50 ready jobs; streamed ZIP |
| GET | `/archive?ids=id1,id2` | Same archive as a browser-native streaming download |
| GET | `/activity?limit=50&before=123` | Product activity; cursor pagination, 90-day retention |
| GET | `/stats` | Cumulative processed bytes/job counts and current queue |

### Multipart fields

| Field | Values / defaults |
|---|---|
| `file` | Exactly one image, required; JPEG, PNG, WebP, AVIF |
| `preset` | `none` (default), `product-photo`, `thumbnail`, `website-banner`, `keep-format` |
| `format` | `jpeg`, `png`, `webp`, `avif`, `original`; overrides preset |
| `width` | 0–8192; 0 keeps width; never enlarges an image |
| `resize_percent` | 1–100; percentage of oriented original dimensions; overrides preset width, incompatible with positive explicit width |
| `preserve_transparency` | `auto` (default), `true`, `false`; auto protects only PNGs containing transparent pixels; see 1.3.0 behavior above |
| `progressive_jpeg` | `true` (default) / `false`; only affects actual JPEG output |
| `quality` | 1–100; JPEG/WebP/AVIF only; default 82, thumbnail 78 |
| `target_kb` | 0–25000; 0/omitted means no target; one KB = 1024 bytes |

Preset widths: none 0, product-photo 1600, thumbnail 480, website-banner 2400, keep-format 0. Product-photo, thumbnail and website-banner produce WebP by default; none and keep-format retain the source format. No crop is applied; aspect ratio is preserved. JPEG output flattens transparency onto white only when transparency protection is disabled; with protection enabled, alpha inputs requested as JPEG produce PNG instead.

Targets reduce encoder quality in bounded steps (down to 35 unless a lower starting quality was explicitly requested). PNG does not switch to lossy palette quantization. Inspect `result.target_met`; `false` is a successful encode that did not achieve the target, not a promise of compliance. If an output is larger, the source is reused only for a PNG with unchanged dimensions whose chunks contain exclusively pixel/palette/transparency data; otherwise the encoded result and its actual size are returned.

### Job representation

```json
{
  "id": "uuid",
  "filename": "product.jpg",
  "status": "completed",
  "preset": "product-photo",
  "input_bytes": 66443,
  "result": {
    "format": "webp",
    "source_format": "jpeg",
    "width": 1400,
    "height": 900,
    "output_bytes": 11044,
    "input_bytes": 66443,
    "saved_bytes": 55399,
    "quality": 82,
    "kept_original": false,
    "has_alpha": false,
    "progressive_jpeg": null,
    "target_met": null
  },
  "error": null,
  "created": 1790000000000,
  "expires": 1790086400000,
  "download_url": "/api/v1/jobs/uuid/download"
}
```

Timestamps are Unix milliseconds. Status transitions are `queued → processing → completed|failed → expired`. Interrupted processing jobs are requeued on server startup. The worker has a 120-second execution deadline. Poll about once per second, with backoff for long jobs.

Source and output files are deleted after 24 hours (cleanup runs once per minute). Small job records, including filenames, persist for 30 additional days; cumulative usage persists. Download and store output in the calling product before expiry.

### Limits and errors

- 25 MiB per file, 40 million decoded pixels; static images only.
- 50 queued/processing jobs per product; 200 global; eight concurrent uploads; two processing workers. Concurrent requests near the queue limit may temporarily exceed it by the number of in-flight uploads.
- 120 upload submissions per minute per product. Upload admission stops below 2 GiB free disk.
- `400`: invalid request/options or size limit; `401`: authentication; `403`: dashboard-only operation/CSRF; `404`: missing or inaccessible job; `409`: output not ready; `410`: expired; `429`: admission/rate limit; `507`: storage pressure.
- Unsupported or corrupt image contents are reported asynchronously as `status: failed`.
- Retries of POST create new jobs; there is no idempotency key or webhook in v0.1.

API keys can access only their own jobs. Revocation is immediate and does not delete existing data. Create a distinct key per product; never place keys in a frontend bundle. No CORS allowlist is configured because this API is intended for backend integrations.
