Apex service API

Use the local CLI or stdio MCP when a person or coding agent needs direct access to a repository checkout. Use hosted MCP when an agent needs a production HTTPS endpoint with a static organization credential. Use the REST API when an application needs explicit HTTP and JSON control, including local archive uploads.

The machine-readable contract is available at /api/apex/v1/openapi.json.

• For remote scans, connect the GitHub repository to the same Apex organization that owns the service key. The first API scan can create and link its workspace automatically.
• For remote scans, use a full 40- or 64-character Git commit SHA. Branch names and moving refs are not accepted.
• For local or non-Git directories, package the source as tar.gz. The API creates the workspace and signed archive upload; no Git remote or website scan is required.
• Generate or revoke keys as an Apex organization manager or administrator.
• Store the key in a secret manager. Apex displays the raw secret only once and stores only its hash.

1. 1
   Open company Settings

   From the company dashboard, open Settings and find Service API keys.
2. 2
   Generate the key

   Select Generate key, give the key a descriptive name, choose the scopes it needs, and set an expiration.
3. 3
   Save the one-time secret

   Copy the secret into your secret manager before closing the dialog. Apex cannot display it again.

Prefer the smallest set of scopes the integration needs. Use only scans:read and findings:read when a key polls existing scans and imports findings; add scans:create when it must start or cancel scans.

CLI alternative

Managers and administrators can also generate, list, and revoke service keys from their own terminal with Apex CLI.

$ apex update
$ apex login
# Replace this placeholder with a future ISO-8601 timestamp from your rotation policy:
$ FUTURE_ISO_8601_TIMESTAMP="YYYY-MM-DDTHH:MM:SSZ"
# Read-only key with an explicit expiration:
$ apex service-key create --name "Audit hub" --scope scans:read,findings:read --expires-at "$FUTURE_ISO_8601_TIMESTAMP"
# Omit --scope only when this key must also trigger scans:
$ apex service-key create --name "Audit hub" --expires-at "$FUTURE_ISO_8601_TIMESTAMP"
# Optional machine-readable output:
$ apex service-key create --name "Audit hub" --scope scans:read,findings:read --expires-at "$FUTURE_ISO_8601_TIMESTAMP" --json

Apex CLI 0.1.16 and later automatically uses your company when only one is available. If you belong to multiple companies, it asks you to choose. Use --company <id-or-handle> to skip that prompt, or when a non-interactive command cannot prompt. As in Settings, copy the secret into your secret manager when it is created. It cannot be retrieved later.

Settings defaults new keys to a 90-day expiration. The CLI leaves a key non-expiring when --expires-at is omitted, so prefer an explicit future ISO-8601 timestamp unless your credential-rotation policy intentionally requires no expiration.

When --scope is omitted, the key gets all three scopes: scans:create, scans:read, and findings:read. List metadata or revoke a key without exposing its secret:

$ apex service-key list
$ apex service-key revoke <key-id>

Point any Streamable HTTP MCP client at https://ai.cantina.xyz/mcp and send the organization service key as Authorization: Bearer <TOKEN>. No local apex-mcp process, device login, browser, or TTY is required.

Codex

$ export APEX_SERVICE_KEY='<service-key>'
$ codex mcp add apex --url https://ai.cantina.xyz/mcp --bearer-token-env-var APEX_SERVICE_KEY
$ codex mcp get apex

Claude Code

Add a user- or project-scoped .mcp.json entry. Claude Code expands ${APEX_SERVICE_KEY} from the process environment when it connects.

{
  "mcpServers": {
    "apex": {
      "type": "http",
      "url": "https://ai.cantina.xyz/mcp",
      "headers": {
        "Authorization": "Bearer ${APEX_SERVICE_KEY}"
      }
    }
  }
}

