AiRecMark/Evaluation API

AiRecMark/Developer Platform/ api v3.0.0/ Evaluation API Reference

JSON / HTTPS SESSION + SAME-ORIGIN CLOUDFLARE PAGES FUNCTIONS

terminalEVALUATION API — PROGRAMMATIC ACCESS

Evaluation API: Benchmark, Tool & Content Endpoints

The AiRecMark Evaluation API exposes the platform's benchmark archive record, tool records and content sets over HTTPS. Read endpoints are public for health, analytics and tool submission; every write path requires an authenticated session and a same-origin request.

rocket_launchQuickstart list_altEndpoint Reference scienceMethodology

API Version

3.0.0memory

Reported by GET /api/health

Public Endpoints

health · events · submit

Write Auth

Session + Origin

Cross-origin writes → 403

Response Format

JSON

application/json; charset=utf-8

§ 01 // OVERVIEW

API v3.0.0

Overview & Versioning

The Evaluation API is served by Cloudflare Pages Functions alongside the site. It exposes three public read/ingest endpoints and a session-gated surface used by the AiRecMark admin console.

Versioning is reported by GET /api/health. Breaking changes to write payloads are gated by the data schema (see § 07) rather than by URL version segment; /api/* paths are otherwise stable.

§ 02 // BASE URL & AUTH

HTTPS ONLY

Base URL & Authentication

All endpoints are relative to the site origin:

# base url
https://www.airecmark.com/api/<endpoint>

Read endpoints used by the public site (health, events) require no credentials. Tool submission (submit) is public but rate-limited. Everything else requires a session cookie issued by POST /api/login:

curl -X POST https://www.airecmark.com/api/login \
-H \
--data '{"password":"<admin-password>"}' -c cookies.txt

lockTwo independent guards on every write

Session: httpOnly cookie validated against the session secret; missing/expired → 401.
Same-origin: cross-origin writes are rejected with 403 cross-origin rejected.

§ 03 // QUICKSTART

60 SECONDS

Quickstart

Probe liveness, then post an analytics event — both work without credentials:

# 1) liveness probe
curl https://www.airecmark.com/api/health

# → {"ok":true,"kv":"ok","version":"3.0.0","ts":"2026-09-14T…Z"}

# 2) analytics beacon (whitelisted events only)
curl -X POST https://www.airecmark.com/api/events \
-H \
--data '{"event":"tool_view","props":{"slug":"cursor"},"path":"/cursor.html"}'
# → 204 No Content

Whitelisted event types: tool_view, affiliate_click, finder_start, finder_complete, compare_view, ranking_view, search, category_click, review_click, pricing_click.

§ 04 // PUBLIC SURFACE

NO CREDENTIALS

Public Endpoints

Method	Path	Returns	Notes
GET	/api/health	200 {ok,kv,version,ts}	Always 200; ok=false if KV unreachable
POST	/api/events	204 No Content	Whitelisted events; beacon-friendly
POST	/api/submit	JSON result	Tool submission; validated + rate-limited

# tool submission payload (POST /api/submit)
curl -X POST https://www.airecmark.com/api/submit \
-H \
--data '{"name":"Example AI","website":"https://example.ai","category":"coding","notes":"…"}'
# → 200 accepted · 400 validation · 429 rate limited

§ 05 // ADMIN SURFACE

SESSION REQUIRED

Authenticated Endpoints

These endpoints power the admin console and content pipeline. Every call requires the session cookie from § 02; write methods additionally require a same-origin request.

Method	Path	Purpose
POST	/api/login	Issue admin session cookie
GET	/api/status	Data freshness & KV summary (30/90/180-day thresholds)
GET	/api/export	Full content export (JSON download)
GET	/api/reviews	Site-wide review record index
GET	/api/tool/:slug	Single tool record
PUT	/api/tool/:slug	Validated write; score composed server-side
GET	/api/content/:set	Read a content set
PUT	/api/content/:set	Write a content set (validated + snapshotted)
GET	/api/review/:slug	Read tool review records
PUT	/api/review/:slug	Append/replace a dated review record
GET	/api/backups/:set	List snapshots
POST	/api/backups/:set	Roll a set back to a named snapshot
POST	/api/upload	base64 asset upload (logo / image)
POST	/api/publish	Trigger a rebuild (deploy hook / build signal)

§ 06 // LIMITS & ERRORS

429 / 400 / 401 / 403

Rate Limits, Errors & Validation

Endpoint	Limit	On Exceed
POST /api/submit	5 / hour / IP	429
POST /api/events	30 / day / IP (bucket cap 2,000/day)	Dropped + overflow counter

Errors are JSON and never HTML:

{ "error": , "detail": }

400 — malformed body or schema validation failure (see detail).
401 — missing/expired session.
403 — cross-origin write rejected.
404 — unknown tool slug or content set.
429 — rate limited.

Writes are validated identically to the CLI build pipeline: the five-dimension score is recomputed server-side, so a client cannot hand-set an overall score.

§ 07 // DATA MODEL

SCHEMA-GATED

Data Model & Schemas

Payloads follow the same versioned schemas used by the build pipeline. Key constraints:

Tool records: score.overall is composed from five dimensions (quality 25% · features 20% · usability 15% · performance 20% · value 20%); manual values are overwritten.
Review states: draft → sourced → reviewed → published → stale; illegal transitions return 400.
Published gate: a record moving to published must carry pricing source + lastChecked, sourced benchmarks, and at least one review with all five dimension scores.

See the Evaluation Methodology for the scoring protocol and the tool records published across the Explore database.

§ 08 // OPERATIONS

STATUS & SUPPORT

Status, Versioning & Support

Live platform state (KV reachability, data freshness, release version) is published on the Platform Status page and is probeable at any time via GET /api/health.

Integration & Access

partnerships@airecmark.com

Session provisioning and programmatic access requests.

Data & Corrections

editorial@airecmark.com

Record corrections and benchmark data questions.

This API is provided for evaluation and platform integration; usage of the public ingest endpoints implies acceptance of our Terms of Service.