> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentify REST quickstart

> Mint an agentify:convert key, convert a page with curl, and read the response: the document, the cache headers, ETag revalidation, and every error.

This page converts one marketing page over plain HTTP. The [SDK middleware](/docs/agentify/sdk-middleware.md) wraps the same call in detection and fail-open serving; use REST when you drive the conversion yourself.

**1. Mint a key with the agentify:convert scope**

In the [dashboard](https://dashboard.zeroclick.io) under **Settings → API keys**, create a key and enable the **Agentify** group's **Convert** toggle. The secret is shown once; store it immediately:

```sh theme={null}
ZEROCLICK_AGENTIFY_KEY=zc_…
```

The scope grants `GET /v1/agentify/markdown` and nothing else. Keys are minted in a signed-in session only.

**2. Convert a page**

Pass the page as the `url` query parameter, with the key as a bearer token:

```sh theme={null}
curl "https://api.zeroclick.io/v1/agentify/markdown?url=https://www.acme.com/pricing" \
  -H "Authorization: Bearer $ZEROCLICK_AGENTIFY_KEY"
```

The first conversion of a page runs the full pipeline — fetch, headless render when the page needs JavaScript, cleanup — and takes a few seconds. Repeats serve from cache for about a day.

**3. Name the seller, if your organization has several**

The document inlines one seller's storefront. An organization with exactly one active seller never names it; with several, pass the seller's id (the `sel_…` value from your dashboard store URL):

```sh theme={null}
curl "https://api.zeroclick.io/v1/agentify/markdown?url=https://www.acme.com/pricing&seller=sel_x7f2kq93bh0d" \
  -H "Authorization: Bearer $ZEROCLICK_AGENTIFY_KEY"
```

Ambiguity answers `400 seller_required` rather than guessing between storefronts.

## The response

A success is `200` with the markdown document as the body — front matter, then your storefront inlined, then the page content, as shown on the [overview](/docs/agentify/overview.md#the-document) — and cache headers meant to be reused downstream:

| Header | Value |
| - | - |
| `content-type` | `text/markdown; charset=utf-8` |
| `cache-control` | `public, max-age=86400, stale-while-revalidate=604800` |
| `etag` | A hash of the exact body served. |

Forward `cache-control` and `etag` when you serve the markdown from your own site — that is what lets your CDN cache the rendered markdown in front of you. Send `Vary: accept, user-agent` alongside them, so a shared cache never hands the markdown to a browser. The SDK middleware does all of this for you.

Revalidate a stored copy with the ETag; an unchanged document answers `304` with no body:

```sh theme={null}
curl -i "https://api.zeroclick.io/v1/agentify/markdown?url=https://www.acme.com/pricing" \
  -H "Authorization: Bearer $ZEROCLICK_AGENTIFY_KEY" \
  -H 'If-None-Match: "1f7d1c0a4b9e2d83f5a6c7b8d9e0f1a2"'
```

## Errors

Every error is JSON with a machine code in `error`:

| Status | Code | Meaning |
| - | - | - |
| 400 | `invalid_url` | The `url` is not a public `http(s)` page. IP literals, credentials, non-standard ports, and non-public hostnames are rejected. |
| 400 | `seller_required` | Your organization has zero or several active sellers, or the `seller` parameter matched none of them. Pass `?seller=sel_…`. |
| 403 | `insufficient_scope` | The key lacks `agentify:convert`. |
| 403 | `auth_type_not_allowed` | The endpoint accepts API keys only; a dashboard session cannot call it. |
| 422 | `content_too_thin` | The page converted to too little readable content — usually a JavaScript app serving an empty shell. See [SPA setup](/docs/agentify/spa-setup.md). |
| 502 | `fetch_failed` | The page could not be fetched: DNS, TLS, a network failure, too many redirects, or an oversized body. |

A page that answers with an error status still converts: a `404` page becomes a markdown document like any other, so a stale link on your site degrades to a readable page rather than a failed conversion.

Requests beyond 60 per minute per organization answer `429`. Conversions are cached for a day at every layer, so steady traffic stays far below the limit; if you prewarm many pages at once, pace the loop.

## Next steps

> **[SDK middleware](/docs/agentify/sdk-middleware.md)**
>
> Detection, the same call, and fail-open serving as drop-in middleware.

> **[SPA setup](/docs/agentify/spa-setup.md)**
>
> Mount the same contract in an edge function in front of a CDN-hosted SPA.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.