Scans API

Base URL

https://api.ariftly.io/v1

Create a scan

POST /projects/{project_id}/scans

Trigger a new scan against the project's target.

Request

curl -X POST https://api.ariftly.io/v1/projects/proj_abc123/scans \
  -H "Authorization: Bearer $ARIFTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "detectors": ["accessibility", "security"],
    "environment": "production",
    "detector_options": {
      "accessibility": {
        "wcag_level": "AA"
      }
    },
    "metadata": {
      "git_sha": "abc1234",
      "branch": "main",
      "triggered_by": "github-actions"
    }
  }'

Request body

Field	Type	Required	Description
detectors	string[]	No	Detectors to run. Defaults to project's default_detectors
environment	string	No	Target environment override
target_override	string	No	Override the project's target URL/path for this scan
detector_options	object	No	Per-detector configuration
metadata	object	No	Arbitrary key-value metadata attached to the scan

Response 201 Created

{
  "scan_id": "scan_xyz789",
  "project_id": "proj_abc123",
  "status": "pending",
  "detectors": ["accessibility", "security"],
  "created_at": "2026-03-25T10:00:00Z",
  "estimated_duration_seconds": 90
}

---

Get a scan

GET /scans/{scan_id}

Retrieve the current status and results of a scan.

curl https://api.ariftly.io/v1/scans/scan_xyz789 \
  -H "Authorization: Bearer $ARIFTLY_API_KEY"

Response 200 OK (running)

{
  "scan_id": "scan_xyz789",
  "project_id": "proj_abc123",
  "status": "running",
  "detectors": ["accessibility", "security"],
  "progress": {
    "accessibility": "completed",
    "security": "running"
  },
  "created_at": "2026-03-25T10:00:00Z"
}

Response 200 OK (completed)

{
  "scan_id": "scan_xyz789",
  "project_id": "proj_abc123",
  "status": "completed",
  "risk_score": 65,
  "risk_level": "high",
  "detectors": {
    "accessibility": {
      "status": "completed",
      "risk_score": 30,
      "risk_level": "low",
      "summary": {
        "total": 6,
        "critical": 0,
        "high": 1,
        "medium": 2,
        "low": 3,
        "info": 0
      }
    },
    "security": {
      "status": "completed",
      "risk_score": 82,
      "risk_level": "critical",
      "summary": {
        "total": 4,
        "critical": 1,
        "high": 2,
        "medium": 1,
        "low": 0,
        "info": 0
      }
    }
  },
  "created_at": "2026-03-25T10:00:00Z",
  "completed_at": "2026-03-25T10:01:45Z",
  "duration_seconds": 105
}

---

List scans for a project

GET /projects/{project_id}/scans

curl "https://api.ariftly.io/v1/projects/proj_abc123/scans?limit=10&status=completed" \
  -H "Authorization: Bearer $ARIFTLY_API_KEY"

Query parameters

Parameter	Type	Default	Description
limit	integer	20	Results per page (max 100)
cursor	string	—	Pagination cursor
status	string	—	Filter by status: pending, running, completed, failed

Response 200 OK

{
  "data": [
    {
      "scan_id": "scan_xyz789",
      "status": "completed",
      "risk_score": 65,
      "created_at": "2026-03-25T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

---

Cancel a scan

POST /scans/{scan_id}/cancel

Cancel a running or pending scan.

curl -X POST https://api.ariftly.io/v1/scans/scan_xyz789/cancel \
  -H "Authorization: Bearer $ARIFTLY_API_KEY"

Response 200 OK

{
  "scan_id": "scan_xyz789",
  "status": "cancelled"
}