Believe Security - Documentation

Believe Security provides a comprehensive REST API that allows you to integrate security scanning directly into your development workflow, CI/CD pipelines, and custom tools. This reference documents all available endpoints, request parameters, and response formats.

Authentication

All API requests require authentication using an API key. You can generate and manage API keys from your Believe Security account settings.

curl -X GET https://api.believesecurity.xyz/v1/analyses \
  -H "Authorization: Bearer YOUR_API_KEY"

Security Best Practices

Never expose your API key in client-side code
Store API keys securely as environment variables or in your CI/CD platform's secret management
Rotate your API keys periodically

Base URL

All API endpoints are relative to the following base URL:

https://api.believesecurity.xyz/v1

Rate Limits

API requests are subject to rate limiting based on your subscription plan. Current limits:

Plan	Request Limit	Analysis Limit
Free	60 per hour	5 per day
Developer	300 per hour	30 per day
Team	1,000 per hour	100 per day
Enterprise	Custom	Custom

Rate limit headers are included in all API responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1623456789

Endpoints

POST

/analyze

Start a new analysis

Request Parameters

{
  "source": {
    "type": "github",      // Required: "github", "program_id", or "file_url"
    "url": "string",       // Required for github and file_url types
    "program_id": "string" // Required for program_id type
  },
  "analysis_depth": "quick", // Optional: "quick", "full", or "continuous" (default: "quick")
  "options": {
    "include_best_practices": true,  // Optional (default: true)
    "generate_remediation": true,    // Optional (default: true)
    "scan_dependencies": true        // Optional (default: false)
  },
  "callback_url": "string"  // Optional: URL to receive completion notification
}

Response

{
  "analysis_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "status": "queued",
  "created_at": "2025-06-15T12:30:45Z",
  "estimated_completion_time": "2025-06-15T12:32:45Z"
}

Example

curl -X POST https://api.believesecurity.xyz/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "github",
      "url": "https://github.com/username/repo-name"
    },
    "analysis_depth": "full",
    "options": {
      "include_best_practices": true,
      "generate_remediation": true,
      "scan_dependencies": true
    }
  }'

GET

/analyses/{analysis_id}

Get analysis status and results

Path Parameters

Parameter	Type	Description
analysis_id	string	The ID of the analysis

Response

{
  "analysis_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "status": "completed", // "queued", "in_progress", "completed", "failed"
  "created_at": "2025-06-15T12:30:45Z",
  "completed_at": "2025-06-15T12:32:15Z",
  "source": {
    "type": "github",
    "url": "https://github.com/username/repo-name"
  },
  "results": {
    "vulnerabilities": [
      {
        "id": "VUL-123",
        "type": "missing_signer_verification",
        "severity": "critical",
        "title": "Missing Signer Verification",
        "description": "The program does not verify that the authority account is a signer, allowing unauthorized transactions.",
        "location": {
          "file": "src/processor.rs",
          "line_start": 142,
          "line_end": 150
        },
        "remediation": "Add a check to verify the authority account is a signer using the is_signer field.",
        "remediation_code": "if !authority.is_signer {
    return Err(ProgramError::MissingRequiredSignature);
}"
      }
      // Additional vulnerabilities...
    ],
    "summary": {
      "critical": 1,
      "high": 2,
      "medium": 3,
      "low": 5,
      "total": 11
    }
  }
}

Example

curl -X GET https://api.believesecurity.xyz/v1/analyses/a1b2c3d4-e5f6-7890-abcd-1234567890ab \
  -H "Authorization: Bearer YOUR_API_KEY"

GET

/analyses

List your analyses

Query Parameters

Parameter	Type	Description
limit	integer	Maximum number of results (default: 20, max: 100)
offset	integer	Number of results to skip (default: 0)
status	string	Filter by status: "queued", "in_progress", "completed", "failed"

Response

{
  "analyses": [
    {
      "analysis_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
      "status": "completed",
      "created_at": "2025-06-15T12:30:45Z",
      "completed_at": "2025-06-15T12:32:15Z",
      "source": {
        "type": "github",
        "url": "https://github.com/username/repo-name"
      },
      "summary": {
        "critical": 1,
        "high": 2,
        "medium": 3,
        "low": 5,
        "total": 11
      }
    },
    // Additional analyses...
  ],
  "pagination": {
    "total": 43,
    "limit": 20,
    "offset": 0
  }
}

Example

curl -X GET "https://api.believesecurity.xyz/v1/analyses?limit=10&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. Error responses include a JSON object with details about the error.

{
  "error": {
    "code": "invalid_source",
    "message": "The provided GitHub repository URL is invalid or inaccessible",
    "details": "Please ensure the repository exists and is accessible with the provided credentials"
  }
}

Status Code	Description
200 OK	The request was successful
400 Bad Request	The request was invalid or missing required parameters
401 Unauthorized	Authentication failed or API key is missing
403 Forbidden	The API key doesn't have permission to access the resource
404 Not Found	The requested resource was not found
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	An error occurred on the server

Webhooks

Believe Security can send webhooks to notify your systems when analyses are completed. To use webhooks, provide a callback_url parameter when starting an analysis.

Webhook Payload

{
  "event": "analysis.completed",
  "analysis_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "status": "completed",
  "created_at": "2025-06-15T12:30:45Z",
  "completed_at": "2025-06-15T12:32:15Z",
  "summary": {
    "critical": 1,
    "high": 2,
    "medium": 3,
    "low": 5,
    "total": 11
  }
}

Webhook Events

Event	Description
analysis.started	An analysis has started processing
analysis.completed	An analysis has completed successfully
analysis.failed	An analysis has failed

Securing Webhooks

All webhook requests include a signature in the X-Believe-Signature header. You should verify this signature to ensure the webhook came from Believe Security.

// Example signature verification in Node.js
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const calculatedSignature = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(calculatedSignature)
  );
}

// Usage
const isValid = verifySignature(
  webhookPayload,
  request.headers['x-believe-signature'],
  'your_webhook_secret'
);

if (isValid) {
  // Process the webhook
} else {
  // Reject the webhook
}

Code Examples

Here are some examples of how to use the Believe Security API in different programming languages.

Node.js

const axios = require('axios');

async function startAnalysis() {
  try {
    const response = await axios.post(
      'https://api.believesecurity.xyz/v1/analyze',
      {
        source: {
          type: 'github',
          url: 'https://github.com/username/repo-name'
        },
        analysis_depth: 'full',
        options: {
          include_best_practices: true,
          generate_remediation: true,
          scan_dependencies: true
        }
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Analysis started:', response.data);
    return response.data.analysis_id;
  } catch (error) {
    console.error('Error starting analysis:', error.response?.data || error.message);
  }
}

Python

import requests
import json

def start_analysis():
    url = "https://api.believesecurity.xyz/v1/analyze"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    payload = {
        "source": {
            "type": "github",
            "url": "https://github.com/username/repo-name"
        },
        "analysis_depth": "full",
        "options": {
            "include_best_practices": True,
            "generate_remediation": True,
            "scan_dependencies": True
        }
    }
    
    try:
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
        result = response.json()
        print(f"Analysis started: {result}")
        return result["analysis_id"]
    except requests.exceptions.RequestException as e:
        print(f"Error starting analysis: {e}")
        return None

API Reference

Authentication

Security Best Practices

Base URL

Rate Limits

Endpoints

Request Parameters

Response

Example

Path Parameters

Response

Example

Query Parameters

Response

Example

Error Handling

Webhooks

Webhook Payload

Webhook Events

Securing Webhooks

Code Examples

Node.js

Python