{ "openapi": "3.1.0", "info": { "title": "AgenticPulse Readiness Auditor & Artifact Synthesizer API", "version": "1.0.0", "description": "Deterministic 6-dimension AI Agent Readiness, GEO, and llms.txt diagnostic scanner, artifact synthesizer, and Stripe checkout API. Versioning Policy: Stable endpoints are served under `/api/v1/*` (with `/api/*` maintained as a backwards-compatible alias) and accept the `X-API-Version: 1.0.0` header. Any breaking change increments the major version path (`/api/v2/*`) and emits RFC 8594 `Deprecation` and `Sunset` headers with at least 90 days notice. Rate Limiting: Responses include RFC `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers (60 req/min default). Errors follow RFC 9457 Problem Details (`application/problem+json`).", "contact": { "name": "AgenticPulse Engineering Support", "url": "https://neatjar.com/agentic-pulse/contact", "email": "sunxg5512@gmail.com" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://neatjar.com/agentic-pulse/", "description": "Production Cloudflare Edge Worker (Global Anycast)" }, { "url": "https://neatjar.com/agentic-pulse/api/v1", "description": "Versioned v1 REST API Base" } ], "components": { "parameters": { "ApiVersionHeader": { "name": "X-API-Version", "in": "header", "required": false, "description": "Explicit API version selector (default: 1.0.0).", "schema": { "type": "string", "default": "1.0.0", "example": "1.0.0" } } }, "headers": { "RateLimitLimit": { "description": "Maximum requests permitted in the current 60-second window.", "schema": { "type": "integer", "example": 60 } }, "RateLimitRemaining": { "description": "Remaining requests permitted in the current 60-second window.", "schema": { "type": "integer", "example": 59 } }, "RateLimitReset": { "description": "Seconds remaining until the rate-limit window resets.", "schema": { "type": "integer", "example": 60 } }, "SunsetHeader": { "description": "RFC 8594 Sunset timestamp if an endpoint version is scheduled for deprecation.", "schema": { "type": "string", "format": "date-time" } } }, "schemas": { "ErrorProblem": { "type": "object", "description": "RFC 9457 Problem Details for HTTP APIs (application/problem+json).", "required": [ "type", "title", "status", "detail", "code", "message" ], "properties": { "type": { "type": "string", "format": "uri", "example": "https://neatjar.com/agentic-pulse/docs#errors/invalid-parameter" }, "title": { "type": "string", "example": "Invalid Request Parameter" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Missing or malformed target URL parameter." }, "instance": { "type": "string", "example": "/api/v1/audit" }, "code": { "type": "string", "example": "INVALID_TARGET_URL" }, "message": { "type": "string", "example": "Please provide a valid http:// or https:// URL or domain name." } } }, "AuditDimensionCheck": { "type": "object", "required": [ "id", "label", "passed", "detail", "impact" ], "properties": { "id": { "type": "string", "example": "llms-txt-exists" }, "label": { "type": "string", "example": "/llms.txt manifest served at root" }, "passed": { "type": "boolean", "example": true }, "detail": { "type": "string", "example": "200 OK (2840 chars, 12ms)" }, "impact": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ] } } }, "AuditDimension": { "type": "object", "required": [ "id", "name", "shortName", "score", "maxScore", "status", "summary", "checks" ], "properties": { "id": { "type": "string", "example": "llms-txt" }, "name": { "type": "string", "example": "/llms.txt & /llms-full.txt Spec" }, "shortName": { "type": "string", "example": "llms.txt Standard" }, "score": { "type": "integer", "example": 20 }, "maxScore": { "type": "integer", "example": 20 }, "status": { "type": "string", "enum": [ "OPTIMAL", "PARTIAL", "CRITICAL" ] }, "summary": { "type": "string" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/AuditDimensionCheck" } } } }, "AuditReportResponse": { "type": "object", "required": [ "targetUrl", "origin", "domain", "auditedAt", "totalScore", "maxScore", "grade", "ttfbMs", "httpStatus", "dimensions", "artifacts" ], "properties": { "targetUrl": { "type": "string", "format": "uri", "example": "https://linear.app/" }, "origin": { "type": "string", "format": "uri", "example": "https://linear.app" }, "domain": { "type": "string", "example": "linear.app" }, "auditedAt": { "type": "string", "format": "date-time" }, "totalScore": { "type": "integer", "minimum": 0, "maximum": 100, "example": 88 }, "maxScore": { "type": "integer", "example": 100 }, "grade": { "type": "string", "enum": [ "A+", "A", "B", "C", "D" ], "example": "A" }, "ttfbMs": { "type": "integer", "example": 42 }, "httpStatus": { "type": "integer", "example": 200 }, "wafStatus": { "type": "string", "example": "OPEN_EDGE (cloudflare)" }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/AuditDimension" } }, "artifacts": { "type": "object", "required": [ "llmsTxt", "llmsFullTxt", "robotsTxt", "jsonLdPatch", "badgeSvgUrl" ], "properties": { "llmsTxt": { "type": "string" }, "llmsFullTxt": { "type": "string" }, "robotsTxt": { "type": "string" }, "jsonLdPatch": { "type": "string" }, "badgeSvgUrl": { "type": "string", "format": "uri" }, "badgeMarkdown": { "type": "string" }, "badgeHtml": { "type": "string" } } } } }, "CheckoutSessionResponse": { "type": "object", "required": [ "ok", "accountId", "plan", "planName", "productId", "priceId", "amountCents", "amountFormatted", "checkoutUrl" ], "properties": { "ok": { "type": "boolean", "example": true }, "accountId": { "type": "string", "example": "acct_1UTs7xQ9O7R8z2Va" }, "plan": { "type": "string", "enum": [ "lifetime", "monthly" ], "example": "lifetime" }, "planName": { "type": "string", "example": "AgenticPulse Lifetime Deal · Unlimited Deep Crawl & Auto-Fix ($49 One-Time)" }, "productId": { "type": "string", "example": "prod_VV8Km1CnMpxKv0" }, "priceId": { "type": "string", "example": "price_1UU84EQ9O7R8z2VavwSjS5Tc" }, "amountCents": { "type": "integer", "example": 4900 }, "amountFormatted": { "type": "string", "example": "$49.00 USD (One-Time Buyout)" }, "checkoutUrl": { "type": "string", "format": "uri" }, "invoicePdfUrl": { "type": "string", "format": "uri" } } }, "TelemetryStateResponse": { "type": "object", "required": [ "siteId", "siteName", "startedAt", "pvTotal", "auditsRun", "checkoutClicks" ], "properties": { "siteId": { "type": "string", "example": "EXP-001-AGENTIC-PULSE" }, "siteName": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "pvTotal": { "type": "integer", "example": 14 }, "pv24h": { "type": "integer", "example": 14 }, "auditsRun": { "type": "integer", "example": 8 }, "artifactDownloads": { "type": "integer", "example": 3 }, "checkoutClicks": { "type": "integer", "example": 2 }, "stripeRevenueUsd": { "type": "number", "example": 0 } } } }, "responses": { "BadRequestProblem": { "description": "Bad Request · Invalid parameters or missing URL (RFC 9457 Problem Details)", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorProblem" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorProblem" } } } }, "RateLimitProblem": { "description": "Too Many Requests · Rate limit exceeded (RFC 9457 Problem Details)", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "description": "Seconds until the client may retry.", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorProblem" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorProblem" } } } }, "InternalServerProblem": { "description": "Internal Server Error (RFC 9457 Problem Details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorProblem" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorProblem" } } } } } }, "paths": { "/api/v1/audit": { "get": { "operationId": "auditDomainV1Get", "summary": "Run a live 6-dimension Agentic & GEO readiness audit via GET (v1)", "parameters": [ { "$ref": "#/components/parameters/ApiVersionHeader" }, { "name": "url", "in": "query", "required": false, "description": "Target domain or URL to audit (e.g. https://linear.app)", "schema": { "type": "string", "example": "https://linear.app" } }, { "name": "preset", "in": "query", "required": false, "description": "Optional preset key (e.g. self)", "schema": { "type": "string", "example": "self" } } ], "responses": { "200": { "description": "Structured 6-dimension audit report and synthesized remediation artifacts", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditReportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestProblem" }, "429": { "$ref": "#/components/responses/RateLimitProblem" }, "500": { "$ref": "#/components/responses/InternalServerProblem" } } }, "post": { "operationId": "auditDomainV1Post", "summary": "Run a live 6-dimension Agentic & GEO readiness audit via POST (v1)", "parameters": [ { "$ref": "#/components/parameters/ApiVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Target domain or URL to audit (e.g. https://linear.app)", "example": "https://linear.app" } } } } } }, "responses": { "200": { "description": "Structured 6-dimension audit report and synthesized remediation artifacts", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditReportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestProblem" }, "429": { "$ref": "#/components/responses/RateLimitProblem" }, "500": { "$ref": "#/components/responses/InternalServerProblem" } } } }, "/api/audit": { "get": { "operationId": "auditDomainGet", "summary": "Run a live 6-dimension Agentic & GEO readiness audit via GET", "parameters": [ { "$ref": "#/components/parameters/ApiVersionHeader" }, { "name": "url", "in": "query", "required": false, "schema": { "type": "string", "example": "https://linear.app" } } ], "responses": { "200": { "description": "Structured 6-dimension audit report and synthesized remediation artifacts", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditReportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestProblem" }, "429": { "$ref": "#/components/responses/RateLimitProblem" }, "500": { "$ref": "#/components/responses/InternalServerProblem" } } }, "post": { "operationId": "auditDomain", "summary": "Run a live 6-dimension Agentic & GEO readiness audit on a target URL", "parameters": [ { "$ref": "#/components/parameters/ApiVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Target domain or URL to audit (e.g. https://linear.app)" } } } } } }, "responses": { "200": { "description": "Structured 6-dimension audit report and synthesized remediation artifacts", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditReportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestProblem" }, "429": { "$ref": "#/components/responses/RateLimitProblem" }, "500": { "$ref": "#/components/responses/InternalServerProblem" } } } }, "/api/checkout": { "get": { "operationId": "getCheckoutSession", "summary": "Retrieve Stripe Checkout session URL for Plan A tiers ($19/mo Pro or $49 LTD)", "parameters": [ { "$ref": "#/components/parameters/ApiVersionHeader" }, { "name": "plan", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "lifetime", "monthly" ], "default": "lifetime" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string", "example": "linear.app" } } ], "responses": { "200": { "description": "Stripe checkout session metadata and hosted payment URL", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestProblem" }, "429": { "$ref": "#/components/responses/RateLimitProblem" }, "500": { "$ref": "#/components/responses/InternalServerProblem" } } }, "post": { "operationId": "createCheckoutSession", "summary": "Initialize a Stripe Checkout session for Pro Monthly ($19/mo) or Lifetime Deal ($49 One-Time)", "parameters": [ { "$ref": "#/components/parameters/ApiVersionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "lifetime", "monthly" ], "description": "Plan A tier: lifetime ($49 One-Time) or monthly ($19/mo Pro Monthly)" }, "domain": { "type": "string" }, "email": { "type": "string" } } } } } }, "responses": { "200": { "description": "Stripe checkout session metadata and hosted payment URL", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestProblem" }, "429": { "$ref": "#/components/responses/RateLimitProblem" }, "500": { "$ref": "#/components/responses/InternalServerProblem" } } } }, "/api/badge": { "get": { "operationId": "getScoreBadge", "summary": "Generate an SVG Agentic Readiness Score badge", "parameters": [ { "$ref": "#/components/parameters/ApiVersionHeader" }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string", "example": "neatjar.com" } }, { "name": "score", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100, "example": 100 } } ], "responses": { "200": { "description": "SVG badge image", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "image/svg+xml": { "schema": { "type": "string", "description": "SVG XML document representing the domain readiness score badge." } } } }, "400": { "$ref": "#/components/responses/BadRequestProblem" }, "429": { "$ref": "#/components/responses/RateLimitProblem" } } } }, "/api/telemetry": { "get": { "operationId": "getTelemetryState", "summary": "Retrieve real-time funnel telemetry and recent domain audit metrics", "parameters": [ { "$ref": "#/components/parameters/ApiVersionHeader" } ], "responses": { "200": { "description": "Current telemetry counters and recent audited domains", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelemetryStateResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimitProblem" }, "500": { "$ref": "#/components/responses/InternalServerProblem" } } } } } }