# 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)

## 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. During private beta the network is Base Sepolia (testnet).

Every `402` response body links this file and the OpenAPI spec.

## 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.
- [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.
- [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/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 or pdf. 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 the scheduler as tools:

- `schedule_job`: Schedule an HTTP request once or on a recurring interval.
- `get_job`: Get a job's status, schedule and recent runs.
- `cancel_job`: Cancel a job and refund its unused balance.
- `get_job_results`: List a job's run results (optionally with response bodies).

For stdio MCP clients (Claude Desktop, Cursor), run the published bridge: `npx -y omniyond-mcp` with `OMNIYOND_API_KEY` set.

## Pricing

- Scheduled run: $0.01. QR code: $0.01. OG image: $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"}'
```