Other clients use the same URL and Bearer header. A successful connection advertises apex-credits, apex-workspaces, apex-scan, apex-status, apex-cancel-scan, apex-findings, and apex-workspace-findings. Tool calls enforce the same scopes, organization isolation, rate limits, usage attribution, and idempotency rules as the REST API. When a REST operation supplies a Retry-After header, the MCP tool error preserves it as retryAfter and a normalized retryAfterSeconds value in structured content.

Send a unique, stable Idempotency-Key for each intended scan. Reuse that same value when retrying the same request.

Apex reuses the active workspace already linked to the repository. If none exists, the same request creates a workspace named after the canonical GitHub repository and links it before starting the scan—no website scan is required. If more than one workspace matches, include its workspaceId in the body. The conflict response includes each matching workspace ID, prefix, and name so the caller can present a choice instead of failing with an undiscoverable ID.

curl --request POST https://ai.cantina.xyz/api/apex/v1/scans \
  --header "Authorization: Bearer $APEX_SERVICE_KEY" \
  --header "Idempotency-Key: 8c8d9e5d-4fa6-4b65-bd42-14ddb5874c83" \
  --header "Content-Type: application/json" \
  --data '{
    "repoUrl": "https://github.com/acme/payments",
    "commit": "0123456789abcdef0123456789abcdef01234567",
    "paths": ["src", "packages/auth"],
    "scanType": "standard",
    "generateThreatModel": true
  }'

Scan a local or non-Git directory

Raw filesystem paths cannot cross an HTTP boundary. Create a tar.gz archive, calculate its SHA-256 plus compressed and uncompressed byte counts, then use the upload → complete → scan flow below. A directory does not need to be a Git repository; omit the optional git object for non-Git source.

# 1. Package the source without embedding the output archive:
tar --exclude="./apex-source.tar.gz" -czf apex-source.tar.gz .
# Calculate SHA256, COMPRESSED_BYTES, and UNCOMPRESSED_BYTES in your uploader.

# 2. Create the workspace and signed upload session:
curl --request POST https://ai.cantina.xyz/api/apex/v1/source-uploads \
  --header "Authorization: Bearer $APEX_SERVICE_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "workspaceName": "Payments local",
    "uploads": [{
      "displayName": "payments",
      "relativePath": ".",
      "archiveFormat": "tar.gz",
      "sha256": "<sha256>",
      "compressedBytes": <compressed-bytes>,
      "uncompressedBytes": <uncompressed-bytes>
    }]
  }'

# 3. PUT the archive to uploads[0].upload.putUrl using its returned headers:
curl --request PUT --header "Content-Type: application/gzip" \
  --upload-file apex-source.tar.gz "<put-url>"

# 4. Verify the upload; this returns archiveId and sha256:
curl --request POST \
  --header "Authorization: Bearer $APEX_SERVICE_KEY" \
  --header "Content-Type: application/json" \
  --data '{"workspaceId":"<workspace-id>"}' \
  https://ai.cantina.xyz/api/apex/v1/source-uploads/<upload-id>/complete

# 5. Start the first scan with a fresh threat model:
curl --request POST https://ai.cantina.xyz/api/apex/v1/scans \
  --header "Authorization: Bearer $APEX_SERVICE_KEY" \
  --header "Idempotency-Key: local-payments-2026-07-22" \
  --header "Content-Type: application/json" \
  --data '{
    "workspaceId": "<workspace-id>",
    "scanType": "standard",
    "generateThreatModel": true,
    "scanSources": [{
      "sourceKind": "local_archive",
      "displayName": "payments",
      "relativePath": ".",
      "archiveId": "<archive-id>",
      "sha256": "<sha256>"
    }]
  }'

A successful request returns HTTP 202:

{
  "scanId": "3e559b86-f524-4b27-a175-fb4944c53f1b",
  "workspaceId": "2abf03ae-768b-4717-9d14-43e1a8d8d9a1",
  "status": "preparing",
  "statusUrl": "/api/apex/v1/scans/3e559b86-f524-4b27-a175-fb4944c53f1b",
  "findingsUrl": "/api/apex/v1/scans/3e559b86-f524-4b27-a175-fb4944c53f1b/findings"
}

