Skip to main content
Skip to content

API Reference

The CloviDecks API lets you integrate CloviDecks into your own applications and automations. All endpoints are served over HTTPS from https://clovidecks.com.

Authentication

Authenticate every request with a Bearer token in the Authorization header. Generate a token from your account settings on the CloviDecks dashboard.

curl https://clovidecks.com/api/me \
  -H "Authorization: Bearer $CLOVI_TOKEN"

import requests

resp = requests.get(
    "https://clovidecks.com/api/me",
    headers={"Authorization": f"Bearer {token}"},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://clovidecks.com/api/me", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await resp.json();
console.log(data);

import axios from "axios";

const { data } = await axios.get(
  "https://clovidecks.com/api/me",
  { headers: { Authorization: `Bearer ${token}` } }
);
console.log(data);

Keep your token secret

Treat your API token like a password. Send it only over HTTPS and never commit it to source control — load it from an environment variable instead.

Responses & errors

All responses are JSON. Successful calls return 2xx; client errors return 4xx with a JSON body describing the problem. Common status codes:

Status Meaning
200 Success
400 Bad request — check your parameters
401 Missing or invalid token
404 Resource not found
429 Rate limit exceeded — slow down and retry
500 Server error — retry or contact support

CloviDecks API Reference

Service: clovidecks — AI slide-to-narrated-video presentation builder
Base URL: https://clovidecks.com (port 8968)
Source: /root/clovidecks/server.js
Generated: 2026-06-16 — 24 routes documented

Authentication

All /api/* routes (except auth endpoints) are protected by requireAuth middleware.

Method Cookie/Header Notes
Platform SSO cl_session cookie Shared CloviTek AI JWT
Standalone session cd_token cookie or Authorization: Bearer <token> Issued by /api/auth/login or /api/auth/register

Admin-only routes additionally require requireAdmin (checks role === 'admin' on the JWT payload).

Note: There is no separate public developer API key system yet. All routes are internal application routes consumed by the CloviDecks web UI. A public REST API is planned.

Auth Routes

POST /api/auth/register

Creates a new CloviDecks account and issues a session cookie.

Auth: None required
Body (JSON):

Field Type Required
email string Yes
password string Yes
name string No

Example: 

curl -X POST https://clovidecks.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"secret123"}'
Response (201): 
{ "ok": true, "user": { "id": 1, "email": "[email protected]" } }
Errors: 400 missing fields; 409 email already registered.

POST /api/auth/login

Signs in an existing account and issues a session cookie.

Auth: None required
Body (JSON): email (string), password (string)

Response: 

{ "ok": true, "user": { "id": 1, "email": "[email protected]" } }
Errors: 401 invalid credentials.

POST /api/auth/logout

Clears the session cookie.

Auth: None required
Response: { "ok": true }

GET /api/me / GET /api/auth/me

Returns the authenticated user's identity from the JWT.

Auth: Session cookie or Bearer token
Response: 

{ "user": { "id": 1, "email": "[email protected]", "name": "Jane", "plan": "free" } }
Errors: 401 Unauthorized

Projects

Projects are the raw "input" workspace — slides, narration text, and uploaded assets — before a deck is generated.

GET /api/projects

Lists all projects owned by the authenticated user.

Auth: Session cookie or Bearer
Response: 

{
  "projects": [
    { "id": 1, "title": "Q2 Review", "slideCount": 8, "createdAt": "2026-06-01T10:00:00Z" }
  ]
}

POST /api/projects

Creates a new project.

Auth: Session cookie or Bearer
Body (JSON): { "title": "..." }
Response (201): 

{ "project": { "id": 2, "title": "New Project", "slides": [] } }

GET /api/projects/:id

Returns a single project with its slides.

Auth: Session cookie or Bearer
Path params: id (integer)
Response: 

{ "project": { "id": 2, "title": "New Project", "slides": [ { "num": 1, "text": "..." } ] } }
Errors: 404 project not found.

PUT /api/projects/:id

Updates project metadata (e.g., title).

Auth: Session cookie or Bearer
Path params: id (integer)
Body (JSON): Any subset of { "title": "..." }

DELETE /api/projects/:id

Deletes a project and all its slides.

Auth: Session cookie or Bearer
Path params: id (integer)
Response: { "ok": true }

POST /api/projects/:id/slides

Adds a slide to a project.

Auth: Session cookie or Bearer
Path params: id (integer)
Body (JSON): { "text": "Narration for this slide...", "num": 1 }
Response (201): { "slide": { "num": 1, "text": "..." } }

PUT /api/projects/:id/slides/:num

Updates a slide's narration text.

Auth: Session cookie or Bearer
Path params: id (project), num (slide position)
Body (JSON): { "text": "Updated narration..." }

DELETE /api/projects/:id/slides/:num

Removes a slide from a project.

Auth: Session cookie or Bearer
Path params: id (project), num (slide position)
Response: { "ok": true }

POST /api/projects/:id/upload

Uploads a slide image (PNG/JPG) to a project.

Auth: Session cookie or Bearer
Path params: id (project integer)
Body: multipart/form-data with field file (image)
Response: { "url": "https://..." }
Errors: 400 unsupported file type; 413 file too large.

POST /api/projects/:id/handoff

Submits a project for deck generation (queues the AI pipeline job).

Auth: Session cookie or Bearer
Path params: id (project integer)
Body (JSON):

Field Type Notes
voice string Optional TTS voice ID
style string Optional presentation style

Response: { "ok": true, "deckId": 7 }

Decks

Decks are the generated output — the assembled narrated video presentations.

POST /api/decks/generate

Triggers AI generation of a deck from a text prompt (alternative to project handoff).

Auth: Session cookie or Bearer
Body (JSON):

Field Type Required
prompt string Yes
slideCount integer No

Response: { "deckId": 8, "status": "queued" }

GET /api/decks/ai/usage

Returns the authenticated user's AI credit usage for the current billing period.

Auth: Session cookie or Bearer
Response: { "used": 3, "limit": 10, "plan": "free" }

GET /api/decks

Lists all decks owned by the authenticated user.

Auth: Session cookie or Bearer
Response: 

{
  "decks": [
    { "id": 7, "title": "Q2 Review", "status": "ready", "slideCount": 8, "createdAt": "2026-06-10T09:00:00Z" }
  ]
}

GET /api/decks/:id

Returns a single deck with full metadata and slide list.

Auth: Session cookie or Bearer
Path params: id (integer)
Errors: 404 deck not found.

GET /api/decks/:id/pptx

Downloads the deck as a PPTX file.

Auth: Session cookie or Bearer
Path params: id (integer)
Response: Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation
Errors: 404 not found; 409 deck not yet ready.

GET /api/decks/:id/pdf

Downloads the deck as a PDF file.

Auth: Session cookie or Bearer
Path params: id (integer)
Response: Content-Type: application/pdf
Errors: 404 not found; 409 deck not yet ready.

POST /api/decks/:id/visual

Triggers AI visual enhancement / slide visual regeneration.

Auth: Session cookie or Bearer
Path params: id (integer)
Body (JSON): { "style": "..." } (optional)
Response: { "ok": true, "status": "processing" }

Admin Routes

Require requireAdmin — JWT must carry role === 'admin'.

GET /api/admin/users

Returns all registered users.

Auth: Admin session
Response: { "users": [ { "id": 1, "email": "...", "plan": "free", "createdAt": "..." } ] }

GET /api/admin/projects

Returns all projects across all users.

Auth: Admin session
Response: { "projects": [ { "id": 1, "userId": 2, "title": "...", "slideCount": 5 } ] }

PUT /api/admin/users/:id/plan

Updates a user's plan tier.

Auth: Admin session
Path params: id (integer)
Body (JSON): { "plan": "pro" }
Response: { "ok": true }

CloviDecks | Terms Privacy Data Handling Cookies | Powered by CloviTek AI