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

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