Apex service API

Read: 8 min
Updated: July 10, 2026
Audience: Platform engineers

§ 01 Choose the right integration

Use Apex CLI or MCP when a person or coding agent is working in a repository. Use the service API when a headless process needs HTTP, JSON, and a static organization credential.


CLI + MCP	Interactive developer and coding-agent workflows with device login
Service API	Serverless workers, cron jobs, CI, and internal audit hubs
Authentication	Authorization: Bearer apex_sk_live_… or X-API-Key
Findings format	GitLab SAST JSON with stable finding IDs and source locations

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

§ 02 Prerequisites

Connect the GitHub repository and link it to an active workspace in the same Apex organization that owns the service key.
Use a full 40- or 64-character Git commit SHA. Branch names and moving refs are not accepted.
Create or revoke keys as an Apex organization manager or Bedrock administrator.
Store the key in a secret manager. Apex displays the raw secret only once and stores only its hash.

Version-one repository support The first service API release accepts GitHub repositories already connected to your Apex organization. GitLab service-account access will follow once connection ownership can be made explicit.

§ 03 Create a service key

apex update
apex login
# Read-only key for polling status and importing findings:
apex service-key create --name "Audit hub" --scope scans:read,findings:read
# Omit --scope only when this key must also trigger scans:
apex service-key create --name "Audit hub"
# Optional machine-readable output:
apex service-key create --name "Audit hub" --scope scans:read,findings:read --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. Copy the secret into your secret manager when it is created. It cannot be retrieved later. 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>

§ 04 Trigger a scan

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 more than one workspace matches, include its workspaceId in the body. The service API never creates or rewrites workspaces.

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"]
  }'

Paths are focus hints The optional paths array prioritizes those files in Apex prompts, but it is not a hard repository boundary. The scan may inspect or report code outside those paths. Omit it if you do not need focus hints; version one does not yet provide strict path isolation.

A successful request returns HTTP 202:

{
  "scanId": "3e559b86-f524-4b27-a175-fb4944c53f1b",
  "status": "queued",
  "statusUrl": "/api/apex/v1/scans/3e559b86-f524-4b27-a175-fb4944c53f1b",
  "findingsUrl": "/api/apex/v1/scans/3e559b86-f524-4b27-a175-fb4944c53f1b/findings"
}

§ 05 Poll scan status

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

Start - Treat the HTTP 202 response as queued and retain its scanId.
Poll - Use bounded exponential backoff while status is queued or running.
Stop - Stop polling on completed, failed, or cancelled.
Collect - Fetch findings after the scan reaches completed.

§ 06 Fetch findings

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.

Findings access includes drafts A key with findings:read can retrieve unpublished draft findings for scans in its organization so an external hub can perform triage. Treat the service key as a privileged credential and do not expose its findings payload to users who cannot review drafts in Apex.

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 Kernel.

§ 07 Errors and retries

Code	Meaning
400	Invalid repository URL, commit SHA, path hint, or request body
401	Missing, malformed, expired, or revoked service key
403	The key lacks the required scope
404	The scan does not exist in the key’s organization
409	Idempotency conflict, repository workspace mismatch, active scan, or a non-completed scan
429	Rate limit reached; respect Retry-After
500	Internal persistence or lookup failure; retry with backoff
502	Transient provider or Kernel failure; retry with the identical request when appropriate
503	Scan finalization or first terminal findings sync is incomplete; respect Retry-After
504	Kernel scan start timed out; retry the identical body with the same Idempotency-Key

Retry safely GET requests are safe to retry. After a transport error, timeout, or 5xx, retry POST only with the original body and the original Idempotency-Key. Idempotency is organization-scoped, so replay remains safe if the service key is rotated between attempts. A definitive 4xx response is retained: after correcting its precondition, submit it as a new intended scan with a new Idempotency-Key. Never log the Authorization or X-API-Key header.

§ 08 Claude and Codex prompts

These prompts work in Claude Code or Codex. The first keeps key creation in your own terminal; the others ask the agent to use the service API for the headless runtime rather than trying to run MCP inside a serverless function.

Give me the exact Apex CLI command I should run in my own terminal to create a service key named Audit hub. Do not run it for me or ask me to paste the secret into this chat.
Using APEX_SERVICE_KEY from the environment, write a serverless TypeScript adapter that starts an Apex scan for this repository and commit. Send a stable Idempotency-Key, poll until terminal, and return the GitLab SAST findings.
Add Apex to our audit hub. Call POST /api/apex/v1/scans, poll GET /api/apex/v1/scans/{scanId} with bounded backoff, then fetch /findings. Never log the bearer token and retry only safe requests.
Given an Apex scanId for a scan started in the web app, fetch its GitLab SAST findings with APEX_SERVICE_KEY, preserve the raw response, and import each vulnerability once by stable ID. Do not trigger another scan or log the credential.
Diagnose this Apex API response without printing secrets. Explain whether it is a transport/5xx retry that must preserve the original Idempotency-Key, or a definitive 4xx that must be corrected and submitted as a new intended scan with a new key.

Introduction

Platform Overview

Products

For Security Teams

For Security Researchers

Evaluations & Standards

Referral Program

Resources

API Reference

§ 01 Choose the right integration

§ 02 Prerequisites

§ 03 Create a service key

§ 04 Trigger a scan

§ 05 Poll scan status

§ 06 Fetch findings

§ 07 Errors and retries

§ 08 Claude and Codex prompts

​§ 01 Choose the right integration

​§ 02 Prerequisites

​§ 03 Create a service key

​§ 04 Trigger a scan

​§ 05 Poll scan status

​§ 06 Fetch findings

​§ 07 Errors and retries

​§ 08 Claude and Codex prompts

§ 01 Choose the right integration

§ 02 Prerequisites

§ 03 Create a service key

§ 04 Trigger a scan

§ 05 Poll scan status

§ 06 Fetch findings

§ 07 Errors and retries

§ 08 Claude and Codex prompts