REST API Reference

This page documents all public Odin Scan API endpoints. All authenticated endpoints require a valid JWT token or API key in the Authorization header. See Authentication for details.

Base URL:

https://api.odinscan.ai/

Analysis

Endpoints for creating, monitoring, and managing security analyses.

Create Analysis

POST /api/v1/analysis

Submits a repository for security analysis.

Auth required: Yes

Example request:

curl -X POST https://api.odinscan.ai/api/v1/analysis \
  -H "Authorization: Bearer odin_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryUrl": "https://github.com/username/repo",
    "branch": "main",
    "framework": "cosmwasm",
    "analysisType": "full",
    "webhookUrl": "https://optional-webhook-endpoint.com"
  }'

Example response (201 Created):

{
  "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "createdAt": "2025-01-15T10:30:00Z"
}

List Analyses

GET /api/v1/analysis

Returns a list of analyses belonging to the authenticated user.

Auth required: Yes

Example request:

curl https://api.odinscan.ai/api/v1/analysis \
  -H "Authorization: Bearer odin_sk_abc123..."

Example response (200 OK):

[
  {
    "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "repositoryUrl": "https://github.com/username/repo",
    "branch": "main",
    "framework": "cosmwasm",
    "status": "completed",
    "createdAt": "2025-01-15T10:30:00Z",
    "completedAt": "2025-01-15T10:31:15Z"
  }
]

Get Analysis Status

GET /api/v1/analysis/:id/status

Returns the current status and progress of a specific analysis.

Auth required: Yes

Example request:

curl https://api.odinscan.ai/api/v1/analysis/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status \
  -H "Authorization: Bearer odin_sk_abc123..."

Example response (200 OK):

{
  "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "progress": 65,
  "currentStage": "ai_analysis"
}

Possible statuses: pending, running, completed, failed

Get Analysis Result

GET /api/v1/analysis/:id/result

Returns the full results of a completed analysis, including all findings and the markdown report.

Auth required: Yes

Example request:

curl https://api.odinscan.ai/api/v1/analysis/a1b2c3d4-e5f6-7890-abcd-ef1234567890/result \
  -H "Authorization: Bearer odin_sk_abc123..."

Example response (200 OK):

{
  "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "repository": {
    "url": "https://github.com/username/repo",
    "branch": "main",
    "framework": "cosmwasm"
  },
  "summary": {
    "totalFindings": 12,
    "criticalFindings": 2,
    "highFindings": 3,
    "mediumFindings": 4,
    "lowFindings": 3,
    "analysisTime": 45000
  },
  "findings": [
    {
      "id": "finding-uuid",
      "title": "Unchecked Address Validation",
      "description": "The contract accepts addresses without validation...",
      "severity": "high",
      "confidence": "high",
      "category": "Input Validation",
      "location": {
        "file": "src/contract.rs",
        "lineStart": 142,
        "lineEnd": 147
      },
      "remediation": "Implement proper address validation..."
    }
  ],
  "markdownReport": "# Security Analysis Report\n..."
}

Note: The markdownReport field contains the full human-readable report. Use this for exports or display purposes.

Delete Analysis

DELETE /api/v1/analysis/:id

Permanently deletes an analysis and all associated results.

Auth required: Yes

Example response (204 No Content): (empty body)

Retry Analysis

POST /api/v1/analysis/:id/retry

Retries a failed analysis. The original configuration (repository, branch, framework) is reused.

Auth required: Yes

Example response (200 OK):

{
  "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "retriedAt": "2025-01-15T11:00:00Z"
}

Get Badge Data

GET /api/v1/analysis/:id/badge

Returns minimal analysis data for rendering a README badge. This is a public endpoint that requires no authentication, so badges can be embedded in GitHub READMEs and rendered by browsers.

Only exposes aggregate finding counts, not individual findings or report contents.

Auth required: No

Example request:

curl https://api.odinscan.ai/api/v1/analysis/a1b2c3d4-e5f6-7890-abcd-ef1234567890/badge

Example response (200 OK):

{
  "status": "completed",
  "totalFindings": 12,
  "criticalFindings": 2,
  "highFindings": 3,
  "mediumFindings": 4,
  "lowFindings": 3,
  "informationalFindings": 0
}

