Skip to main content

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 uses three kinds of tokens, each for 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 tokens (plexicus login): Logging in through your browser creates a personal API token named CLI - <date> that the CLI stores locally. It is listed in Settings → API Tokens, where you can revoke it. See CLI Authentication & Tokens.
  • CI/CD scanner token, also called the Plexalyzer token (Settings → API Tokens, CI/CD scanner token section): Organization-level token for the Plexalyzer scanner in your CI/CD pipelines, such as the Plexicus GitHub Action. It is not for general API calls; see Organization Settings.

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 <your-api-token>" \
-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_code": 202,
"message": "Code scan request accepted"
}

scan_type is app (code scan) or sbom; any other value returns 400. Optional files limits the scan to the listed paths.

Important: Scans run asynchronously. List the scan runs of the repository to follow progress:

curl -H "Authorization: Bearer $TOKEN" \
"https://api.app.plexicus.ai/scan-runs?repository_id=repo-123"

The status of each run is the derived scan state (running, stalled, completed, failed, failed_partial or finalized_by_user).

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:

{
"run_id": "<id of the remediation flow>"
}

The request is accepted with 202 and the finding's remediation flow starts; it responds 409 while the finding is pending false-positive review. Poll the remediation endpoint until the remediation exists (it answers 404 until then):

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 rate limits per endpoint to prevent abuse and answers 429 Too Many Requests when you exceed them. Contact Plexicus if you need higher limits for an integration.

AI credits: AI actions such as remediation, false-positive validation, Deep Code Analysis and report import consume AI credits from your monthly allowance. Settings → Usage shows the credits per action and your history; Settings → Billing shows your allowance. You receive in-app notifications as you approach 75% and 90% of it.

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.