# Getting started

Two steps: get a key, then start a read and collect it.

## 1. Get a key

Keys are minted per email address and mailed to that address. The key itself
exists in the email and nowhere else — only its SHA-256 is stored — so save it
when it arrives.

```bash
curl -X POST https://inspired.jetskibay.com/api/v1/keys \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com"}'
```

The response returns the key's prefix and allowance, never the key:

```json
{
  "key": {
    "keyPrefix": "isk_7f3a",
    "tier": "trial",
    "requestLimit": 10,
    "requestCount": 0,
    "requestsRemaining": 10,
    "expiresAt": 1757625600000
  }
}
```

A trial key is good for **10 requests** and expires **24 hours** after it is
issued. Re-requesting for an address that already has a live key revokes the old
one and carries its remaining allowance over, so losing a key costs nothing and
asking twice buys nothing.

Check what is left, or revoke it, for free:

```bash
curl https://inspired.jetskibay.com/api/v1/keys/current -H "x-api-key: $INSPIRED_KEY"
curl -X DELETE https://inspired.jetskibay.com/api/v1/keys/current -H "x-api-key: $INSPIRED_KEY"
```

## 2a. Start a read over MCP

Connect your agent runtime to `https://inspired.jetskibay.com/mcp` with the key
as a bearer token. The transport is Streamable HTTP with JSON responses, pinned
to MCP revision `2026-07-28`.

```json
{
  "mcpServers": {
    "inspired": {
      "url": "https://inspired.jetskibay.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_INSPIRED_KEY" }
    }
  }
}
```

Then, in one conversation: `list_focus_domains` if you are unsure which subject
fits the photo, `start_visual_search` with the image as base64, and
`get_visual_search` with the returned `requestId` until it reports `complete`.
See [Calling it over MCP](mcp.md) for the full argument and result shapes.

## 2b. Start a read over HTTP

```bash
curl -X POST https://inspired.jetskibay.com/api/v1/jobs \
  -H "x-api-key: $INSPIRED_KEY" \
  -F "image=@living-room.jpg" \
  -F "domain=furniture"
```

```json
{
  "requestId": "3f0c8a5e-1d4b-4a9e-9a1c-2b8f5d7e6c40",
  "status": "queued",
  "statusUrl": "https://inspired.jetskibay.com/api/v1/jobs/3f0c8a5e-…",
  "pollAfterMs": 3000
}
```

Poll it. Polling is free and does not touch your allowance:

```bash
curl "https://inspired.jetskibay.com/api/v1/jobs/$REQUEST_ID" \
  -H "x-api-key: $INSPIRED_KEY"
```

While it runs you get `status: "running"` and a progress object naming the stage
and each object's state. When it finishes you get `status: "complete"` with
`items`, each carrying the extracted product image and its `candidates`.

A read is readable **only with the key that started it**. A search started in the
consumer app has no key attached and is not readable through the API at all.

## Which endpoint to build on

`POST /api/v1/jobs` — or `start_visual_search` over MCP. A full read takes
minutes, which is longer than most HTTP clients and every serverless caller will
wait. The synchronous `POST /api/v1/inspire` exists and returns the same shape in
one response, but it will time out on a slow read; treat it as a convenience for
interactive experiments, not as the integration path.

## Sending the image

JPG, PNG, WEBP or GIF, up to 10 MB. Over HTTP, send it as multipart `image`.
Over MCP, send it as base64 in `image` plus `imageMediaType`, or as a `data:`
URL that names its own type. Instead of bytes, either surface accepts
`pinterestUrl` pointing at a public pin.

Resize before you send. The pipeline reads the photograph, it does not need the
original megapixels, and a 2048px longest edge is what the consumer app uploads.

## What one request costs you

One request is charged **when a read starts**, not when it finishes, so ten
concurrent calls cannot share one remaining request. The charge is given back
only when the platform itself failed. A photo with nothing shoppable in it is a
successful read and still costs one request.