REST API · v1

API Documentation

Optimize any URL or raw text for AI engines. Receive Markdown, JSON-LD, and schema-enriched HTML.

Overview

Receive source-language summaries, question headings, source-only Key Facts and comparison tables, and FAQ answers. JSON-LD contains an Article (WebPage for pasted text) and FAQPage graph; HTML includes the schema script and summary meta description. aeo_checks reports structural checks and warnings. If no source-grounded table can be produced after retry, the document completes with a warning rather than invented facts. Each successful optimize consumes 1 credit from your plan.

Base URLhttps://aipriva.com/api/public/v1

Required planGrowth · Agency

FormatJSON · UTF-8

Authentication

Send your API key as a Bearer token in the Authorization header. Keys start with rag_live_ and are shown exactly once at creation time — store them securely. Generate keys from your dashboard.

Authorization: Bearer rag_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

→ Manage API keys in the dashboard

Endpoints

POST/optimize

Submit a URL or raw text. Returns Markdown, JSON-LD, HTML, checks, and the document id.

Request

{
  "url": "https://example.com/post",
  // — or —
  "rawText": "Long article text…"
}

Response

{
  "id": "8b0a…",
  "status": "completed",
  "title": "Page title",
  "optimized_markdown": "## TL;DR …",
  "json_ld": { "@context": "https://schema.org", "@graph": [{ "@type": "Article", "headline": "Page title" }, { "@type": "FAQPage", "mainEntity": [{ "@type": "Question", "name": "What is AEO?", "acceptedAnswer": { "@type": "Answer", "text": "Answer engine optimization." } }] }] },
  "html": "<!DOCTYPE html>…<script type="application/ld+json">…</script>…",
  "aeo_checks": { "has_tldr": true, "question_heading_count": 5, "has_key_facts_table": true, "table_count": 1, "faq_pair_count": 3, "json_ld_types": ["Article", "FAQPage"], "warnings": [] },
  "credits_remaining": 248
}

GET/documents/{id}

Fetch a previously optimized document by id.

Response

{
  "id": "8b0a…",
  "title": "…",
  "status": "completed",
  "optimized_markdown": "## TL;DR …",
  "json_ld": { "@context": "https://schema.org", "@graph": [{ "@type": "Article", "headline": "Page title" }, { "@type": "FAQPage", "mainEntity": [{ "@type": "Question", "name": "What is AEO?", "acceptedAnswer": { "@type": "Answer", "text": "Answer engine optimization." } }] }] },
  "html": "<!DOCTYPE html>…<script type="application/ld+json">…</script>…",
  "aeo_checks": { "has_tldr": true, "question_heading_count": 5, "has_key_facts_table": true, "table_count": 1, "faq_pair_count": 3, "json_ld_types": ["Article", "FAQPage"], "warnings": [] },
  "created_at": "2026-06-15T…"
}

GET/usage

Returns your current plan, credit balance, and billing reset date.

Response

{
  "plan": "growth",
  "plan_name": "Growth",
  "api_access": true,
  "monthly_credits": 250,
  "credits_remaining": 248,
  "billing_cycle_reset": "2026-07-10T…"
}

POST/bulk

Agency only. Queue up to 200 unique HTTPS URLs for background optimization. Returns 202; one credit per success, failures free. Set allow_partial to run only as many URLs as your current credits cover.

Request

{ "urls": ["https://example.com/post-1", "https://example.com/post-2"], "allow_partial": false }

Response

{ "id": "batch-uuid", "status": "queued", "total": 2, "credits_needed": 2, "credits_remaining": 1000, "omitted": 0 }

GET/bulk/{id}

Agency only. Read owner-scoped batch progress and per-URL document ids. Runs continue with the tab closed. Manage retries, cancellation, pause recovery and ZIP downloads from Bulk in the dashboard.

Response

{ "job": { "id": "batch-uuid", "status": "completed", "total": 2, "pause_reason": null }, "progress": { "total": 2, "completed": 2, "failed": 0, "cancelled": 0, "pending": 0, "processing": 0 }, "items": [{ "url": "https://example.com/post-1", "status": "completed", "document_id": "document-uuid" }] }

Code samples

Three ways to call POST /optimize. Set the AIPRIVA_API_KEY environment variable to your key.

curl -X POST https://aipriva.com/api/public/v1/optimize \
  -H "Authorization: Bearer rag_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/blog/post" }'

Errors

All errors return a JSON body with an `error` object containing a stable `code` and a human-readable `message`.

HTTP	Code	Meaning
400	invalid_input	Body invalid or URL unreachable
401	unauthorized	Missing or invalid API key
402	insufficient_credits	Plan credits exhausted
403	forbidden_plan	Plan does not include API access
404	not_found	Document not found
500	internal_error	Server-side failure

Versioning

All endpoints live under /v1 and are stable. Breaking changes will ship under /v2 with at least 90 days of advance notice.

← Back to Home