API Reference¶

The PADAI backend exposes a REST API on port 8000 (default). All endpoints require authentication via Bearer token or Basic authentication.

Authentication¶

Include your API token in the Authorization header:

Authorization: Bearer your-api-token

Or use Basic authentication if configured with AUTH_USERNAME / AUTH_PASSWORD_HASH.

Core Endpoints¶

Health Check¶

GET /api/healthz

Returns server status, license validity, and version information. No authentication required.

Response:

{
  "status": "ok",
  "license": "ok",
  "version": "1.0.0"
}

Generate Code (Plan)¶

POST /api/plan

Generate PAD (Robin) code from a natural language prompt.

Request body:

{
  "prompt": "Create a flow that copies all .xlsx files from C:\\Import to C:\\Archive",
  "context": {
    "subflows": ["Main"],
    "current_code": ""
  }
}

Response:

{
  "run_id": "abc123",
  "status": "success",
  "pad_text": "# Generated Robin code...",
  "plan": { ... },
  "lint_issues": [],
  "stats": {
    "total_steps": 5,
    "actions_used": ["Folder.GetFiles", "File.Copy"]
  }
}

Patch Code¶

POST /api/patch

Apply targeted modifications to existing PAD code. Supports both LLM-driven and deterministic patching.

Request body:

{
  "prompt": "Add error handling around the file copy step",
  "current_code": "# Existing Robin code...",
  "patch_mode": "llm"
}

Fix Warnings¶

POST /api/fix-warnings

Automatically fix warnings in PAD code (placeholders, invalid paths, missing function ends).

Request body:

{
  "code": "# Robin code with warnings...",
  "warnings": [
    {"code": "placeholder_detected", "line": 5}
  ]
}

Generate Flowchart¶

POST /api/flowchart

Generate a Mermaid diagram from PAD code.

Request body:

{
  "code": "# Robin code...",
  "prompt": "Generate a flowchart of this flow"
}

Analysis Endpoints¶

Analyze Quality¶

POST /api/analyze-quality

Analyze code quality and return a score with metrics.

Analyze Variables¶

POST /api/analyze-variables

Inspect and analyze variables in PAD code.

Suggest Refactoring¶

POST /api/suggest-refactoring

Get refactoring suggestions for PAD code.

Compare Flows¶

POST /api/compare-flows

Diff and compare two versions of a PAD flow.

Run Management¶

Recent Runs¶

GET /api/recent-runs

List recent code generation runs with status and metadata.

Get Run¶

GET /api/runs/{run_id}

Get details of a specific run.

Get Run PAD Code¶

GET /api/runs/{run_id}/pad

Get the generated PAD code for a specific run.

Run Status¶

GET /api/run-status/{run_id}

Check the status of a running generation.

License Management¶

License Status¶

GET /api/license/status

Returns current license status, quotas, features, and expiration date.

Response:

{
  "valid": true,
  "plan": "pro_team",
  "max_users": 5,
  "max_runs_per_month": 5000,
  "current_runs": 142,
  "expires": "2027-04-12",
  "features": ["workbench", "fleet", "audit"]
}

Error Handling Endpoints¶

Analyze Error Handling¶

POST /api/analyze-error-handling

Identify unprotected actions in PAD code.

Generate Error Handlers¶

POST /api/generate-error-handlers

Automatically generate error handling blocks for PAD code.

Documentation Generation¶

Generate Docs¶

POST /api/generate-docs

Generate technical documentation for a PAD flow.

Snippet Library¶

List Snippets¶

GET /api/snippets

List all available code snippets.

Get Snippet Categories¶

GET /api/snippets/categories

List snippet categories.

Render Snippet¶

POST /api/snippets/render

Render a snippet with custom parameters.

HTTP Status Codes¶

Code	Meaning
200	Success
400	Invalid request (check your parameters)
401	Authentication failed (check your API token)
402	License expired or run quota exceeded
429	Rate limit exceeded (wait and retry)
500	Internal server error

Rate Limiting¶

When rate limiting is enabled (RATE_LIMIT_ENABLED=true), the server enforces a maximum number of requests per minute (RATE_LIMIT_PER_MIN, default 120). Exceeding this limit returns HTTP 429.

Version¶

GET /api/version

Returns the current server version and build information.