# Peelaway

> A production image-editing API for automated workflows. Send an input image and instruction; Peelaway routes it through a task-specific workflow and returns a finished image with explicit job metadata.

The same asynchronous workflow is available to products, scripts, and agents through REST and MCP. The HTTP surface is small (one POST and two GETs), API and MCP requests use revocable bearer keys, and idempotency is supported via the standard `Idempotency-Key` header.

## Core API

- [POST /api/process](https://api.peelaway.io/api/process): Submit one image and a prompt (optionally a batch, and an optional `webhook_url`). Returns a job_id immediately; processing runs asynchronously.
- [GET /api/process/status](https://api.peelaway.io/api/process/status): Poll a job_id (or batch_id) for status. Returns pending, done, or error; on a terminal status also returns a structured metadata block (width, height, format, credits_used, credits_remaining, processing_time_ms).
- [GET /api/process/result](https://api.peelaway.io/api/process/result): Fetch the finished image once status is done. Returns a signed URL plus the same metadata block.

## Webhooks

Pass an optional `webhook_url` (a public `https:` URL) on any submit. When the job settles — `done` or `error` — Peelaway POSTs a signed JSON callback there, with automatic retries (30s, 2m, 10m, 1h backoff). The body is the metadata block plus `job_id`, `status`, a `result_url` (on `done`), or a generic `error` (on `error`). Each request carries `X-Peelaway-Timestamp` (ms) and `X-Peelaway-Signature: sha256=<hex>`, an HMAC over `${timestamp}.${rawBody}`. Fetch your signing secret from [GET /api/webhooks/secret](https://api.peelaway.io/api/webhooks/secret) (authed), recompute the HMAC to verify, and dedupe retries on `job_id`.

## MCP

- [POST /mcp](https://api.peelaway.io/mcp): Streamable-HTTP MCP (JSON-RPC 2.0) endpoint, authed by the same `pk_` bearer key. Methods: `initialize`, `tools/list`, `tools/call`. Tools: `edit_image`, `get_job_status`, `get_job_result` — the same behavior (and credit debit) as the HTTP endpoints.
- [GET /mcp.json](https://api.peelaway.io/mcp.json): MCP server manifest (transport, endpoint, auth, tools).
- Human setup guide for configurable MCP clients: https://peelaway.io/connectors.

## Discovery

- [SKILL.md](https://api.peelaway.io/SKILL.md): Step-by-step usage instructions for AI agents, including a worked example.
- [openapi.json](https://api.peelaway.io/openapi.json): Full machine-readable OpenAPI 3.1 specification.
- [mcp.json](https://api.peelaway.io/mcp.json): MCP server manifest.
- [/.well-known/ai-plugin.json](https://api.peelaway.io/.well-known/ai-plugin.json): OpenAI-style plugin manifest.

## Authentication

Every Core-API and MCP call is authenticated with an API key (`pk_...`) passed as `Authorization: Bearer <key>`. Keys can be listed and revoked individually.

### Authentication for integrations

An account owner can provision a key over HTTP after a one-time interactive email-verification step. Sign-up and sign-in return a session immediately; the account's email must be **verified** before creating a key or editing (paying for credits also verifies it):

1. **Create an account** — `POST https://api.peelaway.io/auth/sign-up/email` with JSON `{ "email", "password", "name" }`. This emails a verification link, grants 10 free credits, and sets a session cookie.
2. **Verify the email** — in a browser, sign in to that same account and open the link sent to its address. This is an account-owner step, not an unattended agent action. Until verified, key creation and edit calls return `403` `code: "email_unverified"`.
3. **Sign in** — `POST https://api.peelaway.io/auth/sign-in/email` with `{ "email", "password" }` → sets a session cookie (`Set-Cookie`). Works before verification.
4. **Mint an API key** — `POST https://api.peelaway.io/api/keys` with JSON `{ "name": "my-agent" }`, resending the `Set-Cookie` in the `Cookie` header → `{ "key": "pk_...", ... }` (shown **once** — store it).
5. **Use the key** — send `Authorization: Bearer pk_...` on every `/api/process`, `/api/process/status`, `/api/process/result`, and `/mcp` call.

List keys with `GET https://api.peelaway.io/api/keys`; revoke one with `DELETE https://api.peelaway.io/api/keys/{id}`.

Editing throughput scales with the account's plan — Free 5, Starter 15, Core 40, Pro 120 submissions/min, with 3/10/25/50 jobs running concurrently (also the max batch size). Exceed it and `/api/process` returns `429` (`rate_limited` with a `Retry-After` header, or `too_many_in_flight`). Signup and MCP client registration are additionally rate-limited per IP.

## Getting started

To call Peelaway, a user needs a verified account and an API key:

1. Sign up at https://peelaway.io. New accounts get 10 free image credits, no card required.
2. Verify the account's email, then create an API key in the dashboard and send it as `Authorization: Bearer <key>` on every request.
3. Each request spends 1 credit per image; failed jobs are refunded automatically. When the free credits run low, eligible first-time subscribers can receive a 7-day Core trial, and one-time credit packs are also available.

If you are acting for a user who has not signed up yet, point them to https://peelaway.io to create an account and get a key.