v1 · Stable

Base URL: https://affiqly.com/api/public/v1

Affiqly API

The Affiqly API lets you manage storefront cards, categories, profiles and every AI capability powering the Affiqly product. It's a clean, versioned REST API returning predictable JSON.

API overview Swagger UI

Quickstart

Create a free account and open the Developers dashboard.
Generate an API key (shown once — copy it immediately).
Make your first authenticated request:

curl https://affiqly.com/api/public/v1/cards \
  -H 'authorization: Bearer aff_live_...'

Authentication

Send your API key as a Bearer token in the Authorization header. Keys look like aff_live_… and carry read + write scopes by default.

Authorization: Bearer aff_live_...

Rotate keys anytime from the Developers dashboard — old keys are revoked immediately.

Errors

Every error uses a consistent envelope with a machine-readable code, a human message, and a request id you can share with support.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded.",
    "request_id": "req_...",
    "docs_url": "https://affiqly.com/docs#errors"
  }
}

Code	HTTP	Meaning
missing_api_key	401	No bearer token was provided.
invalid_api_key	401	Key not found or revoked.
insufficient_scope	403	Key doesn't have the required scope.
rate_limited	429	Too many requests this minute — see Retry-After.
quota_exceeded	429	Monthly quota reached — upgrade the plan.
insufficient_credits	402	Not enough AI credits.
ai_disabled_on_plan	403	AI endpoints require Starter or higher.
validation_error	400	Request body failed schema validation.
not_found	404	Resource doesn't exist or isn't yours.
internal_error	500	Unexpected server error. Retry with backoff.

Rate limits & quotas

Each response includes:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-Quota-Limit: 50000
X-Quota-Remaining: 49812
X-Request-Id: req_...

When you hit a limit we return 429 with a Retry-After header. SDKs retry automatically with exponential backoff.

Pagination

List endpoints accept limit (max 200) and offset query parameters. Cursor pagination is coming in v2.

GET /v1/cards?limit=50&offset=100

Webhooks

Event types

card.created
card.updated
card.deleted
category.created
category.updated
category.deleted
profile.updated
subscription.updated

Signature verification

Every delivery includes a X-Affiqly-Signature: sha256=<hex> header — HMAC-SHA256 of the raw request body using your endpoint secret. Verify it in constant time before trusting the payload.

import crypto from "node:crypto";
const sig = req.headers["x-affiqly-signature"];
const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.AFFIQLY_WEBHOOK_SECRET)
  .update(rawBody).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
  return res.status(401).end();
}

Retries

Any non-2xx response triggers retries with exponential backoff (1m, 5m, 30m, 2h, 12h — up to 5 attempts). Return 2xx as soon as you've persisted the event; do the heavy work asynchronously.

SDKs

JavaScript

Download

import { Affiqly } from "https://affiqly.com/api/public/v1/sdk.mjs";
const client = new Affiqly({ apiKey: process.env.AFFIQLY_KEY });

Python

Download

curl -o affiqly.py https://affiqly.com/api/public/v1/sdk.py
from affiqly import Affiqly
client = Affiqly()

Endpoints

GET

/cards?limit=20— List cards

Paginate through your storefront cards.

curl -X GET https://affiqly.com/api/public/v1/cards?limit=20 \
  -H 'authorization: Bearer aff_live_...'

GET

/cards/{id}— Get a card

Fetch a single card by id.

curl -X GET https://affiqly.com/api/public/v1/cards/{id} \
  -H 'authorization: Bearer aff_live_...'

POST

/cards— Create a card

Create a new smart-catalog card.

curl -X POST https://affiqly.com/api/public/v1/cards \
  -H 'authorization: Bearer aff_live_...' \
  -H 'content-type: application/json' \
  -d '{"product_name":"Ceramic Pour-Over","price":42,"currency":"USD","card_type":"PRODUCT","description":"Slow-drip artisan brew.","card_url":"https://shop.example.com/pour-over"}'

PATCH

/cards/{id}— Update a card

Change price, status, or content.

curl -X PATCH https://affiqly.com/api/public/v1/cards/{id} \
  -H 'authorization: Bearer aff_live_...' \
  -H 'content-type: application/json' \
  -d '{"price":39,"status":"PUBLISHED"}'

DELETE

/cards/{id}— Delete a card

Permanently remove a card.

curl -X DELETE https://affiqly.com/api/public/v1/cards/{id} \
  -H 'authorization: Bearer aff_live_...'

GET

/categories— List categories

Get your category taxonomy.

curl -X GET https://affiqly.com/api/public/v1/categories \
  -H 'authorization: Bearer aff_live_...'

POST

/categories— Create category

Group related cards.

curl -X POST https://affiqly.com/api/public/v1/categories \
  -H 'authorization: Bearer aff_live_...' \
  -H 'content-type: application/json' \
  -d '{"name":"Coffee","slug":"coffee"}'

GET

/profile— Get profile

Return the authenticated profile.

curl -X GET https://affiqly.com/api/public/v1/profile \
  -H 'authorization: Bearer aff_live_...'

PATCH

/profile— Update profile

Update bio, links, or currency.

curl -X PATCH https://affiqly.com/api/public/v1/profile \
  -H 'authorization: Bearer aff_live_...' \
  -H 'content-type: application/json' \
  -d '{"full_name":"Ada Lovelace","bio":"Storefront by Ada."}'

POST

/ai/bio— AI · Bio

Generate a profile bio. ~1 credit.

curl -X POST https://affiqly.com/api/public/v1/ai/bio \
  -H 'authorization: Bearer aff_live_...' \
  -H 'content-type: application/json' \
  -d '{"industry":"fitness coaching","tone":"friendly","keywords":["personal","online"]}'

POST

/ai/cta— AI · CTA copy

Generate call-to-action copy.

curl -X POST https://affiqly.com/api/public/v1/ai/cta \
  -H 'authorization: Bearer aff_live_...' \
  -H 'content-type: application/json' \
  -d '{"context":"Free 7-day trial","goal":"signups"}'

POST

/ai/website-analyze— AI · Analyze website

Extract structured storefront data from a URL.

curl -X POST https://affiqly.com/api/public/v1/ai/website-analyze \
  -H 'authorization: Bearer aff_live_...' \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com"}'

POST

/ai/coach— AI · Storefront audit

Run an AI audit on your storefront.

curl -X POST https://affiqly.com/api/public/v1/ai/coach \
  -H 'authorization: Bearer aff_live_...'

POST

/ai/analytics-insights— AI · Analytics insights

Turn metrics into recommendations.

curl -X POST https://affiqly.com/api/public/v1/ai/analytics-insights \
  -H 'authorization: Bearer aff_live_...' \
  -H 'content-type: application/json' \
  -d '{"metrics":{"views":1200,"clicks":84}}'

POST

/ai/website-builder— AI · Website builder

Generate a full storefront draft.

curl -X POST https://affiqly.com/api/public/v1/ai/website-builder \
  -H 'authorization: Bearer aff_live_...' \
  -H 'content-type: application/json' \
  -d '{"business":"Handmade candles","industry":"lifestyle","tone":"warm"}'

GET

/usage— Usage

Current plan usage and quota.

curl -X GET https://affiqly.com/api/public/v1/usage \
  -H 'authorization: Bearer aff_live_...'