$ curl --header "Authorization: Bearer $APEX_SERVICE_KEY" \
  https://ai.cantina.xyz/api/apex/v1/scans/<scan-id>

1. 1
   Start

   Treat the HTTP 202 response as accepted and retain its scanId and statusUrl.
2. 2
   Poll

   Use bounded exponential backoff while status is preparing, queued, or running.
3. 3
   Stop

   Stop polling on completed, failed, or cancelled.
4. 4
   Collect

   Fetch findings after the scan reaches completed.

$ curl --request POST \
  --header "Authorization: Bearer $APEX_SERVICE_KEY" \
  https://ai.cantina.xyz/api/apex/v1/scans/<scan-id>/cancel

Cancellation requires scans:create and stops the remaining Apex work for a queued or running scan. A successful response returns HTTP 200 with status: cancelled. Repeating the request after cancellation is safe and returns the same terminal status.

$ curl --header "Authorization: Bearer $APEX_SERVICE_KEY" \
  https://ai.cantina.xyz/api/apex/v1/scans/<scan-id>/findings

The response is a GitLab SAST report. Each vulnerability includes the persisted Apex finding ID, title, description, severity, and available file and line location. IDs remain stable when you fetch the same scan again, so downstream systems can deduplicate safely.

Findings retrieval also works for scans started in the Apex web app, so an integration can begin with this endpoint before automating scan creation.

Discover workspace IDs

A key with scans:create can list active workspaces before creating a scan. Provide a repository URL or GitHub owner/name to find every linked workspace without exposing unrelated workspace metadata. If more than one is returned, let the user choose one and send its workspaceId in a new scan request with a new Idempotency-Key.

curl --header "Authorization: Bearer $APEX_SERVICE_KEY" \
  'https://ai.cantina.xyz/api/apex/v1/workspaces?repository=Uniswap%2Fliquidity-launcher'

Fetch a whole workspace by prefix

To fetch the same finding set as the workspace findings browser, use its human-readable prefix such as BEDR9. The export uses non-archived scans and excludes PR scans, fix-review scans, and unfinished advanced-scan setup drafts. The service key still limits the lookup to its own organization, so a prefix from a different organization returns 404. Use the workspace UUID instead if a company has an ambiguous prefix.

curl --header "Authorization: Bearer $APEX_SERVICE_KEY" \
  'https://ai.cantina.xyz/api/apex/v1/workspaces/BEDR9/findings?state=open'

The response includes the resolved workspace, its active scans, and full finding records rather than only finding IDs. Set state=opento exclude invalid findings, duplicates, and findings marked fixed, false positive, won't fix, or skipped. The response includes each finding's reviewState, isDuplicate, and duplicateOfId. Repeat filter to combine facets. Supported forms include severity:high, status:valid, review:accepted, duplicate:unique, repo:example-app, source:lib/auth.ts, impact:high, likelihood:medium, visibility:draft, scan:<scan-id>, and !validation:invalid. Finding statuses are proposed, partially_valid, valid, invalid, or duplicate; open is a finding state, not a status value. Review state and validity include the current shared client feedback used by the workspace UI. Validation filters use the same client/viewer feedback precedence as the workspace UI, and each finding exposes the resulting validity as valid, invalid, or unknown. Invalid or unknown filter strings are ignored; the response's filters array shows the filters that were applied.

The first request after a scan completes durably synchronizes the terminal finding set. If that sync is unavailable or has more pages, Apex returns 503 with Retry-After. Retry the same GET; after readiness is persisted, later requests serve the cached report without depending on a live scan process.

These prompts work in Claude Code or Codex. The first two keep key creation in a user-controlled Settings or terminal flow; the others use either the hosted MCP endpoint or the REST API for a headless runtime instead of launching a local stdio process there.