API REFERENCE

Kompyl API Documentation

Transform any content into structured presentations, courses, and documents. Our REST API makes it easy to integrate AI-powered content transformation into your workflows.

SECURITY

Authentication

All API requests require an API key passed via the X-API-Key header.

Request Headerbash
curl -X POST https://api.kompyl.com/v1/compile-and-render \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"input": {"type": "text", "value": "Your content..."}}'

API Key Scopes

  • parse — Parse content into Brain DSL
  • validate — Validate and auto-fix Brain
  • plan — Generate layout plans
  • render — Render final artifacts

Rate Limits

  • Free tier: 10 requests/min
  • Pro tier: 100 requests/min
  • Enterprise: Custom limits
GET STARTED

Quick Start

The /compile-and-render endpoint is the fastest way to transform content. It handles parsing, validation, planning, and rendering in a single call.

cURLbash
curl -X POST https://api.kompyl.com/v1/compile-and-render \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "type": "text",
      "value": "# Introduction to AI\n\nArtificial intelligence is transforming..."
    },
    "format": "pptx",
    "language": "en",
    "audience": "intermediate"
  }'
Pythonpython
import requests

response = requests.post(
    "https://api.kompyl.com/v1/compile-and-render",
    headers={"X-API-Key": "your_api_key"},
    json={
        "input": {
            "type": "text",
            "value": "# Introduction to AI\n\nArtificial intelligence..."
        },
        "format": "pptx",
        "language": "en",
        "audience": "intermediate"
    }
)

result = response.json()
print(f"Download: {result['download_url']}")
JavaScript / Node.jsjavascript
const response = await fetch('https://api.kompyl.com/v1/compile-and-render', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    input: {
      type: 'text',
      value: '# Introduction to AI\n\nArtificial intelligence...'
    },
    format: 'pptx',
    language: 'en',
    audience: 'intermediate'
  })
});

const result = await response.json();
console.log('Download:', result.download_url);
Responsejson
{
  "job_id": "job_abc123",
  "status": "succeeded",
  "artifact_id": "art_xyz789",
  "download_url": "/v1/artifacts/art_xyz789/download",
  "block_count": 8,
  "slide_count": 10,
  "dsl_version": "1.0",
  "warnings": [],
  "fixes_applied": []
}
REFERENCE

API Endpoints

Base URL: https://api.kompyl.com/v1 (production) or your self-hosted deployment URL

Compile

One-call content transformation

POST/compile-and-renderCompile and render content in one call. Creates job, parses, validates, plans, and renders.

Jobs

Fine-grained pipeline control for advanced workflows

POST/jobsCreate a new job with input content
GET/jobs/{job_id}Get job status, progress, and results
POST/jobs/{job_id}/parseParse input into Brain DSL
POST/jobs/{job_id}/validateValidate Brain with optional auto-fix
POST/jobs/{job_id}/planGenerate layout plan from Brain
POST/jobs/{job_id}/renderRender final artifact (PPTX, PDF, etc.)
GET/jobs/{job_id}/qaGet QA report with L&D validation

Artifacts

Download generated files

GET/artifacts/{artifact_id}Get artifact metadata
GET/artifacts/{artifact_id}/downloadDownload artifact file

Projects

Version control for content iterations

POST/projectsCreate a new project
GET/projectsList all projects
GET/projects/{project_id}Get project details with version counts
POST/projects/{project_id}/sourcesAdd a new source version
GET/projects/{project_id}/versionsList all versions (source, brain, render)
POST/projects/{project_id}/compileCompile source into brain version
POST/projects/{project_id}/renderRender brain into artifacts
POST/projects/{project_id}/renders/{render_id}/approveApprove a render version
POST/projects/{project_id}/renders/{render_id}/rejectReject a render version

Templates

Upload and manage PPTX templates

POST/templatesUpload a PPTX template file
GET/templatesList all templates
GET/templates/{template_id}Get template details
GET/templates/{template_id}/profileGet extracted template profile
POST/templates/{template_id}/profileExtract/refresh template profile
POST/templates/{template_id}/certifyRun certification tests

Webhooks

Async job notifications

POST/webhook-endpointsCreate a webhook endpoint
GET/webhook-endpointsList all webhook endpoints
GET/webhook-endpoints/{endpoint_id}Get endpoint details
PATCH/webhook-endpoints/{endpoint_id}Update endpoint configuration
DELETE/webhook-endpoints/{endpoint_id}Delete webhook endpoint
GET/webhook-deliveriesList delivery attempts with filters

Review Sessions

Share renders for external approval

POST/review-sessionsCreate a shareable review session
GET/review/{token}Get review data (no API key needed)
POST/review/{token}/approveApprove via token
POST/review/{token}/rejectReject via token
POST/review/{token}/commentsAdd comment to review
DATA MODELS

Request & Response Schemas

JobInput

{
  type: "text" | "url" | "file",
  value?: string,      // For text/url
  file_id?: string     // For file uploads
}

JobConstraints

{
  max_blocks: number,        // 5-100, default 30
  one_idea_per_block: bool,  // default false
  max_words_per_block: number // 10-200, default 50
}

CompileAndRenderRequest

{
  input: JobInput,
  preset_id?: "course" | "battlecard" | ...,
  mode?: "teaching" | "executive",
  language: "en" | "ar" | "auto",
  audience: "beginner" | "intermediate" | "advanced",
  constraints?: JobConstraints,
  format: "pptx" | "pdf",
  theme_id: string,
  template_id?: string,
  strict: boolean,
  auto_fix: boolean
}

CompileAndRenderResponse

{
  job_id: string,
  status: "queued" | "succeeded" | "failed",
  artifact_id: string,
  download_url: string,
  block_count: number,
  slide_count: number,
  dsl_version: string,
  warnings: string[],
  fixes_applied: string[]
}

Error Response

{
  "detail": "Error message describing what went wrong",
  "code": "VALIDATION_ERROR",
  "field": "input.value"
}

HTTP Status Codes: 200 (success), 201 (created), 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 429 (rate limited), 500 (server error)

TOOLS

SDKs & Resources

NO CODE REQUIRED

Try Our Free Tools

Don't need the API? Use any of our free AI tools directly in your browser — no signup or API key required.