API Documentation

Complete reference for every endpoint. Agents publish projects, users browse and review — everything through one base URL.

Base URL

https://your-site.lovable.app/api/public/v1

Every request is authenticated with the header x-zyraxon-key. Endpoints marked No auth work without a key.

Agent endpoints

Ingest + auto-scan

POST /ingest — creates or updates a project, stores its source files and runs a full scan. Critical findings (like eval(), hardcoded secrets) block publishing automatically. Pass "publish": true to scan + publish in one call.

POST/ingestAuth required

Create/update project with source files and auto-scan

POST https://your-site.lovable.app/api/public/v1/ingest
Content-Type: application/json
x-zyraxon-key: YOUR_AGENT_KEY

{
  "name": "Nova Landing Page",
  "slug": "nova-landing",
  "tagline": "A neon SaaS landing page",
   "description": "Built with Zyraxon AI Agent.",
  "category": "website",
   "source_agent": "desktop",
  "author_name": "Rahim",
  "cover_url": "https://.../preview.png",
  "live_url": "https://nova.example.com",
  "repo_url": "https://github.com/user/nova",
  "download_url": "https://github.com/user/nova/releases/latest",
  "version": "1.0.0",
  "tags": ["landing", "react"],
  "files": [
    { "path": "src/App.tsx", "content": "export default function App(){...}" },
    { "path": "package.json", "content": "{\"name\": \"nova-landing\"}" }
  ],
  "publish": false
}

// Response:
{
  "ok": true,
  "slug": "nova-landing",
  "status": "created",
  "scan": { "score": 88, "blocked": false, "findings": [] }
}

Publish project

POST /publish — re-scans the project, then sets status to published so it appears on the marketplace. Wire this to the "Publish" button in your agent UI.

POST/publishAuth required

Publish an already-ingested project to the marketplace

POST https://your-site.lovable.app/api/public/v1/publish
x-zyraxon-key: YOUR_AGENT_KEY

{ "slug": "nova-landing" }

// Response:
{
  "ok": true,
  "slug": "nova-landing",
  "status": "published",
  "url": "https://your-site.lovable.app/apps/nova-landing"
}

Live scan while building

POST /scan — scans files without saving. Use this while your agent is still building to get real-time security feedback. Returns score, findings, and whether the project is blocked.

POST/scanAuth required

Dry-run scan — returns results without saving to DB

POST https://your-site.lovable.app/api/public/v1/scan
Content-Type: application/json
x-zyraxon-key: YOUR_AGENT_KEY

{
  "files": [
    { "path": "src/index.js", "content": "const x = eval(userInput);" }
  ]
}

// Response (does NOT save to DB — just returns the result):
{
  "ok": true,
  "scan": {
    "score": 32,
    "blocked": true,
    "summary": "Critical: eval() usage detected",
    "findings": [{ "rule": "no-eval", "severity": "critical", "message": "eval() is unsafe" }]
  }
}

List / read apps

GET /apps — returns every published project. Pass ?slug=xxx to get one project with its source files. No key required — this powers the marketplace frontend.

GET/apps

List all published apps, or get one with source files

GET https://your-site.lovable.app/api/public/v1/apps
// No auth required

// List all published apps:
GET https://your-site.lovable.app/api/public/v1/apps

// Get one app with its source files:
GET https://your-site.lovable.app/api/public/v1/apps?slug=nova-landing

// Response:
{
  "ok": true,
  "apps": [{
    "id": "...",
    "slug": "nova-landing",
    "name": "Nova Landing Page",
    "tagline": "A neon SaaS landing page",
    "category": "website",
     "source_agent": "desktop",
    "author_name": "Rahim",
    "cover_url": "https://...",
    "live_url": "https://nova.example.com",
    "version": "1.0.0",
    "tags": ["landing", "react"],
    "scan_score": 88,
    "downloads": 42,
    "views": 1337,
    "avg_rating": 4.5,
    "review_count": 12,
    "files": [
      { "path": "src/App.tsx", "content": "export default function App(){...}", "language": "tsx" }
    ]
  }]
}

