API Documentation

Everything you need to integrate with the CodeVF API and official SDKs.

Main hours: 8am-8pm EST. We’re actively working toward 24/7 availability; responses may be slower outside these hours for now.

Quick Start

Get Your API Key

Create an API key from your dashboard

Create a Project

curl -X POST https://codevf.com/api/v1/projects/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Project"
  }'

Create a Task

curl -X POST https://codevf.com/api/v1/tasks/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Review this auth flow for security issues",
    "projectId": 123,
    "mode": "fast",
    "maxCredits": 3000
  }'

Poll for Results

curl https://codevf.com/api/v1/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

All API requests require authentication using an API key sent in the Authorization header:

Authorization: Bearer cvf_test_your_key_here

Keep Your API Key Secret

Never commit API keys to version control or expose them in client-side code.

API Endpoints

Submit a task for review by a human engineer.

Request Body

Parameter	Type	Required	Description
`prompt`	string	Required	Your question or review request (10-10,000 chars)
`maxCredits`	number	Required	Maximum credits to spend (60-115200)
`projectId`	number	Required	Project to attach this task to (from POST /projects/create)
`mode`	enum	Optional	Service level: `realtime_answer`, `fast`, `standard` (default: standard)
`metadata`	object	Optional	Custom metadata for your reference
`idempotencyKey`	string	Optional	UUID for idempotent requests
`attachments`	array	Optional	File attachments (max 5)
`tagId`	number	Optional	Engineer expertise level (see GET /tags for options). Affects final cost via multiplier.
`responseSchema`	object	Optional	JSON Schema defining structured response format • AI generates response matching your schema • Best for: data extraction, structured code analysis, API data generation

Service Modes

Most responses still land under 5 minutes; priority order still applies.

realtime_answer (2x multiplier)

Instant human response • 60-600 credits

fast (1.5x multiplier)

Response within 4 hours • 240-115200 credits

standard (1x multiplier)

Response within 24 hours • 240-115200 credits

File Attachments

Up to 5 files are supported. Each attachment requires:

fileName: The name of the file
fileSize: Size in bytes (max 50MB)
mimeType: File type (e.g. application/pdf, text/plain)
data: Base64-encoded file content

📊 Structured Responses (JSON Schema)

New: Define a JSON Schema to get structured, type-safe responses perfect for programmatic consumption.

✅ When to use: Data extraction, code analysis results, API data generation

⚡ realtime_answer mode: Instant AI-generated response (no engineer needed)

👨‍💻 Other modes: Engineer validates/refines AI-generated output

Example: Structured Response Schema

{
  "prompt": "Analyze this codebase for security issues",
  "projectId": 123,
  "mode": "realtime_answer",
  "maxCredits": 150,
  "responseSchema": {
    "type": "object",
    "properties": {
      "vulnerabilities": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "severity": { 
              "type": "string", 
              "enum": ["critical", "high", "medium", "low"] 
            },
            "description": { "type": "string" },
            "location": { "type": "string" },
            "recommendation": { "type": "string" }
          },
          "required": ["severity", "description"]
        }
      },
      "securityScore": { 
        "type": "number", 
        "minimum": 0, 
        "maximum": 100 
      }
    },
    "required": ["vulnerabilities", "securityScore"]
  }
}

Response will have result field with data matching your schema exactly.

Example Request (with Attachments)

{
  "prompt": "Review this React component for security issues",
  "projectId": 123,
  "mode": "fast",
  "maxCredits": 4500,
  "metadata": {
    "environment": "production"
  },
  "attachments": [
    {
      "fileName": "screenshot.png",
      "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJ...",
      "mimeType": "image/png"
    },
    {
      "fileName": "error.log",
      "content": "Error: Cannot read property 'user' of undefined...",
      "mimeType": "text/plain"
    }
  ]
}

Response

{
  "id": "task_abc123xyz",
  "status": "pending",
  "mode": "fast",
  "maxCredits": 3000,
  "tagIdUsed": 1,
  "expertiseMultiplier": 1.7,
  "createdAt": "2025-12-18T10:00:00Z"
}

Code Examples

import requests
import base64
import time

API_KEY = "cvf_test_your_key_here"
BASE_URL = "https://codevf.com/api/v1"

# Read and encode image file
with open("screenshot.png", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode()

# Create task with attachments
response = requests.post(
    f"{BASE_URL}/tasks/create",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "prompt": "Review this UI flow and check the screenshot",
        "projectId": 123,
        "mode": "fast",
        "maxCredits": 4500,
        "attachments": [
            {
                "fileName": "screenshot.png",
                "content": image_base64,
                "mimeType": "image/png"
            },
            {
                "fileName": "error.log",
                "content": "Error: Authentication failed at login.py:42",
                "mimeType": "text/plain"
            }
        ]
    }
)
task = response.json()
task_id = task["id"]

# Poll for completion
while True:
    response = requests.get(
        f"{BASE_URL}/tasks/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    task = response.json()

    if task["status"] == "completed":
        print("Result:", task["result"]["message"])
        break
    elif task["status"] == "cancelled":
        print("Task was cancelled")
        break

    time.sleep(10)

Error Codes

400

Bad Request

Invalid parameters or malformed request

401

Unauthorized

Invalid or missing API key

402

Payment Required

Insufficient credits in your account

404

Not Found

Task does not exist or you lack access

408

Request Timeout

No engineer available or request timed out

409

Conflict

Idempotency key already used by different API key

413

Payload Too Large

Request body exceeds 150KB limit

429

Too Many Requests

Rate limit exceeded (1 req/sec / 3,600/hour)

500

Internal Server Error

Something went wrong on our end

📋 Standardized Error Response Format

All API errors return a consistent JSON structure with error codes, messages, and contextual details for programmatic handling.

Example: Insufficient Credits (402)

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits to complete this operation",
    "details": {
      "available": 600,
      "required": 3000
    }
  }
}

Example: Unauthorized (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Example: Rate Limited (429)

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "retry_after": 60,
    "reset_at": "2026-02-14T12:00:00Z",
    "limit": "1 req/sec"
  }
}

Example: Invalid Request (400)

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Validation failed",
    "details": {
      "errors": [
        {
          "field": "prompt",
          "message": "Prompt must be at least 10 characters"
        },
        {
          "field": "maxCredits",
          "message": "Must be between 60 and 115200"
        }
      ]
    }
  }
}

💡 SDK Integration: Our JavaScript and Python SDKs automatically parse these error responses into typed exception classes with helper methods. See SDK Error Handling for examples.