Overview

The Genesis API provides programmatic access to Contox's AI-powered codebase analysis. Use these endpoints to start scans, monitor progress, retrieve findings, and cancel running scans.

All Genesis endpoints require authentication via HMAC-SHA256 signatures. See HMAC Signing for details.

Start a scan

Starts a new Genesis Scan for a project. The scan runs asynchronously -- use the status endpoint to poll for progress.

POST /api/v2/genesis/start

Required headers

Header	Description
`Content-Type`	Must be `application/json`
`X-Contox-Project`	Your project ID
`X-Contox-Timestamp`	Unix timestamp used in signature
`X-Contox-Signature`	HMAC-SHA256 signature prefixed with `sha256=`

Request body

Field	Type	Required	Description
`projectId`	string	Yes	The project to scan
`branch`	string	No	Git branch to analyze. Defaults to `main`.
`maxFiles`	number	No	Maximum number of files to include. Defaults to `500`. Range: 1--5000.
`selective`	boolean	No	Only analyze files changed since the last scan. Defaults to `false`. Requires a previous completed scan.

Example request

bash

curl -X POST https://contox.dev/api/v2/genesis/start \
  -H "Content-Type: application/json" \
  -H "X-Contox-Project: proj_abc123" \
  -H "X-Contox-Timestamp: 1705312200" \
  -H "X-Contox-Signature: sha256=a1b2c3d4..." \
  -d '{
    "projectId": "proj_abc123",
    "branch": "main",
    "maxFiles": 500,
    "selective": false
  }'

Response

json

{
  "scanId": "scan_abc123def456",
  "status": "fetch_tree"
}

Field	Type	Description
`scanId`	string	Unique identifier for the scan
`status`	string	Initial scan phase (`fetch_tree`)

Error responses

Status	Error	Cause
400	`Invalid request body`	Missing or invalid fields
400	`No previous scan for selective mode`	Selective scan requested but no completed scan exists
401	`Invalid signature`	HMAC signature verification failed
404	`Project not found`	Invalid project ID
409	`Scan already in progress`	A scan is already running for this project
429	`Rate limit exceeded`	Too many requests

Get scan status

Returns the current status of the latest scan for a project.

GET /api/v2/genesis/status?projectId=X

Query parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	The project ID

Example request

bash

curl https://contox.dev/api/v2/genesis/status?projectId=proj_abc123 \
  -H "X-Contox-Project: proj_abc123" \
  -H "X-Contox-Timestamp: 1705312200" \
  -H "X-Contox-Signature: sha256=a1b2c3d4..."

Response

json

{
  "scan": {
    "id": "scan_abc123def456",
    "phase": "analyze",
    "progress": 0.45,
    "filesTotal": 320,
    "filesProcessed": 320,
    "chunksTotal": 87,
    "chunksProcessed": 39,
    "findingsCount": 24,
    "techStack": ["Next.js", "TypeScript", "Tailwind CSS"],
    "error": null,
    "startedAt": "2025-01-20T10:00:00Z",
    "completedAt": null
  }
}

Field	Type	Description
`id`	string	Scan identifier
`phase`	string	Current phase: `fetch_tree`, `fetch_files`, `build_chunks`, `analyze`, `synthesize`, `security_audit`, `assemble`, `complete`, or `failed`
`progress`	number	Overall progress as a float between 0.0 and 1.0
`filesTotal`	number	Total number of files in the scan
`filesProcessed`	number	Number of files downloaded and processed
`chunksTotal`	number	Total number of chunks created from files
`chunksProcessed`	number	Number of chunks analyzed so far
`findingsCount`	number	Running count of findings extracted
`techStack`	string[]	Technologies detected so far
`error`	string \| null	Error message if the scan failed, otherwise `null`
`startedAt`	string	ISO 8601 timestamp when the scan started
`completedAt`	string \| null	ISO 8601 timestamp when the scan completed, or `null` if still running

Polling pattern

Poll the status endpoint to track scan progress. A recommended polling interval:

Phase	Recommended interval
`fetch_tree`, `fetch_files`	Every 2 seconds
`build_chunks`	Every 2 seconds
`analyze`	Every 3 seconds
`synthesize`, `security_audit`	Every 5 seconds
`assemble`	Every 3 seconds

Stop polling when phase is complete or failed.

typescript

async function pollScanStatus(projectId: string): Promise<void> {
  let phase = '';
  while (phase !== 'complete' && phase !== 'failed') {
    const res = await fetch(`/api/v2/genesis/status?projectId=${projectId}`);
    const { scan } = await res.json();
    phase = scan.phase;

    // Update UI with scan.progress, scan.filesProcessed, etc.
    updateProgressUI(scan);

    const interval = ['analyze'].includes(phase) ? 3000 : 2000;
    await new Promise((r) => setTimeout(r, interval));
  }
}

