Targets

Manage scan targets and ownership verification

POST/v1/targets

Create a target

Register a new domain or IP address as a scan target. The target must be verified before any scans can be initiated against it. After creation, use the verification endpoints to prove ownership.

Request Body

Name	Type	Description
`domain`required	`string`	The fully-qualified domain name or IP address to target (e.g. "example.com" or "203.0.113.42")

Example Request

bash

curl -X POST "https://apviso.com/api/v1/v1/targets" \
  -H "X-API-Key: apvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "domain": "example.com"
}'

Response

Returns the newly created target with its unique ID. The target starts in an unverified state. You must complete ownership verification before running scans.

json

{
  "id": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "domain": "example.com",
  "verified": false,
  "verificationMethod": null,
  "verifiedAt": null,
  "authConfigured": false,
  "createdAt": "2026-04-10T09:15:32Z",
  "updatedAt": "2026-04-10T09:15:32Z"
}

GET/v1/targets

List targets

Retrieve a paginated list of all targets registered to your account. Results are ordered by creation date (newest first).

Query Parameters

Name	Type	Description
`page`	`number` Default: `1`	Page number for pagination
`limit`	`number` Default: `20`	Number of results per page (max 100)

Example Request

bash

curl -X GET "https://apviso.com/api/v1/v1/targets" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns a paginated list of targets with their verification status, last scan timestamp, and authentication configuration state.

json

