API Documentation

LUCID API

Two pipelines for AI code quality. Forward verifies existing code by extracting claims and checking them. Reverse generates verified code from a task description using formal specifications.

Base URLhttps://api.trylucid.dev

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from the dashboard.

http

Authorization: Bearer lk_live_<64 hex characters>

Keys are prefixed with lk_live_ for production and lk_test_ for sandbox environments.

Forward Pipeline — Verify Code

POST/api/v1/forward

Submit existing code for verification. LUCID extracts testable claims from the code, verifies each claim against the implementation, and generates remediation tasks for any failures.

Request Body

Field	Type	Required	Description
code	string	Required	Source code to verify
language	string	Optional	Programming language. Default: `"typescript"`
context	string	Optional	Additional context about what the code should do

Response

json

{
  "request_id": "req_m1abc_x7k2f9",
  "code": "function add(a, b) { return a - b; }",
  "language": "typescript",
  "claims": {
    "count": 5,
    "items": [
      { "id": "CLAIM-001", "category": "correctness", "severity": "critical",
        "description": "Function claims to add two numbers",
        "assertion": "add(1, 2) should return 3" }
    ]
  },
  "verification": {
    "passed": 3, "failed": 1, "partial": 1, "total": 5,
    "items": [
      { "claimId": "CLAIM-001", "verdict": "FAIL",
        "reasoning": "Returns a - b, not a + b",
        "evidence": "return a - b" }
    ]
  },
  "remediation": {
    "count": 2,
    "items": [
      { "claimId": "CLAIM-001", "title": "Fix subtraction to addition",
        "action": "modify", "severity": "critical",
        "codeGuidance": "Change 'return a - b' to 'return a + b'" }
    ]
  }
}

How it works

Extract — Identifies testable claims (correctness, security, edge cases)
Verify — Checks each claim against the actual implementation
Remediate — Generates fix tasks for failed or partial claims

Reverse Pipeline — Generate Code

POST/api/v1/reverse

Generate verified code from a task description. LUCID synthesizes formal specifications, derives constraints, generates code guided by those specs, then self-verifies the result.

Request Body

Field	Type	Required	Description
task	string	Required	Description of what the code should do
language	string	Optional	Target language. Default: `"typescript"`

Response

json

{
  "request_id": "req_m1def_y8m3g0",
  "task": "Write a rate limiter using sliding window algorithm",
  "language": "typescript",
  "code": "class SlidingWindowRateLimiter { ... }",
  "specs": { "count": 22, "items": [...] },
  "constraints": { "count": 15, "items": [...] },
  "verification": {
    "satisfied": 21, "total": 22, "percentage": 95.5,
    "items": [...]
  }
}

How it works

Synthesize — Generates 10-30 formal specifications from the task
Constrain — Derives must/must-not constraints + domain patterns
Generate — Produces code guided by specs and constraints
Verify — Self-checks the generated code against all specs

Code Examples

Get started quickly with these integration examples.

Forward Pipeline (Verify Code)

Python

python

import requests

response = requests.post(
    "https://api.trylucid.dev/api/v1/forward",
    headers={"Authorization": "Bearer lk_live_YOUR_API_KEY"},
    json={
        "code": """def add(a, b):
    return a - b  # Bug: should be a + b""",
        "language": "python",
        "context": "Function should add two numbers"
    }
)

result = response.json()
print(f"Claims: {result['claims']['count']}")
print(f"Passed: {result['verification']['passed']}/{result['verification']['total']}")
for fix in result["remediation"]["items"]:
    print(f"  Fix: {fix['title']}")

Node.js

javascript

const response = await fetch("https://api.trylucid.dev/api/v1/forward", {
  method: "POST",
  headers: {
    "Authorization": "Bearer lk_live_YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    code: "function add(a, b) { return a - b; }",
    language: "typescript",
    context: "Function should add two numbers",
  }),
});

const { verification, remediation } = await response.json();
console.log(`${verification.passed}/${verification.total} claims passed`);
remediation.items.forEach(fix => console.log(`Fix: ${fix.title}`));

cURL

bash

curl -X POST https://api.trylucid.dev/api/v1/forward \
  -H "Authorization: Bearer lk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "function add(a, b) { return a - b; }",
    "language": "typescript",
    "context": "Function should add two numbers"
  }'

Reverse Pipeline (Generate Code)

cURL

bash

curl -X POST https://api.trylucid.dev/api/v1/reverse \
  -H "Authorization: Bearer lk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Write a rate limiter using sliding window algorithm",
    "language": "typescript"
  }'

Rate Limits

Rate limits and monthly quotas vary by tier.

Plan	Price	Verifications / mo	Rate
Free	$0	100	5 req/min
Pro	$49/mo	1,000	20 req/min
Team	$149/mo	5,000	60 req/min

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating seconds to wait.

Error Codes

The API uses standard HTTP status codes. Errors include a JSON body with details.

Code	Meaning
400	Invalid request body — missing required fields or malformed JSON
401	Missing or invalid API key
405	Method not allowed — use POST for pipelines, GET for usage
429	Rate limit or monthly quota exceeded — check Retry-After header
500	Internal server error — retry with exponential backoff

Error Response Format

json

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: entry_point"
  }
}

Ready to ship verified code?

Get your API key and start verifying in minutes.

Get API Key