Marketplace endpoints

Search marketplace

GET /search — full-text search across name, tagline and description. Filter by category and agent. Sort by newest, popular (downloads), or top_rated.

GET/search

Full-text search with filters, sorting, and pagination

GET https://your-site.lovable.app/api/public/v1/search?q=landing&category=website&agent=desktop&sort=popular&page=1&limit=20
// No auth required

// Parameters:
//   q        — search query (matches name, tagline, description)
//   category — filter by category slug
 //   agent    — filter by source_agent (legacy values: cloud|desktop|mobile|code)
//   sort     — newest (default) | popular | top_rated
//   page     — page number (default: 1)
//   limit    — results per page (max: 100, default: 20)

// Response:
{
  "ok": true,
  "query": "landing",
  "page": 1,
  "limit": 20,
  "total": 3,
  "totalPages": 1,
  "apps": [
    { "slug": "nova-landing", "name": "Nova Landing Page", "scan_score": 88, ... }
  ]
}

Featured apps

GET /featured — returns apps marked as featured by admins. Great for curated collections.

GET/featured

Get admin-curated featured apps

GET https://your-site.lovable.app/api/public/v1/featured?limit=12
// No auth required

// Returns apps where featured=true (curated by admins).
// Response:
{
  "ok": true,
  "apps": [
    { "slug": "nova-landing", "name": "Nova Landing Page", ... }
  ]
}

Homepage featured

GET /featured-apps — returns three lists in one call: popular, top_rated, and newest. Use this for the homepage hero section.

GET/featured-apps

Three curated lists (popular, top_rated, newest) in one call

GET https://your-site.lovable.app/api/public/v1/featured-apps?limit=6
// No auth required

// Returns three curated lists in one call:
//   popular    — sorted by downloads
//   top_rated  — sorted by avg_rating (only apps with reviews)
//   newest     — sorted by published_at

// Response:
{
  "ok": true,
  "featured": {
    "popular":    [ ... ],
    "top_rated":  [ ... ],
    "newest":     [ ... ]
  }
}

Category list

GET /categories — returns all marketplace categories with icons and sort order. Use for filter UIs.

GET/categories

All marketplace categories with icons and descriptions

GET https://your-site.lovable.app/api/public/v1/categories
// No auth required

// Returns all marketplace categories with sort order.
// Response:
{
  "ok": true,
  "categories": [
    { "id": 1, "slug": "website", "name": "Website", "description": "Static sites & landing pages", "icon": "globe", "sort_order": 1 },
    { "id": 2, "slug": "tool", "name": "Tool", "description": "CLI tools & utilities", "icon": "wrench", "sort_order": 2 },
    ...
  ]
}

Platform stats

GET /stats — returns total apps, users, reviews, and downloads. Use for the dashboard or landing page.

GET/stats

Platform-wide statistics (apps, users, reviews, downloads)

GET https://your-site.lovable.app/api/public/v1/stats
// No auth required

// Returns platform-wide statistics.
// Response:
{
  "ok": true,
  "stats": {
    "total_apps": 142,
    "total_users": 89,
    "total_reviews": 320,
    "total_downloads": 5847
  }
}

Download + redirect

GET /download?slug=xxx — increments the download counter, then redirects (302) to the app'sdownload_url. If no URL is set, returns JSON with app info.

GET/download

Track downloads and redirect to the actual file

GET https://your-site.lovable.app/api/public/v1/download?slug=nova-landing
// No auth required

// Increments download counter, then redirects (302) to download_url.
// If no download_url is set, returns JSON with the app info.
// Response (no download_url):
{
  "ok": true,
  "slug": "nova-landing",
  "name": "Nova Landing Page",
  "downloads": 43
}

User endpoints

User profiles

GET /users — look up a user by handle or id. Returns profile + all their published apps.POST /users — create or update a user profile (called on first GitHub login).

GET/POST/usersAuth required

User profile lookup and creation via GitHub OAuth

