[Home](/)

# Agents.md

Production integration guide for ZipRio marketplace APIs.

## Base URL

- Local: `http://localhost:3000`
- Production: your deployed web origin

Examples use `BASE_URL`.

## Prerequisites

1. Create account at `GET /auth/sign-up`.
2. Sign in at `GET /auth/sign-in`.
3. Create API key at `GET /settings/api-keys`.
4. Enable scopes:
   - `marketplace:search`
   - `marketplace:purchase`
5. Copy key once and store in your secret manager.

API key format:

- `zkr_<prefix>_<secret>`

## Auth and Headers

Send API key as bearer token:

```http
Authorization: Bearer zkr_<prefix>_<secret>
```

For JSON POST routes also send:

```http
Content-Type: application/json
```

## Quick Start (Smoke Test)

```bash
# 1) Service health
curl -fsS "$BASE_URL/api/healthcheck"

# 2) Agent search
curl -sS "$BASE_URL/api/agent/search" \
  -H "Authorization: Bearer $ZIPRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"nextjs template"}'

# 3) Agent purchase quote
curl -sS "$BASE_URL/api/agent/purchase" \
  -H "Authorization: Bearer $ZIPRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assetId":"<asset_id>","licenseCode":"commercial","seats":1}'
```

## Primary Agent Endpoints

### 1) Search assets

- Method: `POST /api/agent/search`
- Scope: `marketplace:search`
- Body:

```json
{
  "query": "nextjs template"
}
```

- Success response:

```json
{
  "ok": true,
  "results": []
}
```

### 2) Purchase quote (quote-only)

- Method: `POST /api/agent/purchase`
- Scope: `marketplace:purchase`
- Body:

```json
{
  "assetId": "asset_id_here",
  "licenseCode": "commercial",
  "seats": 1
}
```

- Success response shape:

```json
{
  "ok": true,
  "mode": "agent",
  "status": "quote_only",
  "quote": {}
}
```

Notes:
- This route returns a quote only. It does not finalize payment.
- `seats` must be a positive integer.

## Additional Endpoints

### 3) Asset listing

- Method: `GET /api/v1/assets?q=<query>`
- Public browse is allowed.

```bash
curl -sS "$BASE_URL/api/v1/assets?q=agent"
```

### 4) Stripe purchase intent

- Method: `POST /api/v1/purchase`
- Works with session auth.
- API-key scope check on this route is currently `purchase` (not `marketplace:purchase`).

### 5) Crypto purchase intent

- Method: `POST /api/v1/crypto/purchase`
- Body includes `cryptoCurrency`: `ETH`, `USDC`, or `BTC`.
- API-key scope check on this route is currently `purchase` (not `marketplace:purchase`).

### 6) Download purchased file

- Method: `GET /api/v1/download/<fileId>`
- Requires authenticated user session and entitlement.
- API key auth alone is not sufficient for this route.

## Common Errors

- `401`: `UNAUTHORIZED` or `API_KEY_REQUIRED`
- `403`: `INSUFFICIENT_SCOPE`
- `404`: `LICENSE_PRICE_NOT_FOUND` or `LICENSE_OR_VERSION_NOT_AVAILABLE`
- `402`: `SPEND_LIMIT_EXCEEDED` (agent quote route)
- `429`: `DAILY_SPEND_LIMIT_EXCEEDED` or `MONTHLY_SPEND_LIMIT_EXCEEDED` (v1 purchase)
- `503`: `CRYPTO_PAYMENTS_NOT_CONFIGURED` (crypto route)

## Recommended Agent Flow

1. Search with `/api/agent/search`.
2. Select `assetId` and valid `licenseCode`.
3. Request quote via `/api/agent/purchase`.
4. Present quote and terms to user and request explicit approval.
5. Complete payment via UI/session flow or your approved backend flow.
6. Download via entitled user session route.

## Security Requirements

- Keep API keys server-side only.
- Use least-privilege scopes.
- Set daily/monthly spend limits.
- Never log raw API keys.
- Rotate and revoke keys on schedule.

## Minimal Server Example

```ts
const res = await fetch(`${process.env.ZIPRIO_BASE_URL}/api/agent/search`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ZIPRIO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: 'rag pipeline' }),
});

if (!res.ok) {
  const text = await res.text();
  throw new Error(`ZipRio search failed (${res.status}): ${text}`);
}

const data = await res.json();
```

## Operational Checklist

- [ ] Account created
- [ ] API key created with required scopes
- [ ] Spend limits configured
- [ ] `/api/healthcheck` returns `OK`
- [ ] `/api/agent/search` returns `ok: true`
- [ ] `/api/agent/purchase` returns `status: quote_only`

## Optional Hardening

- [ ] Structured handling for 401/403/404/402/429/503
- [ ] Key rotation and revocation runbook documented
- [ ] Alerting for repeated auth/scope failures