Error responses:

See Badges & Banners for usage examples and embeddable SVG URLs.

Repositories

Endpoints for managing GitHub repository connections.

List Repositories

GET /api/v1/repositories

Returns the authenticated user’s synced GitHub repositories.

Auth required: Yes

Example request:

curl https://api.odinscan.ai/api/v1/repositories \
  -H "Authorization: Bearer odin_sk_abc123..."

Example response (200 OK):

[
  {
    "id": "repo-uuid",
    "githubId": 123456789,
    "name": "my-smart-contracts",
    "fullName": "username/my-smart-contracts",
    "url": "https://github.com/username/my-smart-contracts",
    "defaultBranch": "main",
    "language": "Rust",
    "lastSyncedAt": "2025-01-15T08:00:00Z"
  }
]

Sync Repositories

POST /api/v1/repositories/sync

Performs a full synchronization of the user’s GitHub repositories. This fetches all accessible repositories from GitHub and updates the local database.

Auth required: Yes

Example request:

curl -X POST https://api.odinscan.ai/api/v1/repositories/sync \
  -H "Authorization: Bearer odin_sk_abc123..."

Example response (200 OK):

{
  "synced": 42,
  "added": 3,
  "updated": 39,
  "syncedAt": "2025-01-15T10:00:00Z"
}

Quick Sync Repositories

POST /api/v1/repositories/quick-sync

Performs an incremental sync, fetching only repositories updated since the last sync. Faster than a full sync.

Auth required: Yes

Get Repository

GET /api/v1/repositories/:id

Returns details for a specific repository.

Auth required: Yes

Get Repository Statistics

GET /api/v1/repositories/stats

Returns aggregate statistics across all synced repositories.

Auth required: Yes

Subscriptions

Endpoints for managing billing and subscription plans.

List Plans

GET /api/subscriptions/plans

Returns all available subscription plans and their features.

Auth required: Yes

Example response (200 OK):

[
  {
    "id": "plan-basic",
    "name": "Basic",
    "monthlyAnalyses": 10,
    "features": ["AI scanning", "Markdown reports"]
  },
  {
    "id": "plan-pro",
    "name": "Pro",
    "monthlyAnalyses": 60,
    "features": ["Full scanning", "AI chat", "SARIF export", "Priority support"]
  }
]

Create Checkout Session

POST /api/subscriptions/checkout

Creates a checkout session for subscribing to a plan. Returns a URL to redirect the user to the payment page.

Auth required: Yes

Example response (200 OK):

{
  "checkoutUrl": "https://polar.sh/checkout/..."
}

Get Subscription Status

GET /api/subscriptions/status

Returns the authenticated user’s current subscription status and tier.

Auth required: Yes

Example response (200 OK):

{
  "tier": "pro",
  "status": "active",
  "currentPeriodEnd": "2025-02-15T00:00:00Z",
  "monthlyAnalysesUsed": 12,
  "monthlyAnalysesLimit": 60
}

Create Customer Portal Session

POST /api/subscriptions/portal

Creates a session URL for the billing management portal where users can update payment methods, view invoices, or cancel their subscription.

Auth required: Yes

Example response (200 OK):

{
  "portalUrl": "https://polar.sh/portal/..."
}

Health

Public endpoints for monitoring API availability. These do not require authentication.

Basic Health Check

GET /health

Returns a simple status indicating the API is running.

Auth required: No

Example response (200 OK):

{
  "status": "ok"
}

Detailed Health Check

GET /health/detailed

Returns health status for the API and all dependencies (database, Redis, external services).

Auth required: No

Example response (200 OK):

{
  "status": "ok",
  "database": "connected",
  "redis": "connected",
  "uptime": 86400
}

Error Responses

All endpoints return errors in a consistent format:

{
  "error": {
    "code": "ANALYSIS_FAILED",
    "message": "Analysis failed due to compilation errors",
    "details": {
      "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "stage": "compilation"
    }
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "requestId": "req-abc123"
}

Common status codes:

Next Steps

• Authentication – set up API access
• Rate Limits – understand request limits
• Exports – export analysis results in various formats