Create scan

POST/accounts/{account_id}/managed-defense/vulnerability-discovery/scans

Submits repository intent for operator review. This endpoint does not immediately start execution. Worker-imported repositories must be ready; explicit repository host scopes must be authorized and explicit branch selections must exist before the request is persisted.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Path ParametersExpand Collapse

account_id: string

Header ParametersExpand Collapse

"Idempotency-Key": optional string

maxLength128

minLength1

Body ParametersJSONExpand Collapse

repos: array of object { name, branch, hosts }

Repository names must be unique within a request.

name: string

maxLength255

minLength1

branch: optional string

Branch to scan. Defaults to the repository’s default branch.

maxLength255

minLength1

hosts: optional array of string

Explicit hostname scopes. Every hostname must be authorized for this repository before review admission; rejected scopes return 422 and do not persist a scan request.

telemetry_window: optional object { end, start }

UTC ISO-8601 interval. Start is inclusive, end is exclusive, and the interval must be positive and at most seven days.

end: string

formatdate-time

start: string

formatdate-time

ReturnsExpand Collapse

errors: array of ResponseInfo { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

messages: array of ResponseInfo { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

result: object { id, completed_at, message, 6 more }

id: string

formatuuid

completed_at: string

formatdate-time

message: string

maxLength1024

phase: "provisioning" or "indexing" or "analyzing" or 2 more

One of the following:

"provisioning"

"indexing"

"analyzing"

"reporting"

"finalizing"

repositories: array of object { id, name, phase, 2 more }

id: string

formatuuid

name: string

phase: "provisioning" or "indexing" or "analyzing" or 2 more

One of the following:

"provisioning"

"indexing"

"analyzing"

"reporting"

"finalizing"

report_status: "not_ready" or "pending_review" or "published" or "withdrawn"

One of the following:

"not_ready"

"pending_review"

"published"

"withdrawn"

status: "requested" or "accepted" or "running" or 4 more

One of the following:

"requested"

"accepted"

"running"

"completed"

"failed"

"rejected"

"cancelled"

started_at: string

formatdate-time

status: "requested" or "accepted" or "running" or 4 more

One of the following:

"requested"

"accepted"

"running"

"completed"

"failed"

"rejected"

"cancelled"

submitted_at: string

formatdate-time

telemetry_window: optional object { end, start }

UTC ISO-8601 interval. Start is inclusive, end is exclusive, and the interval must be positive and at most seven days.

end: string

formatdate-time

start: string

formatdate-time

success: true

Create scan

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/managed-defense/vulnerability-discovery/scans \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "repos": [
            {
              "name": "x"
            }
          ]
        }'

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "completed_at": "2019-12-27T18:11:19.117Z",
    "message": "message",
    "phase": "provisioning",
    "repositories": [
      {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "name": "name",
        "phase": "provisioning",
        "report_status": "not_ready",
        "status": "requested"
      }
    ],
    "started_at": "2019-12-27T18:11:19.117Z",
    "status": "requested",
    "submitted_at": "2019-12-27T18:11:19.117Z",
    "telemetry_window": {
      "end": "2019-12-27T18:11:19.117Z",
      "start": "2019-12-27T18:11:19.117Z"
    }
  },
  "success": true
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "completed_at": "2019-12-27T18:11:19.117Z",
    "message": "message",
    "phase": "provisioning",
    "repositories": [
      {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "name": "name",
        "phase": "provisioning",
        "report_status": "not_ready",
        "status": "requested"
      }
    ],
    "started_at": "2019-12-27T18:11:19.117Z",
    "status": "requested",
    "submitted_at": "2019-12-27T18:11:19.117Z",
    "telemetry_window": {
      "end": "2019-12-27T18:11:19.117Z",
      "start": "2019-12-27T18:11:19.117Z"
    }
  },
  "success": true
}