# Omniyond

> Pay-per-use utility API for AI agents. The keystone is a scheduler: schedule any HTTP call to run once or on a recurring interval, with automatic retries and delivery to storage or a callback. Pay per call with x402 (USDC on Base) or with prepaid credits — no plan, no subscription.

Base URL: https://omniyond.com
Machine-readable spec: https://omniyond.com/openapi.yaml
MCP endpoint: https://omniyond.com/mcp (Streamable HTTP, POST only)
MCP registry card: https://omniyond.com/.well-known/mcp/server.json

## Authentication (two ways, no account required for agents)

- API key (prepaid credits): send `Authorization: Bearer omni_...`. Buy a credit pack ($9 / $29 / $99, credits never expire); each scheduled run costs $0.01.
- x402 (pay per call): send no key. The API replies `402 Payment Required` with payment requirements in the `payment-required` response header (USDC on Base). Pay, then resend with the `X-PAYMENT` header. No signup, no key. Payments settle on Base mainnet (`eip155:8453`) in USDC.

Every `402` response body links this file and the OpenAPI spec. A request body that fails validation gets a `400` before any charge or `402` challenge.

## Scheduler endpoints

- [POST /v1/schedule](https://omniyond.com/v1/schedule): Schedule an HTTP request. Omit `schedule` for a one-shot job; set `schedule` to `5m`/`1h`/`1d` for recurring (minimum 5 minutes, 90-day horizon). Body fields: `url` (required), `method`, `headers`, `body`, `schedule`, `maxRuns`, `runAt`, `delivery` (`store`|`callback`|`both`), `callbackUrl`, `pay`, `maxPriceUsd`. $0.01 per run. With x402, price = $0.01 × `maxRuns` (pass `?maxRuns=N`).
  - Paying a downstream API: set `pay: true` to have the scheduler pay the target endpoint via x402 (USDC on Base) on each run, up to `maxPriceUsd` (default $0.10, max $1.00). This lets an agent schedule a job that itself buys a paid API — e.g. a daily call to another x402 service. Requires an API key with prepaid credits (not available on x402 pay-per-call jobs). Each run debits the downstream price plus a small margin from your credits; the reservation (`maxPriceUsd` × runs) is held up front and unspent credit is refunded if you cancel. Run results record the amount paid and the settlement transaction hash.
  - Failed runs: a timeout, connection error, 5xx or 429 is retried after 30s, 5m and 30m. If it still fails, the job is marked `failed` and stops, and the project's admins get an email. Restart it with `POST /v1/jobs/{id}/restart` (or `restart_job` over MCP), or cancel it to refund its unused balance.
- [GET /v1/jobs/{id}](https://omniyond.com/v1/jobs/): Get a job's status, schedule and recent runs. API key only.
- [DELETE /v1/jobs/{id}](https://omniyond.com/v1/jobs/): Cancel a job and refund its unused prepaid balance to your credits. API key only.
- [POST /v1/jobs/{id}/restart](https://omniyond.com/v1/jobs/): Restart a failed or paused job using the prepaid balance it still holds. It runs within a minute, then continues on its schedule. There's no new charge. API key only.
- [GET /v1/jobs/{id}/results](https://omniyond.com/v1/jobs/): List a job's run results. Add `?body=1` to include each run's stored response body. API key only.

## Utility endpoints

- [POST /v1/qr](https://omniyond.com/v1/qr): Generate a QR code as SVG from any text or URL. Body: `data` (required), `ecc` (L/M/Q/H), `border`. Returns image/svg+xml. $0.01.
- [POST /v1/og-image](https://omniyond.com/v1/og-image): Render a social preview (OG) image as PNG from `title`, `description`, `theme` (dark/light), `width`, `height`. Returns a hosted image URL. $0.01.
- [POST /v1/pdf](https://omniyond.com/v1/pdf): Render a PDF from raw `html` or a `url` (SSRF-protected), with `format` (A4/Letter/Legal) and `landscape`. Returns a hosted PDF URL. $0.02.
- [POST /v1/screenshot](https://omniyond.com/v1/screenshot): Take a PNG screenshot of a `url` (SSRF-protected) or raw `html`. Optional `width` and `height` (viewport, default 1280x800) and `fullPage` (capture the whole scrollable page). Returns a hosted image URL. $0.01.
- [POST /v1/extract](https://omniyond.com/v1/extract): Render a URL in a real headless browser (handles JS-heavy pages) and extract it. Body: `url` (required, SSRF-protected), `format` (`markdown` default, `content` for rendered HTML, or `links`), `visibleLinksOnly`, `excludeExternalLinks`. Returns clean LLM-ready markdown, rendered HTML, or a link list. $0.01.
- [POST /v1/link](https://omniyond.com/v1/link): Create a short link that 302-redirects to `url` and counts clicks. Optional `slug`, `expiresInDays`. The redirect is served at `/l/{slug}`. $0.01.
- [GET /v1/link/{slug}](https://omniyond.com/v1/link/): Get a short link's target, total click count and expiry. API key only (must be your link). Free.
- [GET /v1/files/{token}](https://omniyond.com/v1/files/): Fetch a file produced by og-image, pdf or screenshot. The token is the capability — no auth needed.
- [GET /v1/hello](https://omniyond.com/v1/hello): Minimal paid endpoint for testing the payment flow. $0.001 per call.

## MCP tools

The MCP server at `POST /mcp` (requires an API key) exposes every tool. Paid tools are charged from your credit balance at the same price as the REST endpoint, and refunded if the call fails:

- `schedule_job`: Schedule an HTTP request once or on a recurring interval. $0.01 per run.
- `get_job`: Get a job's status, schedule and recent runs. Free.
- `cancel_job`: Cancel a job and refund its unused balance. Free.
- `restart_job`: Restart a failed or paused job using its remaining prepaid balance. Free.
- `get_job_results`: List a job's run results (optionally with response bodies). Free.
- `extract_page`: Render a URL and return clean markdown, rendered HTML or its links. $0.01.
- `create_qr_code`: Generate a QR code and return the SVG markup. $0.01.
- `create_og_image`: Render a social preview image and return a hosted PNG URL. $0.01.
- `create_pdf`: Render a PDF from HTML or a URL and return a hosted PDF URL. $0.02.
- `create_screenshot`: Take a PNG screenshot of a URL or HTML and return a hosted image URL. $0.01.
- `create_short_link`: Create a short link that counts clicks. $0.01.
- `get_short_link`: Get a short link's target and click count. Free.

Connect any MCP client that supports remote servers (Grok Bot, Claude Code, Claude Desktop, Cursor, Codex) to `https://omniyond.com/mcp` with an `Authorization: Bearer omni_...` header.

## Pricing

- Scheduled run: $0.01. QR code: $0.01. OG image: $0.01. Screenshot: $0.01. Page extract: $0.01. Short link: $0.01. PDF: $0.02. Hello: $0.001.
- Credit packs: $9 (~900 runs), $29 (~2,900 runs), $99 (~9,900 runs). Credits never expire.
- Balances are tracked in microUSD ($1 = 1,000,000).

## Example

```
curl -X POST https://omniyond.com/v1/schedule \
  -H "Authorization: Bearer omni_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.acme.com/daily-digest","schedule":"1d","delivery":"callback","callbackUrl":"https://acme.com/hooks/digest"}'
```