Get scan results

Retrieves the full findings from a completed scan.

GET /api/v2/genesis/results?projectId=X

Query parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	The project ID

Example request

bash

curl https://contox.dev/api/v2/genesis/results?projectId=proj_abc123 \
  -H "X-Contox-Project: proj_abc123" \
  -H "X-Contox-Timestamp: 1705312200" \
  -H "X-Contox-Signature: sha256=a1b2c3d4..."

Response

json

{
  "findings": [
    {
      "id": "find_abc123",
      "layer": "architecture",
      "title": "Next.js 14 App Router with server components",
      "content": "The application uses Next.js 14 with the App Router...",
      "importance": 5,
      "files": [
        "src/app/layout.tsx",
        "src/app/dashboard/layout.tsx",
        "next.config.ts"
      ],
      "tags": ["next.js", "app-router", "server-components"],
      "createdAt": "2025-01-20T10:15:00Z"
    },
    {
      "id": "find_def456",
      "layer": "security",
      "title": "Missing rate limiting on authentication endpoints",
      "content": "The /api/auth/login and /api/auth/register endpoints...",
      "importance": 4,
      "files": [
        "src/app/api/auth/login/route.ts",
        "src/app/api/auth/register/route.ts"
      ],
      "tags": ["owasp", "rate-limiting", "authentication"],
      "createdAt": "2025-01-20T10:15:00Z"
    }
  ],
  "techStack": [
    { "name": "Next.js", "version": "14.2.0", "category": "framework" },
    { "name": "TypeScript", "version": "5.3.0", "category": "language" },
    { "name": "Tailwind CSS", "version": "4.0.0", "category": "styling" },
    { "name": "Appwrite", "version": "16.0.0", "category": "backend" }
  ],
  "summary": {
    "totalFindings": 47,
    "byLayer": {
      "product": 8,
      "architecture": 7,
      "dependencies": 6,
      "conventions": 9,
      "dataModel": 5,
      "entryPoints": 8,
      "security": 4
    },
    "scanDuration": 142,
    "filesAnalyzed": 320,
    "chunksAnalyzed": 87
  }
}

Finding object

Field	Type	Description
`id`	string	Unique finding identifier
`layer`	string	Analysis layer: `product`, `architecture`, `dependencies`, `conventions`, `dataModel`, `entryPoints`, `security`
`title`	string	Concise summary of the finding
`content`	string	Full finding details in markdown
`importance`	number	Significance score from 1 (low) to 5 (critical)
`files`	string[]	Source file paths that contributed to this finding
`tags`	string[]	Categorization tags
`createdAt`	string	ISO 8601 timestamp

Tech stack object

Field	Type	Description
`name`	string	Technology name
`version`	string	Detected version
`category`	string	Classification: `framework`, `language`, `styling`, `backend`, `database`, `testing`, `tooling`

Summary object

Field	Type	Description
`totalFindings`	number	Total number of findings across all layers
`byLayer`	object	Finding count per analysis layer
`scanDuration`	number	Total scan time in seconds
`filesAnalyzed`	number	Number of files processed
`chunksAnalyzed`	number	Number of chunks processed

Cancel a scan

Cancels a running scan. The current phase completes before the scan stops. Findings extracted up to the cancellation point are preserved.

POST /api/v2/genesis/cancel

Request body

Field	Type	Required	Description
`projectId`	string	Yes	The project to cancel the scan for

Example request

bash

curl -X POST https://contox.dev/api/v2/genesis/cancel \
  -H "Content-Type: application/json" \
  -H "X-Contox-Project: proj_abc123" \
  -H "X-Contox-Timestamp: 1705312200" \
  -H "X-Contox-Signature: sha256=a1b2c3d4..." \
  -d '{
    "projectId": "proj_abc123"
  }'

Response

json

{
  "scanId": "scan_abc123def456",
  "status": "cancelled",
  "findingsPreserved": 24
}

Field	Type	Description
`scanId`	string	The cancelled scan's identifier
`status`	string	Always `cancelled`
`findingsPreserved`	number	Number of findings preserved from the partial scan

Error responses

Status	Error	Cause
400	`No scan in progress`	No active scan exists for this project
401	`Invalid signature`	HMAC signature verification failed
404	`Project not found`	Invalid project ID

Next steps

Genesis Scan Concepts -- How Genesis Scan works
Genesis Dashboard -- Using the Genesis UI
HMAC Signing -- Signing API requests
Rate Limits -- API rate limit details

V2 Ask

API Keys

On this page