Skip to main content

Python SDK

The official Python SDK provides type-safe, programmatic access to all Precogs security scanning features.

Installation​

Install the official package from PyPI:

pip install precogs-sdk

Requirements: Python 3.8+

Environment Variables​

VariableDescriptionDefault
PRECOGS_API_KEYYour project API key (pk_live_...)(None)
PRECOGS_BASE_URLOverride API endpoint (for local development)https://api.precogs.ai/api/v1

Quick Start​

from precogs import PrecogsClient

# Initialize with your API key
client = PrecogsClient(api_key="pk_live_xxxxxxxxxxxx")

# Or use environment variable (recommended)
# export PRECOGS_API_KEY=pk_live_xxxxxxxxxxxx
client = PrecogsClient()

# List your projects
projects = client.projects.list()
for project in projects:
    print(f"Project: {project['name']}")

# Trigger a security scan
scan = client.scans.trigger_code_scan(project_id="proj_123")
print(f"Scan started: {scan['id']}")

# Get critical vulnerabilities
vulns = client.vulnerabilities.list(severity="critical")
for vuln in vulns:
    print(f"[{vuln['severity']}] {vuln['title']}")

Authentication​

Get your API key from Settings → API Keys in the Precogs Dashboard.

# Option 1: Direct initialization
client = PrecogsClient(api_key="pk_live_xxx")

# Option 2: Environment variable (recommended)
import os
os.environ["PRECOGS_API_KEY"] = "pk_live_xxx"
client = PrecogsClient()
Security Best Practice

Never hardcode API keys in source code. Use environment variables or secret management tools.

API Resources​

Projects​

# List all projects
projects = client.projects.list()

# Get project details
project = client.projects.get("proj_123")

# Create a new project
project = client.projects.create(
    name="My App",
    repo_url="https://github.com/org/repo",
    provider="github",  # or "gitlab", "bitbucket"
    branch="main"
)

Scans​

# Code security scan (SAST)
scan = client.scans.trigger_code_scan(project_id="proj_123", branch="develop")

# Dependency scan (SCA)
scan = client.scans.trigger_dependency_scan(project_id="proj_123")

# Infrastructure as Code scan
scan = client.scans.trigger_iac_scan(project_id="proj_123")

# Container image scan
scan = client.scans.trigger_container_scan(
    project_id="proj_123",
    image="nginx:latest"
)

# Get scan results
results = client.scans.get_results(scan_id="scan_456")

Vulnerabilities​

# List with filters
vulns = client.vulnerabilities.list(
    project_id="proj_123",
    severity="high",
    status="open",
    limit=50
)

# Get details
vuln = client.vulnerabilities.get("vuln_789")

# Get AI-generated fix
fix = client.vulnerabilities.get_ai_fix("vuln_789")
print(fix['suggestedCode'])

# Update status
client.vulnerabilities.update_status(
    vuln_id="vuln_789",
    status="fixed",
    reason="Patched in v2.1.0"
)

Dashboard​

# Security overview
overview = client.dashboard.get_overview()

# Severity distribution
dist = client.dashboard.get_severity_distribution()

# Trend over time
trend = client.dashboard.get_trend(days=30)

Error Handling​

from precogs import (
    PrecogsClient,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    InsufficientTokensError
)

try:
    client = PrecogsClient()
    projects = client.projects.list()
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except InsufficientTokensError:
    print("Upgrade your plan for more tokens")
except NotFoundError:
    print("Resource not found")

Context Manager​

The SDK supports the context manager pattern for automatic cleanup:

with PrecogsClient() as client:
    projects = client.projects.list()
# Connection automatically closed

Next Steps​