Platform API

Overview

The Axiomatic platform exposes an API for syncing test results, querying run history, and managing repositories. The API is used internally by axm run (auto-sync) and the GitHub Action.

Authentication

All API requests require a Bearer token. Authenticate via axm login to obtain a token, which is stored at ~/.axiomatic/credentials.

curl -H "Authorization: Bearer $TOKEN" \
  https://axiomatic.sh/api/v1/runs

Endpoints

List Runs

GET /api/v1/runs

Returns the most recent 50 test runs for repositories in the authenticated user's organizations.

Response:

{
  "success": true,
  "data": [
    {
      "id": "clx123...",
      "repo": "owner/repo",
      "branch": "main",
      "commitSha": "abc123",
      "timestamp": "2026-03-15T10:30:00.000Z",
      "resultsCount": 5,
      "createdAt": "2026-03-15T10:30:01.000Z"
    }
  ]
}

Get Run

GET /api/v1/runs/:id

Returns details for a specific run, including per-test results, violations, and agent reasoning.

Response:

{
  "success": true,
  "data": {
    "id": "clx123...",
    "repo": "owner/repo",
    "branch": "main",
    "commitSha": "abc123",
    "timestamp": "2026-03-15T10:30:00.000Z",
    "createdAt": "2026-03-15T10:30:01.000Z",
    "results": [
      {
        "id": "clx456...",
        "testPath": "axiomatic/auth-required.yml",
        "condition": "All API routes must require authentication",
        "status": "pass",
        "severity": "error",
        "confidence": 0.95,
        "violations": [],
        "notes": "Checked 12 API route files...",
        "cached": false,
        "cost": 0.0042
      }
    ]
  }
}

Sync Results

POST /api/v1/runs

Upload test results from a local or CI run. This is called automatically by axm run when authenticated. The repository is associated with the org that matches the repo owner. The first upload creates the repository record on the platform. Navigation plans (shared agent memory) are included in the payload when available.

List Repositories

GET /api/v1/repos

Returns all repositories with test results on the platform, including the latest run for each. Results are scoped to organizations the user belongs to. Pass ?org=slug to filter by a specific organization.

Response:

{
  "success": true,
  "data": [
    {
      "id": "clx789...",
      "owner": "owner",
      "name": "repo",
      "fullName": "owner/repo",
      "isPrivate": false,
      "runsCount": 12,
      "latestRun": {
        "id": "clx123...",
        "branch": "main",
        "commitSha": "abc123",
        "timestamp": "2026-03-15T10:30:00.000Z",
        "createdAt": "2026-03-15T10:30:01.000Z"
      },
      "createdAt": "2026-02-01T00:00:00.000Z"
    }
  ]
}

List Library Packs

GET /api/library

Returns a list of all available test packs in the Axiomatic library. No authentication required.

Response:

{
  "success": true,
  "data": [
    {
      "name": "owasp-security",
      "title": "OWASP Security",
      "description": "Security tests based on the OWASP Top 10",
      "tags": ["security"],
      "testCount": 5
    }
  ]
}

Get Library Pack

GET /api/library/:packName

Returns a specific pack including all test definitions. No authentication required. Used by axm install to fetch pack contents.

Response (200):

{
  "success": true,
  "data": {
    "name": "owasp-security",
    "title": "OWASP Security",
    "description": "Security tests based on the OWASP Top 10",
    "tags": ["security"],
    "tests": [
      {
        "name": "no-sql-injection",
        "condition": "No raw SQL queries with string concatenation...",
        "on": ["**/*.ts"],
        "severity": "error",
        "tags": ["security"]
      }
    ]
  }
}

Response (404):

{
  "success": false,
  "error": { "code": "NOT_FOUND", "message": "Pack \"foo\" not found" }
}

Check LLM Credits

GET /api/lm/credits

Returns the LLM credit balance, usage, and reset date for the organization associated with the API token (or the user's personal org for unscoped tokens). Requires API token authentication (Authorization: Bearer <token>).

Response:

{
  "success": true,
  "data": {
    "remaining": 4.82,
    "used": 0.18,
    "total": 5.0,
    "hasCredits": true,
    "periodStart": "2026-03-01T00:00:00.000Z",
    "resetDate": "2026-03-31T00:00:00.000Z",
    "plan": "free"
  }
}

Get Usage History

GET /api/lm/usage

Returns the most recent 50 LLM usage log entries for the current organization. Requires session authentication (web dashboard).

Response:

{
  "success": true,
  "data": [
    {
      "id": "abc123",
      "model": "claude-sonnet-4-6",
      "inputTokens": 1200,
      "outputTokens": 350,
      "costUsd": 0.0089,
      "date": "2026-03-15T10:30:00.000Z"
    }
  ]
}

LLM Proxy

POST /api/lm/v1/messages

Forwards requests to the Anthropic Messages API using platform-managed credentials. This is the endpoint the CLI calls when running tests with cloud credits (no local ANTHROPIC_API_KEY required). Requires API token authentication via Authorization: Bearer <token> or x-api-key header.

The proxy:

Authenticates the user and checks remaining credit balance
Forwards the request to https://api.anthropic.com/v1/messages (with streaming disabled)
Calculates cost server-side from the Anthropic response usage fields
Deducts the cost from the user's credit balance and logs the usage
Returns the Anthropic response as-is

Error (402 - credits exhausted):

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "LLM credit limit reached ($5.00/month). Usage resets on 3/31/2026. Upgrade your plan or set a local ANTHROPIC_API_KEY to continue."
  }
}

Organization Management

These endpoints manage organizations, members, and invites. All require session authentication.

GET    /api/orgs                     # List user's organizations
POST   /api/orgs                     # Import a GitHub org
PATCH  /api/orgs/:orgId              # Rename org (admin)
DELETE /api/orgs/:orgId              # Delete org (admin)
GET    /api/orgs/:orgId/members      # List org members
PUT    /api/orgs/:orgId/members      # Update member role (admin)
DELETE /api/orgs/:orgId/members      # Remove member (admin)
POST   /api/orgs/:orgId/leave        # Leave org
GET    /api/orgs/:orgId/invites      # List pending invites
POST   /api/orgs/:orgId/invites      # Create invite (admin)
DELETE /api/orgs/:orgId/invites      # Cancel invite (admin)
POST   /api/invites/:token/accept    # Accept an invite
GET    /api/github/orgs              # List importable GitHub orgs

These endpoints are used by the web dashboard and are not part of the public v1 API. They follow the same error format documented below.

Error Format

All error responses follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Common error codes: UNAUTHORIZED, BAD_REQUEST, NOT_FOUND, PLAN_LIMIT, INTERNAL_ERROR.

SDK

There is no standalone SDK at this time. Use the CLI (axm run auto-syncs when authenticated) or make HTTP requests directly. If you need programmatic access, axm run --json outputs structured results suitable for piping to other tools.

Platform API

On this page