Saltar al contenido principal

API Guide

By the end of this page, you'll understand how to authenticate to the Plexicus API, construct requests, handle pagination, and run real workflows like listing findings, triggering scans, and importing repositories.

Authentication​

All Plexicus API requests use HTTP Bearer token authentication. Your token is a secret key that identifies you and grants access to your organization's data.

API token vs. CLI token vs. MCP token​

Plexicus issues three types of tokens, each scoped to a specific use:

  • Personal API tokens (Settings → API Tokens): General-purpose programmatic access. Use for scripts, integrations, and the MCP server. See CLI Authentication & Tokens for lifecycle details.
  • CLI exchange tokens (plexicus login): Temporary, single-use tokens obtained by logging in via your browser. The CLI exchanges your browser session for a bearer token. See CLI Authentication & Tokens.
  • Plexalyzer tokens (Settings → Plexalyzer Token): Legacy connector tokens for automated workflows (deprecated; use personal API tokens instead).

For new integrations, generate a personal API token in Settings → API Tokens and use it here.

Bearer token format​

Include your token in the Authorization header:

Authorization: Bearer <your-api-token>
Accept: application/json

Example:

curl -H "Authorization: Bearer sk_live_abc123def456" \
     -H "Accept: application/json" \
     https://api.app.plexicus.ai/repositories

Handling authentication failures​

  • 401 Unauthorized: Token is invalid, expired, or revoked. Generate a new token in Settings → API Tokens.
  • 403 Forbidden: Token is valid but you lack permission for this endpoint. Verify your role and entitlements.

Base URLs​

SaaS (managed Plexicus)​

https://api.app.plexicus.ai

Self-hosted​

Replace with your self-hosted API URL:

https://plexicus.company.internal
https://plexicus.on-prem.local

Contact your Plexicus admin for the exact URL.

Request conventions​

Headers​

Every request must include:

Authorization: Bearer <your-api-token>
Accept: application/json
Content-Type: application/json (for POST/PUT/PATCH)

HTTP methods​

  • GET: Fetch data (read-only)
  • POST: Create a resource or trigger an action (202 for async operations)
  • PUT: Replace a resource
  • PATCH: Update part of a resource
  • DELETE: Remove a resource (204 No Content response)

Request body​

Send JSON in the request body for POST/PUT/PATCH:

{
  "name": "my-repo",
  "url": "https://github.com/example/repo"
}

Response format​

Success responses (2xx) include JSON:

{
  "id": "repo-123",
  "attributes": {
    "name": "example/repo",
    "url": "https://github.com/example/repo"
  }
}

Error responses (4xx/5xx) follow the RFC 7807 Problem Details format:

{
  "type": "urn:plexicus:invalid-token",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication failed — the API token is invalid, expired or revoked. Generate a new one in the Plexicus console."
}

Pagination​

List endpoints support cursor-based pagination. The response includes:

{
  "items": [...],
  "total": 42,
  "next": "/repositories?cursor=c2_abc123&limit=25"
}

Fetching the next page​

Extract the cursor from the next URL and pass it to the next request:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.app.plexicus.ai/repositories?limit=25&cursor=c2_abc123"

Default page size​

Most endpoints default to 25 items per page. Use the limit parameter to adjust (e.g., ?limit=100).

Common workflows​

List all repositories​

Fetch all repositories in your organization:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.app.plexicus.ai/repositories"

Response:

{
  "items": [
    {
      "id": "repo-123",
      "attributes": {
        "name": "example/backend",
        "url": "https://github.com/example/backend",
        "severity_counts": {
          "critical": 3,
          "high": 8,
          "medium": 12,
          "low": 5
        }
      }
    }
  ],
  "total": 42,
  "next": "/repositories?cursor=c2_xyz&limit=25"
}

Get a single repository​

Fetch details of one repository:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.app.plexicus.ai/repositories/repo-123"

List findings by severity​

List critical and high findings:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.app.plexicus.ai/findings?filters%5Bseverity%5D=critical,high"

Response:

{
  "items": [
    {
      "id": "f-456",
      "attributes": {
        "title": "SQL Injection in /api/users.py",
        "file": "api/users.py",
        "line": 42,
        "severity": "critical",
        "cwe": "CWE-89",
        "status": "open"
      }
    }
  ],
  "total": 11,
  "next": "/findings?cursor=c3_next&limit=25"
}

Trigger a scan​

Request a new application security scan:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repository_id":"repo-123","scan_type":"app"}' \
  "https://api.app.plexicus.ai/repository-scans"

Response:

{
  "status": "queued",
  "message": "Scan requested for repository repo-123. Poll the scan status endpoint to monitor progress."
}

Important: Scans run asynchronously. Typical duration: 5–15 minutes. Poll the repository endpoint to track status:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.app.plexicus.ai/repositories/repo-123"

Check the scan_status field in the response (e.g., "in-progress" → "completed").

Bulk-create repositories​

Import multiple repositories at once:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repositories": [
      {"name":"example/repo1","url":"https://github.com/example/repo1"},
      {"name":"example/repo2","url":"https://github.com/example/repo2"}
    ]
  }' \
  "https://api.app.plexicus.ai/repositories/bulk"

Generate an AI remediation​

Request the AI engine to create a fix for a finding:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"finding_id":"f-456","auto_create":false}' \
  "https://api.app.plexicus.ai/remediations"

Response:

{
  "status": "queued",
  "message": "Remediation generation requested for finding f-456. Poll get_remediation every 10s until status=ready."
}

Poll the remediation endpoint until it's ready:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.app.plexicus.ai/remediations?finding_id=f-456"

When ready, the response includes the diff and guidance fields.

Rate limiting and quotas​

Plexicus applies standard API rate limits to prevent abuse. Exact limits vary by plan:

  • Starter & Scale: ~1000 requests per hour per organization
  • Enterprise: Custom limits (contact sales)

Quota costs (AI Credits):

  • AI Remediation: 10 credits
  • False-Positive Detection: 5 credits
  • Deep Analysis: 20 credits
  • Report Import: 15 credits

Monitor your AI Credit usage in Settings → Billing. When you approach 75% or 90% of your monthly quota, you'll receive an in-app notification.

Handling rate limit (429)​

If you hit the rate limit, wait before retrying. Implement exponential backoff:

import time
import requests

max_retries = 3
for attempt in range(max_retries):
    response = requests.get(url, headers=headers)
    if response.status_code == 429:
        wait_time = 2 ** attempt  # 1s, 2s, 4s
        time.sleep(wait_time)
    elif response.ok:
        return response.json()
    else:
        break

API reference​

For complete endpoint documentation (parameters, response schemas, error codes), see the Platform API Reference.

The reference is auto-generated from the OpenAPI specification and stays in sync with the latest API version.