Common API Tasks

curl examples for common BlockSecOps API operations.

---

Contracts

Upload Contract

curl -X POST "https://api.blocksecops.com/api/v1/contracts/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "project_id=abc123"

List Contracts

curl -X GET "https://api.blocksecops.com/api/v1/contracts?first=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Projects

Create Project

curl -X POST "https://api.blocksecops.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DeFi Protocol",
    "description": "Main DeFi contracts"
  }'

---

Scans

Start Scan

curl -X POST "https://api.blocksecops.com/api/v1/scans" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": "abc123",
    "preset": "standard"
  }'

Get Scan Status

curl -X GET "https://api.blocksecops.com/api/v1/scans/{scan_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Recent Scans

curl -X GET "https://api.blocksecops.com/api/v1/scans?per_page=10&sort=-created_at" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Status

curl -X GET "https://api.blocksecops.com/api/v1/scans?status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Date Range

curl -X GET "https://api.blocksecops.com/api/v1/scans?created_after=2025-01-01&created_before=2025-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Vulnerability Management

List Vulnerabilities

curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?severity=critical&first=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Status

curl -X PATCH "https://api.blocksecops.com/api/v1/vulnerabilities/{vuln_id}/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "acknowledged"}'

Get Vulnerabilities by Severity

# Get critical vulnerabilities
curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?severity=critical" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get high and critical
curl -X GET "https://api.blocksecops.com/api/v1/vulnerabilities?severity=critical,high" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Vulnerability Status

curl -X PATCH "https://api.blocksecops.com/api/v1/vulnerabilities/{vuln_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "acknowledged",
    "notes": "Will fix in next release"
  }'

Mark as False Positive

curl -X PATCH "https://api.blocksecops.com/api/v1/vulnerabilities/{vuln_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "false_positive",
    "reason": "Intentional behavior for admin functions"
  }'

---

Audit Logs

List Audit Logs

curl -X GET "https://api.blocksecops.com/api/v1/audit-logs?resource_type=scan&first=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Export Reports

JSON Export

curl -X GET "https://api.blocksecops.com/api/v1/scans/{scan_id}/export?format=json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o report.json

PDF Report

curl -X GET "https://api.blocksecops.com/api/v1/scans/{scan_id}/export?format=pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o report.pdf

SARIF Format (for GitHub)

curl -X GET "https://api.blocksecops.com/api/v1/scans/{scan_id}/export?format=sarif" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o results.sarif

---

Webhook Configuration

Create Webhook

curl -X POST "https://api.blocksecops.com/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["scan.completed", "scan.failed"],
    "secret": "your-webhook-secret"
  }'

List Webhooks

curl -X GET "https://api.blocksecops.com/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Test Webhook

curl -X POST "https://api.blocksecops.com/api/v1/webhooks/{webhook_id}/test" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Organization Management

List Organization Members

curl -X GET "https://api.blocksecops.com/api/v1/organizations/{org_id}/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

Invite Member

curl -X POST "https://api.blocksecops.com/api/v1/organizations/{org_id}/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "member"
  }'

---

Error Handling

Robust Error Handler

import requests

def api_call(method, endpoint, **kwargs):
    """Make API call with error handling."""
    url = f'{API_URL}{endpoint}'

    try:
        response = requests.request(method, url, headers=headers, **kwargs)

        # Rate limiting
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            raise RateLimitError(f"Rate limited. Retry after {retry_after}s")

        # Auth errors
        if response.status_code == 401:
            raise AuthenticationError("Invalid API key")

        if response.status_code == 403:
            raise PermissionError("Insufficient permissions")

        # Not found
        if response.status_code == 404:
            raise NotFoundError(f"Resource not found: {endpoint}")

        # Server errors
        if response.status_code >= 500:
            raise ServerError("API server error. Please retry.")

        response.raise_for_status()
        return response.json()

    except requests.exceptions.ConnectionError:
        raise NetworkError("Failed to connect to API")
    except requests.exceptions.Timeout:
        raise TimeoutError("API request timed out")