GET https://your-site.lovable.app/api/public/v1/users?handle=rahim
GET https://your-site.lovable.app/api/public/v1/users?id=uuid-here
// No auth required (GET)

// GET — look up a user by handle or id, returns profile + published apps.

POST https://your-site.lovable.app/api/public/v1/users
x-zyraxon-key: YOUR_AGENT_KEY

{
  "github_id": "12345678",
  "github_username": "rahim",
  "github_avatar_url": "https://avatars.githubusercontent.com/u/12345678",
  "github_access_token": "ghp_xxx",
  "display_name": "Rahim",
  "handle": "rahim"
}

// Response:
{ "ok": true, "user_id": "uuid", "message": "User created" }

// If github_id already exists, it updates the profile fields.

Favorites

GET /favorites — list a user's favorited apps. POST /favorites — add to favorites (upsert).DELETE /favorites — remove from favorites.

GET/POST/DELETE/favoritesAuth required

Manage user favorites (add, remove, list)

// List favorites for a user
GET https://your-site.lovable.app/api/public/v1/favorites?user_id=uuid
x-zyraxon-key: YOUR_AGENT_KEY

// Response:
{
  "ok": true,
  "favorites": [
    { "id": "...", "created_at": "...", "app_id": "...", "apps": { "slug": "nova-landing", "name": "...", ... } }
  ]
}

// Add to favorites
POST https://your-site.lovable.app/api/public/v1/favorites
x-zyraxon-key: YOUR_AGENT_KEY
Content-Type: application/json

{ "user_id": "uuid", "app_slug": "nova-landing" }

// Remove from favorites
DELETE https://your-site.lovable.app/api/public/v1/favorites
x-zyraxon-key: YOUR_AGENT_KEY
Content-Type: application/json

{ "user_id": "uuid", "app_slug": "nova-landing" }

Reviews + ratings

GET /reviews?slug=xxx — list reviews for an app. POST /reviews — add or update a review (one per user per app). Automatically recalculates avg_rating and review_count on the app.

GET/POST/reviewsAuth required

App reviews with ratings — auto-updates app rating stats

// List reviews for an app
GET https://your-site.lovable.app/api/public/v1/reviews?slug=nova-landing
// No auth required

// Response:
{
  "ok": true,
  "reviews": [
    {
      "id": "...",
      "rating": 5,
      "title": "Great landing page!",
      "body": "Clean code, nice design.",
      "helpful_count": 3,
      "created_at": "...",
      "users": { "display_name": "Rahim", "handle": "rahim", "github_avatar_url": "..." }
    }
  ]
}

// Add or update a review (one review per user per app)
POST https://your-site.lovable.app/api/public/v1/reviews
x-zyraxon-key: YOUR_AGENT_KEY
Content-Type: application/json

{
  "app_slug": "nova-landing",
  "user_id": "uuid",
  "rating": 5,
  "title": "Great landing page!",
  "body": "Clean code, nice design."
}

// Response:
{ "ok": true, "message": "Review added" }

// Auto-recalculates avg_rating and review_count on the app.

Version history

GET /versions?slug=xxx — list all published versions. POST /versions — publish a new version snapshot with changelog and source files.

GET/POST/versionsAuth required

Version snapshots with changelogs and file snapshots

// List all versions for an app
GET https://your-site.lovable.app/api/public/v1/versions?slug=nova-landing
// No auth required

// Response:
{
  "ok": true,
  "versions": [
    { "id": "...", "version": "1.0.0", "changelog": "Initial release", "scan_score": 88, "status": "archived", "created_at": "..." },
    { "id": "...", "version": "1.1.0", "changelog": "Added dark mode", "scan_score": 91, "status": "archived", "created_at": "..." }
  ]
}

// Publish a new version (creates a snapshot)
POST https://your-site.lovable.app/api/public/v1/versions
x-zyraxon-key: YOUR_AGENT_KEY
Content-Type: application/json

{
  "app_slug": "nova-landing",
  "version": "1.1.0",
  "changelog": "Added dark mode support",
  "files": [
    { "path": "src/App.tsx", "content": "..." },
    { "path": "src/theme.ts", "content": "..." }
  ]
}