{
  "data": [
    {
      "id": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
      "domain": "example.com",
      "verified": true,
      "verificationMethod": "dns_txt",
      "verifiedAt": "2026-04-10T09:22:18Z",
      "authConfigured": true,
      "lastScanAt": "2026-04-10T14:30:00Z",
      "createdAt": "2026-04-10T09:15:32Z",
      "updatedAt": "2026-04-10T14:30:00Z"
    },
    {
      "id": "019414b2-a3d1-7e8b-c4f6-1d2e3f4a5b6c",
      "domain": "staging.example.com",
      "verified": true,
      "verificationMethod": "file",
      "verifiedAt": "2026-04-09T11:05:44Z",
      "authConfigured": false,
      "lastScanAt": null,
      "createdAt": "2026-04-09T10:48:21Z",
      "updatedAt": "2026-04-09T11:05:44Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

GET/v1/targets/:id

Get target details

Retrieve detailed information about a specific target, including its verification status, authentication configuration, and scan history summary.

Path Parameters

Name	Type	Description
`id`required	`string`	Target ID (UUIDv7)

Example Request

bash

curl -X GET "https://apviso.com/api/v1/v1/targets/:id" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns the full target object including scan count, open findings count, and auth type (credentials are never returned).

json

{
  "id": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "domain": "example.com",
  "verified": true,
  "verificationMethod": "dns_txt",
  "verifiedAt": "2026-04-10T09:22:18Z",
  "authConfigured": true,
  "authType": "bearer",
  "lastScanAt": "2026-04-10T14:30:00Z",
  "scanCount": 5,
  "openFindingsCount": 12,
  "createdAt": "2026-04-10T09:15:32Z",
  "updatedAt": "2026-04-10T14:30:00Z"
}

DELETE/v1/targets/:id

Delete a target

Permanently delete a target and its associated verification data. This operation will fail with a 409 Conflict if any scans exist for this target. Delete all associated scans first, or use this only for targets that were never scanned.

This endpoint returns 409 Conflict if the target has any associated scans. You must delete all scans for the target before deleting it.

Path Parameters

Name	Type	Description
`id`required	`string`	Target ID (UUIDv7)

Example Request

bash

curl -X DELETE "https://apviso.com/api/v1/v1/targets/:id" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns a confirmation message on success. Returns 409 Conflict if scans exist for this target.

json

{
  "message": "Target deleted successfully"
}

POST/v1/targets/:id/verify

Verify target ownership

Initiate or complete an ownership verification check for the target. APVISO supports three verification methods: DNS TXT record, file upload at a well-known path, or an HTML meta tag. You must first retrieve the verification token via the instructions endpoint, implement the chosen method on your target, then call this endpoint to trigger the check.

Path Parameters

Name	Type	Description
`id`required	`string`	Target ID (UUIDv7)

Request Body

Name	Type	Description
`method`required	`string` dns_txtfilemeta_tag	Verification method to use

Example Request

bash

curl -X POST "https://apviso.com/api/v1/v1/targets/:id/verify" \
  -H "X-API-Key: apvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "method": "dns_txt"
}'

Response

Returns the target with updated verification status. If verification fails, `verified` will remain `false` and an `error` field will describe the failure reason.

json

{
  "id": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "domain": "example.com",
  "verified": true,
  "verificationMethod": "dns_txt",
  "verifiedAt": "2026-04-10T09:22:18Z"
}

GET/v1/targets/:id/verify/instructions

Get verification instructions

Retrieve the unique verification token and step-by-step instructions for each supported verification method. The token is stable per target and can be reused across verification attempts.

Path Parameters

Name	Type	Description
`id`required	`string`	Target ID (UUIDv7)

Example Request

bash

curl -X GET "https://apviso.com/api/v1/v1/targets/:id/verify/instructions" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns the verification token and detailed instructions for all three supported verification methods. Implement any one method, then call the verify endpoint.

json

{
  "token": "apviso-verify-a8f7c07d4ab5e39c2d",
  "methods": {
    "dns_txt": {
      "description": "Add a TXT record to your domain's DNS configuration",
      "record": {
        "type": "TXT",
        "name": "_apviso-verify.example.com",
        "value": "apviso-verify-a8f7c07d4ab5e39c2d"
      }
    },
    "file": {
      "description": "Place a verification file at the well-known path on your web server",
      "path": "/.well-known/penterep-verify.txt",
      "content": "apviso-verify-a8f7c07d4ab5e39c2d",
      "url": "https://example.com/.well-known/penterep-verify.txt"
    },
    "meta_tag": {
      "description": "Add a meta tag to the <head> section of your homepage",
      "tag": "<meta name=\"apviso-verify\" content=\"apviso-verify-a8f7c07d4ab5e39c2d\">"
    }
  }
}

GET/v1/targets/:id/verify/status

Check verification status

Check the current verification status of a target without triggering a new verification attempt. Useful for polling after initiating verification.

Path Parameters

Name	Type	Description
`id`required	`string`	Target ID (UUIDv7)

Example Request

bash

curl -X GET "https://apviso.com/api/v1/v1/targets/:id/verify/status" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns the current verification status including the method used and timestamps for verification and last check.

json

{
  "verified": true,
  "verificationMethod": "dns_txt",
  "verifiedAt": "2026-04-10T09:22:18Z",
  "lastCheckAt": "2026-04-10T09:22:18Z"
}

PUT/v1/targets/:id/auth

Set authentication config

Configure authentication credentials that the scan agents will use when accessing your target. This enables scanning of authenticated areas of your application. Credentials are encrypted at rest and never returned in API responses. Supports bearer tokens, basic auth, cookies, API keys, custom headers, and login-based authentication.

Credentials are encrypted at rest using AES-256-GCM. They are only decrypted inside the isolated scan container at runtime.

Path Parameters

Name	Type	Description
`id`required	`string`	Target ID (UUIDv7)

Request Body

Name	Type	Description
`type`required	`string` bearerbasiccookieapi_keycustom_headerslogin	Authentication type
`credentials`required	`object`	Authentication credentials. Structure varies by type: bearer requires `token`, basic requires `username` and `password`, cookie requires `cookies` (key-value map), api_key requires `header` and `value`, custom_headers requires `headers` (key-value map), login requires `loginUrl`, `usernameField`, `passwordField`, `username`, `password`, and optionally `submitSelector`.

Example Request

bash

curl -X PUT "https://apviso.com/api/v1/v1/targets/:id/auth" \
  -H "X-API-Key: apvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "bearer",
  "credentials": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}'

Response

Returns the target with the updated auth configuration status. Credentials are never included in the response for security.

json

{
  "id": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "domain": "example.com",
  "authConfigured": true,
  "authType": "bearer",
  "updatedAt": "2026-04-10T10:05:41Z"
}

DELETE/v1/targets/:id/auth

Clear authentication config

Remove the stored authentication configuration for a target. Future scans will run without authentication credentials, testing only publicly accessible areas.

Path Parameters

Name	Type	Description
`id`required	`string`	Target ID (UUIDv7)

Example Request

bash

curl -X DELETE "https://apviso.com/api/v1/v1/targets/:id/auth" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns the target with auth configuration cleared.

json

{
  "id": "019414a8-f7c0-7d4a-b5e3-9c2d1e8f4a6b",
  "domain": "example.com",
  "authConfigured": false,
  "authType": null,
  "updatedAt": "2026-04-10T10:12:09Z"
}

Back to API Reference