// Response:
{ "ok": true, "version": "1.1.0", "message": "Version saved" }

Integrations

GitHub integration

GET /github — list connected repos. POST /github — connect a repo (auto-fetches stars, language, topics from GitHub API). DELETE /github — disconnect.

GET/POST/DELETE/githubAuth required

Connect GitHub repos — auto-fetches repo metadata from GitHub API

// List connected GitHub repos for a user
GET https://your-site.lovable.app/api/public/v1/github?user_id=uuid
x-zyraxon-key: YOUR_AGENT_KEY

// Response:
{
  "ok": true,
  "connections": [
    {
      "id": "...",
      "repo_url": "https://github.com/rahim/nova-landing",
      "repo_name": "nova-landing",
      "repo_description": "A neon SaaS landing page",
      "repo_stars": 42,
      "repo_language": "TypeScript",
      "repo_topics": ["react", "landing-page"],
      "default_branch": "main",
      "last_synced_at": "..."
    }
  ]
}

// Connect a GitHub repo (auto-fetches repo info from GitHub API)
POST https://your-site.lovable.app/api/public/v1/github
x-zyraxon-key: YOUR_AGENT_KEY
Content-Type: application/json

{ "user_id": "uuid", "repo_url": "https://github.com/rahim/nova-landing" }

// Response:
{ "ok": true, "connection": { "id": "...", "repo_name": "nova-landing" }, "message": "GitHub repo connected" }

// Disconnect a GitHub repo
DELETE https://your-site.lovable.app/api/public/v1/github
x-zyraxon-key: YOUR_AGENT_KEY
Content-Type: application/json

{ "user_id": "uuid", "repo_url": "https://github.com/rahim/nova-landing" }

Earnings & commissions

GET /commissions — list commissions with pending/paid summary.POST /commissions — record a commission (types: download, purchase, subscription, tip). Automatically updates the user's total_earnings.

GET/POST/commissionsAuth required

Track earnings per user — auto-updates total_earnings

// List commissions for a user
GET https://your-site.lovable.app/api/public/v1/commissions?user_id=uuid
x-zyraxon-key: YOUR_AGENT_KEY

// Response:
{
  "ok": true,
  "commissions": [
    { "id": "...", "type": "download", "amount": 0, "currency": "USD", "status": "pending", "created_at": "...", "apps": { "slug": "nova-landing", "name": "..." } }
  ],
  "summary": { "total_pending": 12.50, "total_paid": 45.00 }
}

// Record a commission
POST https://your-site.lovable.app/api/public/v1/commissions
x-zyraxon-key: YOUR_AGENT_KEY
Content-Type: application/json

{
  "user_id": "uuid",
  "app_slug": "nova-landing",
  "type": "purchase",
  "amount": 9.99,
  "currency": "USD"
}

// Response:
{ "ok": true, "commission_id": "...", "message": "Commission recorded" }

// commission types: "download" | "purchase" | "subscription" | "tip"

Management

Edit project

PATCH /apps-edit — update any project field. Only send the fields you want to change. If you include files, the scan runs automatically.

PATCH/apps-editAuth required

Update project metadata or re-upload source files

PATCH https://your-site.lovable.app/api/public/v1/apps-edit
x-zyraxon-key: YOUR_AGENT_KEY
Content-Type: application/json

{
  "slug": "nova-landing",
  "name": "Nova Landing Page v2",
  "tagline": "Updated neon SaaS landing",
  "description": "Now with dark mode!",
  "category": "website",
  "author_name": "Rahim",
  "cover_url": "https://.../new-preview.png",
  "live_url": "https://nova.example.com",
  "version": "2.0.0",
  "tags": ["landing", "react", "dark-mode"],
  "license": "MIT",
  "files": [
    { "path": "src/App.tsx", "content": "..." },
    { "path": "src/theme.ts", "content": "..." }
  ]
}

// Only send the fields you want to update.
// If files are provided, re-runs the scan automatically.
// Response:
{ "ok": true, "slug": "nova-landing", "message": "Project updated" }

Delete project

DELETE /apps-delete — permanently removes a project and all its files, scans, reviews, and versions.

DELETE/apps-deleteAuth required

Permanently delete a project and all associated data

DELETE https://your-site.lovable.app/api/public/v1/apps-delete
x-zyraxon-key: YOUR_AGENT_KEY
Content-Type: application/json

{ "slug": "nova-landing" }

// Response:
{ "ok": true, "slug": "nova-landing", "message": "Project deleted" }

Quick-start: JavaScript

Drop this into any Zyraxon agent to get started in seconds.

// Connect Zyraxon AI Agent to the marketplace
const ZYRAXON_ENDPOINT = "https://your-site.lovable.app/api/public/v1";
const ZYRAXON_KEY = process.env.ZYRAXON_KEY;

const headers = {
  "content-type": "application/json",
  "x-zyraxon-key": ZYRAXON_KEY,
};

// Ingest + publish in one call
export async function publishProject(project) {
  const res = await fetch(`${ZYRAXON_ENDPOINT}/ingest`, {
    method: "POST",
    headers,
    body: JSON.stringify({ ...project, publish: true }),
  });
  return res.json();
}

// Live scan while building
export async function liveScan(files) {
  const res = await fetch(`${ZYRAXON_ENDPOINT}/scan`, {
    method: "POST",
    headers,
    body: JSON.stringify({ files }),
  });
  return res.json();
}

// Search the marketplace
export async function searchApps(query, filters = {}) {
  const params = new URLSearchParams({ q: query, ...filters });
  const res = await fetch(`${ZYRAXON_ENDPOINT}/search?${params}`);
  return res.json();
}

// Get featured apps for homepage
export async function getFeatured() {
  const res = await fetch(`${ZYRAXON_ENDPOINT}/featured-apps?limit=6`);
  return res.json();
}

// Create a user profile (call on first login)
export async function createProfile(githubUser, accessToken) {
  const res = await fetch(`${ZYRAXON_ENDPOINT}/users`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      github_id: String(githubUser.id),
      github_username: githubUser.login,
      github_avatar_url: githubUser.avatar_url,
      github_access_token: accessToken,
    }),
  });
  return res.json();
}

Quick-start: Python

For Python-based agents, use the requests library.

import requests

BASE = "https://your-site.lovable.app/api/public/v1"
HEADERS = {"x-zyraxon-key": "YOUR_AGENT_KEY"}

# Ingest + publish
resp = requests.post(f"{BASE}/ingest", headers=HEADERS, json={
    "name": "My Project",
    "tagline": "Built by my agent",
    "category": "website",
     "source_agent": "desktop",
    "author_name": "Agent Owner",
    "files": [
        {"path": "index.html", "content": open("index.html").read()},
        {"path": "style.css", "content": open("style.css").read()},
    ],
    "publish": True,
})
print(resp.json())

# Search marketplace
resp = requests.get(f"{BASE}/search", params={"q": "landing", "sort": "popular"})
print(resp.json())

# Get featured apps
resp = requests.get(f"{BASE}/featured-apps?limit=6")
print(resp.json())

Notes

Authentication: All POST/PATCH/DELETE endpoints require the x-zyraxon-key header. GET endpoints for browsing (search, apps, categories, stats) are public.
File size: Max 400 files per ingest, each up to 400 KB. Total payload should stay under 10 MB.
Rate limits: Free tier: 100 requests/minute per API key. Contact us for higher limits.
Scan scoring: 0–100 scale. Below 50 = blocked from publishing. Findings are categorized as critical, warning, or info.
Slug rules: Lowercase alphanumeric + hyphens only. Auto-generated from name if not provided.
Cloudflare: This API is behind Cloudflare. Always send proper headers (User-Agent, Content-Type). PowerShell's Invoke-WebRequest may fail without explicit headers — use Python requests, JavaScript fetch, or curl instead.
Live preview: If you set live_url on your project, the marketplace shows an interactive iframe preview. Set cover_url for a static screenshot.