Introduction

This is the documentation for the SIWECOS Business Layer API.

Users

User Registration

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/user \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "mail@siwecos.de",
    "password": "abcd1234",
    "agb_check": true
}'

POST /api/v2/user HTTP/1.1
Host: bla.local
Content-Type: application/json

{
    "email": "mail@siwecos.de",
    "password": "abcd1234",
    "agb_check": true
}

A user can be registered in the database.

The Response has the following structure:

{
  "token": "Y2jHgqtSVcz8eFqiV4eC0s5Y",
  "email": "mail@siwecos.de",
  "preferred_language": "de",
  "is_active": false,
  "domain_verification_token": "p522893XyZYSu5riyZ7PRCQ1ynOTyrfsYfx0NNUjbB"
}

HTTP Request

POST /api/v2/user

Request Parameters

Parameter	Type	Description
email	`email`	The user's email address
password	`password`	The user's password
agb_check	`boolean`	The user must accept the General Terms and Conditions to use this service

Response Status Codes

Code	Meaning
200	User created
422	Validation failed

User Activation

The Request must have the following structure:

curl -X GET \
  http://bla.local/api/v2/user/activate/{key}

GET /api/v2/user/activate/{key} HTTP/1.1
Host: bla.local

A user has to be activated via verification of his email address to use the service.

The Response has the following structure:

{
  "token": "Y2jHgqtSVcz8eFqiV4eC0s5Y",
  "email": "mail@siwecos.de",
  "preferred_language": "de",
  "is_active": true,
  "domain_verification_token": "p522893XyZYSu5riyZ7PRCQ1ynOTyrfsYfx0NNUjbB"
}

HTTP Request

GET /api/v2/user/activate/{key}

Request Parameters

Parameter	Type	Description
key	`string`	The user's activation key that was sent via email address

Response Status Codes

Code	Meaning
200	OK
404	User not found
410	User already activated

Resend Activation Mail

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/user/activate/resend \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "mail@siwecos.de"
}'

POST /api/v2/user/activate/resend HTTP/1.1
Host: bla.local
Content-Type: application/json

{
    "email": "mail@siwecos.de"
}

The activation mail can be resend if requested.

The Response has the following structure:

{
  "message": "Mail sent."
}

HTTP Request

POST /api/v2/user/activate/resend

Request Parameters

Parameter	Type	Description
email	`email`	The user's email address

Response Status Codes

Code	Meaning
200	Mail sent
410	User already activated
422	Validation failed

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/user/login \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "mail@siwecos.de",
    "password": "abcd1234"
}'

POST /api/v2/user/login HTTP/1.1
Host: bla.local
Content-Type: application/json

{
    "email": "mail@siwecos.de",
    "password": "abcd1234"
}

The user can be logged in to SIWECOS.

The Response has the following structure:

{
  "token": "Y2jHgqtSVcz8eFqiV4eC0s5Y",
  "email": "mail@siwecos.de",
  "preferred_language": "de",
  "is_active": false,
  "domain_verification_token": "p522893XyZYSu5riyZ7PRCQ1ynOTyrfsYfx0NNUjbB"
}

HTTP Request

POST /api/v2/user/login

Request Parameters

Parameter	Type	Description
email	`email`	The user's email address
password	`password`	The user's password

Response Status Codes

Code	Meaning
200	User logged in
403	Wrong credentials
406	User not activated
422	Validation failed

Send Password Reset Mail

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/user/password/sendResetMail \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "mail@siwecos.de"
}'

POST /api/v2/user/password/sendResetMail HTTP/1.1
Host: bla.local
Content-Type: application/json

{
    "email": "mail@siwecos.de"
}

An activated user can reset his password.

The Response has the following structure:

{
  "message": "If the user exists in our records, the mail was sent."
}

HTTP Request

POST /api/v2/user/password/sendResetMail

Request Parameters

Parameter	Type	Description
email	`email`	The user's email address

Response Status Codes

Code	Meaning
200	Password-Reset email was sent if the activated user exists in the database
422	Validation failed

Reset Password

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/user/password/reset \
  -H 'Content-Type: application/json' \
  -d '{
    "newpassword": "ABCD1234",
    "reset_token": "zVgL1Aa5N57L9CEnrpH8xsmKH983Ip3u9ElnjYuED08YR449999Y0j551iFg80m36ybdn3JTJTz22DhNZL87R76pIDw8O95n"
}'

POST /api/v2/user/password/reset HTTP/1.1
Host: bla.local
Content-Type: application/json

{
    "newpassword": "ABCD1234",
    "reset_token": "zVgL1Aa5N57L9CEnrpH8xsmKH983Ip3u9ElnjYuED08YR449999Y0j551iFg80m36ybdn3JTJTz22DhNZL87R76pIDw8O95n"
}

The user can reset his password.

The Response has the following structure:

{
  "message": "Reset completed"
}

HTTP Request

POST /api/v2/user/password/reset

Request Parameters

Parameter	Type	Description
newpassword	`password`	The user's new password
reset_token	`string`	The associated reset token that was sent by email

Response Status Codes

Code	Meaning
200	Password reset completed
404	User not found
422	Validation failed

Get User Data

The Request must have the following structure:

curl http://bla.local/api/v2/user \
  -H 'SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y'

GET /api/v2/user HTTP/1.1
Host: bla.local
SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y

A logged in user can retrieve his user data.

The Response has the following structure:

{
  "token": "Y2jHgqtSVcz8eFqiV4eC0s5Y",
  "email": "mail@siwecos.de",
  "preferred_language": "de",
  "is_active": true,
  "domain_verification_token": "p522893XyZYSu5riyZ7PRCQ1ynOTyrfsYfx0NNUjbB"
}

HTTP Request

GET /api/v2/user

Authentication via HTTP-Header SIWECOS-Token required.

Response Status Codes

Code	Meaning
200	User data
403	User token invalid / missing

Update User Data

The Request must have the following structure:

curl -X PATCH \
  http://bla.local/api/v2/user \
  -H 'Content-Type: application/json' \
  -H 'SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y' \
  -d '{
    "email": "mail@siwecos.de",
    "preferred_language": "en",
    "newpassword": "ABCD1234"
}'

PATCH /api/v2/user HTTP/1.1
Host: bla.local
Content-Type: application/json
SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y

{
    "email": "mail@siwecos.de",
    "preferred_language": "en",
    "newpassword": "ABCD1234"
}

The user can update his details.

The Response has the following structure:

{
  "message": "User updated"
}

HTTP Request

PATCH /api/v2/user

Authentication via HTTP-Header SIWECOS-Token required.

Request Parameters

Parameter	Type	Description
email	`email`	The user's new email address
newpassword	`password`	The user's new password
preferred_language	`string`	The user's preferred language for the app

Response Status Codes

Code	Meaning
200	User updated
403	`SIWECOS-Token` not valid
422	Validation failed

User Deletion

The Request must have the following structure:

curl -X DELETE \
  http://bla.local/api/v2/user \
  -H 'Content-Type: application/json' \
  -H 'SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y' \

DELETE /api/v2/user HTTP/1.1
Host: bla.local
Content-Type: application/json
SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y

The user can delete his account.

The Response has the following structure:

{
  "message": "User deleted"
}

HTTP Request

DELETE /api/v2/user

Authentication via HTTP-Header SIWECOS-Token required.

Response Status Codes

Code	Meaning
200	User deleted
403	`SIWECOS-Token` not valid

After deletion the associated Token with all the registered Domains and Scans will also be deleted.

Tokens

In addition to Users the API can also work user-less while working only with Tokens. With this functionality a 3rd-Party Plugin can be created that will automate the registration process completly.

Register Token

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/token \
  -H 'Content-Type: application/json' \
  -d '{
    "agb_check": true
}'

POST /api/v2/token HTTP/1.1
Host: bla.local
Content-Type: application/json

{
    "agb_check": true
}

A SIWECOS Token can be registered instead of a User.

The Response has the following structure:

{
    "token": "w3JofJRDjGsj2MfOlrDivNMK"
}

HTTP Request

POST /api/v2/token

Request Parameters

Parameter	Type	Description
agb_check	`boolean`	The user must accept the General Terms and Conditions to use this service

Response Status Codes

Code	Meaning
200	Token registered
422	Validation failed

Domains

Adding a Domain

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/domain \
  -H 'Content-Type: application/json' \
  -H 'SIWECOS-Token: 46rzR6TLJxtt7OrwLST+aTrc' \
  -d '{
    "domain": "siwecos.de"
}'

POST /api/v2/domain HTTP/1.1
Host: bla.local
Content-Type: application/json
SIWECOS-Token: 46rzR6TLJxtt7OrwLST+aTrc

{
    "domain": "siwecos.de"
}

A new Domain can be added/registered to a Token.

The Response has the following structure:

{
    "domain": "siwecos.de",
    "url": "https://siwecos.de",
    "verification_token": "QsMNH613iGPScan554n7v0f4V29s6W5p9kzPOfA8oECH1Drejv7jpUE53i323tU8",
    "is_verified": false
}

HTTP Request

POST /api/v2/domain

Authentication via HTTP-Header SIWECOS-Token required.

Request Parameters

Parameter	Type	Description
domain	`string`	The domain that should be registered

Response Status Codes

Code	Meaning
200	Domain created
403	Domain is already verified
410	Domain was not created / could not be saved
422	Validation failed

Domain Verification

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/domain/verify \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "siwecos.de"
}'

POST /api/v2/domain/verify HTTP/1.1
Host: bla.local
Content-Type: application/json

{
    "domain": "siwecos.de"
}

Verify the associated Domain for the given domain.

The Response has the following structure:

{
    "domain": "siwecos.de",
    "url": "https://siwecos.de",
    "verification_token": "QsMNH613iGPScan554n7v0f4V29s6W5p9kzPOfA8oECH1Drejv7jpUE53i323tU8",
    "is_verified": true
}

HTTP Request

POST /api/v2/domain/verify

Authentication via HTTP-Header SIWECOS-Token required.

Request Parameters

Parameter	Type	Description
domain	`string`	The domain that should be verified

Response Status Codes

Code	Meaning
200	Domain verified
403	Domain is already verified
404	Domain could not be verified
409	Domain verification exception
422	Validation failed

The domain can either be verified by <meta>-Tag or HTML-Page. [Further information]

The HTTP error code 404 will be returned if the verification token could not be found.
The HTTP error code 409 will be returned if the domain host could not be reached [Connection Issues, TLS-Problems, HTTP-Responses with 5xx codes, etc.]

Listing all Domains

The Request must have the following structure:

curl -X GET \
  http://bla.local/api/v2/domain \
  -H 'SIWECOS-Token: 46rzR6TLJxtt7OrwLST+aTrc'

GET /api/v2/domain HTTP/1.1
Host: bla.local
SIWECOS-Token: 46rzR6TLJxtt7OrwLST+aTrc

Returning a list of domains for the specified SIWECOS-Token.

The Response has the following structure:

{
    "domains": [
        {
            "domain": "siwecos.de",
            "url": "https://siwecos.de",
            "verification_token": "QsMNH613iGPScan554n7v0f4V29s6W5p9kzPOfA8oECH1Drejv7jpUE53i323tU8",
            "is_verified": false
        },
        {
            "domain": "lednerb.eu",
            "url": "https://lednerb.eu",
            "verification_token": "9r0Ei2ZG14PGXoN6T32BHid0GWCKiPP0R3LDZo7U8oE2z5JaBL80k5n1284Pql7I",
            "is_verified": true
        }
    ]
}

HTTP Request

GET /api/v2/domain

Authentication via HTTP-Header SIWECOS-Token required.

Response Status Codes

Code	Meaning
200	List of domains returned
403	`SIWECOS-Token` not valid

Requesting Domain Details

The Request must have the following structure:

curl -X GET \
  http://bla.local/api/v2/domain/siwecos.de \
  -H 'SIWECOS-Token: 46rzR6TLJxtt7OrwLST+aTrc'

GET /api/v2/domain/siwecos.de HTTP/1.1
Host: bla.local
SIWECOS-Token: 46rzR6TLJxtt7OrwLST+aTrc

Returning the details for a specified Domain.

The Response has the following structure:

{
    "domain": "siwecos.de",
    "url": "https://siwecos.de",
    "verification_token": "QsMNH613iGPScan554n7v0f4V29s6W5p9kzPOfA8oECH1Drejv7jpUE53i323tU8",
    "is_verified": false
}

HTTP Request

GET /api/v2/domain/{domain}

Authentication via HTTP-Header SIWECOS-Token required.

Response Status Codes

Code	Meaning
200	Domain details returned
403	`SIWECOS-Token` not valid
404	Domain not found

Deleting a Domain

The Request must have the following structure:

curl -X DELETE \
  http://bla.local/api/v2/domain \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "siwecos.de"
}'

DELETE /api/v2/domain HTTP/1.1
Host: bla.local
Content-Type: application/json

{
    "domain": "siwecos.de"
}

A Domain can be deleted.

The Response has the following structure:

{
    "message": "Domain deleted"
}

HTTP Request

DELETE /api/v2/domain

Authentication via HTTP-Header SIWECOS-Token required.

Request Parameters

Parameter	Type	Description
domain	`string`	The domain that should be deleted

Response Status Codes

Code	Meaning
200	Domain deleted
403	Forbidden
422	Validation failed

Retrieving the latest Main-URL Scan Report

The Request must have the following structure:

curl -X GET \
  http://bla.local/api/v2/domain/example.org/report/en \
  -H 'SIWECOS-Token: 46rzR6TLJxtt7OrwLST+aTrc'

GET /api/v2/domain/example.org/report/en HTTP/1.1
Host: bla.local
SIWECOS-Token: 46rzR6TLJxtt7OrwLST+aTrc

Retrieving the latest Scan Report for the given Domain.

The Response has the same structure as the Scan Report

HTTP Request

GET /api/v2/domain/{domain}/report/{language?}

Authentication via HTTP-Header SIWECOS-Token is required for non-free Scans.

Request Parameters

Parameter	Type	Description
domain	`string`	The domain the report is requested for
language_code	`string`	One of the supported language codes for translated results: `de` or `en`

Response Status Codes

Code	Meaning
200	Latest Scan Report
404	No scan found

Retrieving the latest Full Scan Report

The Request must have the following structure:

curl -X GET \
  http://bla.local/api/v2/domain/example.org/fullreport/en \
  -H 'SIWECOS-Token: 46rzR6TLJxtt7OrwLST+aTrc'

GET /api/v2/domain/example.org/fullreport/en HTTP/1.1
Host: bla.local
SIWECOS-Token: 46rzR6TLJxtt7OrwLST+aTrc

Retrieving the latest SiwecosScan Report for the given Domain.

The Response has the same structure as the Full Scan Report

HTTP Request

GET /api/v2/domain/{domain}/fullreport/{language?}

Authentication via HTTP-Header SIWECOS-Token is required for non-free Scans.

Request Parameters

Parameter	Type	Description
domain	`string`	The domain the report is requested for
language_code	`string`	One of the supported language codes for translated results: `de` or `en`

Response Status Codes

Code	Meaning
200	Latest Scan Report
404	No scan found

Retrieving the sealproof data

The Request must have the following structure:

curl -X GET \
  "http://bla.local/api/v2/domain/example.org/sealproof"

GET /api/v2/domain/example.org/sealproof HTTP/1.1
Host: bla.local

The data for the SIWECOS sealproof can be requested.

The Response has the following structure:

{
  "domain": "example.org",
  "score": 82,
  "finished_at": "2019-04-09T05:58:55Z"
}

HTTP Request

GET /api/v2/domain/{domain}/sealproof

Request Parameters

Parameter	Type	Description
domain	`string`	The domain for the requested sealproof

Response Status Codes

Code	Meaning
200	OK
404	Scan not found
409	Domain not verified

Scans

Starting a Freescan

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/freescan \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "siwecos.de"
}'

POST /api/v2/freescan HTTP/1.1
Host: bla.local
Content-Type: application/json

{
    "domain": "siwecos.de"
}

A Freescan can be started.

The Response has the following structure:

{
  "scan_id": 6
}

HTTP Request

POST /api/v2/freescan

Request Parameters

Parameter	Type	Description
domain	`string`	The domain that should be scanned

Response Parameters

Parameter	Type	Description
scan_id	`integer`	The scan's `id`

Response Status Codes

Code	Meaning
200	Scan started
422	Validation failed

Starting a Scan

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/freescan \
  -H 'Content-Type: application/json' \
  -H 'SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y' \
  -d '{
    "domain": "siwecos.de"
}'

POST /api/v2/scan HTTP/1.1
Host: bla.local
Content-Type: application/json
SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y

{
    "domain": "siwecos.de"
}

A regular scan can be started for a registered domain.

The Response has the following structure:

{
    "scan_id": 3
}

HTTP Request

POST /api/v2/scan

Authentication via HTTP-Header SIWECOS-Token required.

Request Parameters

Parameter	Type	Description
domain	`string`	The domain that should be scanned

Response Parameters

Parameter	Type	Description
scan_id	`integer`	The scan's `id`

Response Status Codes

Code	Meaning
200	Scan started
404	Associated Domain not found or unverified
422	Validation failed

Retrieving the Scan Status

The Request must have the following structure:

curl -X GET \
  http://bla.local/api/v2/scan/3913 \
  -H 'Content-Type: application/json' \
  -H 'SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y'

GET /api/v2/scan/3913 HTTP/1.1
Host: bla.local
SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y
Content-Type: application/json

The scan status can be requested.

The Response has the following structure:

{
  "id": 1,
  "status": "running",
  "has_error": false,
  "started_at": "2019-04-09T05:28:43Z",
  "finished_at": null
}

HTTP Request

GET /api/v2/scan/{scan_id}

Authentication via HTTP-Header SIWECOS-Token is required for non-freescans.

Request Parameters

Parameter	Type	Description
scan_id	`integer`	The scan's `id`. It's returned when you request a scan start

Response Parameters

Parameter	Type	Description
status	`string`	The status can be: `created`, `running`, `finished` or `failed`
has_error	`boolean`	Determines if the scan had an error
started_at	`date`	DateTime String for the start time (when the scan was dispatched to the Core-API)
finished_at	`date`	DateTime String for the finished time (when the result was received from the Core-API)

Response Status Codes

Code	Meaning
200	Scan status retrieved
403	Forbidden
404	Scan not found
422	Validation failed

Retrieving the Main-URL Scan Report

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/scan/3913/en \
  -H 'Content-Type: application/json' \
  -H 'SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y'

POST /api/v2/scan/3913/en HTTP/1.1
Host: bla.local
SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y
Content-Type: application/json

The scan report can be requested.

The Response has the following structure:

{
  "id": 1,
  "status": "finished",
  "has_error": false,
  "started_at": "2019-04-09T05:28:43Z",
  "finished_at": "2019-04-09T05:58:55Z",
  "score": 87,
  "report": [
    // Core-API Report for different Scanners
    // For documentation purposes only the siwecos/HSHS-DOMXSS-Scanner results are listed here
    {
      "scanner_name": "Header Scanner",
      "scanner_code": "HEADER",
      "score": 85,
      "has_error": false,
      "error_message": null,
      "started_at": "2019-04-09T05:28:50Z",
      "finished_at": "2019-04-09T05:28:56Z",
      "tests": [
        // for documentation purpose only one test is listed here
        {
          "headline": "Check of HSTS protection",
          "score": 100,
          "has_error": false,
          "result": "Your website can only be reached via the secure HTTPS protocol. Communication between your website and its visitors can not be intercepted or manipulated.",
          "result_details": [
              "The value of 'max-age' is greater than 6 months."
          ],
          "result_description": null,
          "solution_tips": "<p>If the connection to your page is not encrypted, all communication between your site and its users can be intercepted and manipulated. </p><p>max-age=63072000; includeSubdomains; HTTP Strict Transport Security (HSTS) is a web security policy mechanism that is easy to integrate. </p> <b>--snip</b><pre> # Activate HTTP Strict Transport Security (HSTS) # Required: \"max-age\" # Optional: \"includeSubDomains\"</pre> <pre>  <b>Header set Strict-Transport-Security \"max-age=31556926; includeSubDomains\"</b> </pre> <p><b>--snap</b> </p><p>Here is an example of an .htaccess file which will set the <b>Header Scanner</b> to green. (<a target=\"siwecos_wiki\" href=\"https://siwecos.de/wiki/Htaccess/EN\" title=\"Htaccess/EN\">.htaccess example</a>) </p>",
          "information_link": "https://siwecos.de/wiki/No-Encryption-Found/EN"
        }
      ]
    }
  ]
}

HTTP Request

POST /api/v2/scan/{scan_id}/{language_code}

Authentication via HTTP-Header SIWECOS-Token is required for non-freescans.

Request Parameters

Parameter	Type	Description
scan_id	`integer`	The scan's `id`. It's returned when you request a scan start
language_code	`string`	One of the supported language codes for translated results: `de` or `en`

Response Parameters

Parameter	Type	Description
status	`string`	The status can be: `finished`
has_error	`boolean`	Determines if the scan had an error
started_at	`date`	DateTime String for the start time (when the scan was dispatched to the Core-API)
finished_at	`date`	DateTime String for the finished time (when the result was received from the Core-API)
report	`array`	Array of translated and formatted scan results that where delivered by the Core-API

Response Status Codes

Code	Meaning
200	Scan status retrieved
403	Forbidden
404	Scan not found
422	Validation failed

Retrieving the Main-URL Scan Report as PDF

The Request must have the following structure:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
      "SIWECOS-Token": "Y2jHgqtSVcz8eFqiV4eC0s5Y"
  }' \
  "http://bla.local/api/v2/scan/3913/en/pdf"

POST /api/v2/scan/3913/en/pdf HTTP/1.1
Host: bla.local
Content-Type: application/json

{
  "SIWECOS-Token": "Y2jHgqtSVcz8eFqiV4eC0s5Y"
}

The scan report can be requested as a PDF file.

A PDF file will be downloaded.

HTTP Request

POST /api/v2/scan/{scan_id}/{language_code}/pdf

Authentication via HTTP-Post-Parameter SIWECOS-Token is required for non-freescans.

Request Parameters

Parameter	Type	Description
scan_id	`integer`	The scan's `id`. It's returned when you request a scan start
language_code	`string`	One of the supported language codes for translated results: `de` or `en`
SIWECOS-Token	`string`	SIWECOS-Token for non-freescans

Response Status Codes

Code	Meaning
200	PDF Report
403	Forbidden
404	Scan not found
409	Scan not finished

Retrieving the Full Scan Report

The Request must have the following structure:

curl -X POST \
  http://bla.local/api/v2/siwecosScan/3913/en \
  -H 'Content-Type: application/json' \
  -H 'SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y'

POST /api/v2/siwecosScan/3913/en HTTP/1.1
Host: bla.local
SIWECOS-Token: Y2jHgqtSVcz8eFqiV4eC0s5Y
Content-Type: application/json

The scan report can be requested.

The Response has the following structure:

{
  "id": 1,
  "status": "finished",
  "has_error": false,
  "started_at": "2019-04-09T05:28:43Z",
  "finished_at": "2019-04-09T05:58:55Z",
  "score": 87,
  "scanner_scores": [
    "DOMXSS": 25,
    "HEADER": 42.5,
    "INFOLEAK": 50,
    "INI_S": 50,
    "TLS": 50
  ],
  "reports": [
    // Arrays with one report for each scanned URL or MailDomain
    "https://example.org": [
      // ScanReport for Main-URL
    ],
    "https://example.org/blog": [
      // ScanReport for first crawledUrl, ...
    ],
    "mx1.example.org": [
      // ScanReport for first MailDomain, ...
    ],
    "...": [
      // ...
    ]
  ]
}

HTTP Request

POST /api/v2/siwecosScan/{scan_id}/{language_code}

Authentication via HTTP-Header SIWECOS-Token is required for non-freescans.

Request Parameters

Parameter	Type	Description
scan_id	`integer`	The scan's `id`. It's returned when you request a scan start
language_code	`string`	One of the supported language codes for translated results: `de` or `en`

Response Parameters

Parameter	Type	Description
status	`string`	The status can be: `finished`
has_error	`boolean`	Determines if the scan had an error
started_at	`date`	DateTime String for the start time (when the scan was dispatched to the Core-API)
finished_at	`date`	DateTime String for the finished time (when the result was received from the Core-API)
score	`integer`	Calculated weighted total score for the scan
scanner_scores	`array`	Average score by scanner
reports	`array`	Array of translated and formatted scan reports for each scanned `URL` or `MailDomain`

Response Status Codes

Code	Meaning
200	Scan status retrieved
403	Forbidden
404	Scan not found
422	Validation failed

Retrieving the Full Scan Report as PDF

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
      "SIWECOS-Token": "Y2jHgqtSVcz8eFqiV4eC0s5Y"
  }' \
  "http://bla.local/api/v2/siwecosScan/3913/en/pdf"

POST /api/v2/siwecosScan/3913/en/pdf HTTP/1.1
Host: bla.local
Content-Type: application/json

{
  "SIWECOS-Token": "Y2jHgqtSVcz8eFqiV4eC0s5Y"
}

The scan report can be requested as a PDF file.

A PDF file will be downloaded.

HTTP Request

POST /api/v2/siwecosScan/{scan_id}/{language_code}/pdf

Authentication via HTTP-Post-Parameter SIWECOS-Token is required for non-freescans.

Request Parameters

Parameter	Type	Description
scan_id	`integer`	The scan's `id`. It's returned when you request a scan start
language_code	`string`	One of the supported language codes for translated results: `de` or `en`
SIWECOS-Token	`string`	SIWECOS-Token for non-freescans

Response Status Codes

Code	Meaning
200	PDF Report
403	Forbidden
404	Scan not found
409	Scan not finished

Introduction

Users

User Registration

HTTP Request

Request Parameters

Response Status Codes

User Activation

HTTP Request

Request Parameters

Response Status Codes

Resend Activation Mail

HTTP Request

Request Parameters

Response Status Codes

User Login

HTTP Request

Request Parameters

Response Status Codes

Send Password Reset Mail

HTTP Request

Request Parameters

Response Status Codes

Reset Password

HTTP Request

Request Parameters

Response Status Codes

Get User Data

HTTP Request

Response Status Codes

Update User Data

HTTP Request

Request Parameters

Response Status Codes

User Deletion

HTTP Request

Response Status Codes

Tokens

Register Token

HTTP Request

Request Parameters

Response Status Codes

Domains

Adding a Domain

HTTP Request

Request Parameters

Response Status Codes

Domain Verification

HTTP Request

Request Parameters

Response Status Codes

Listing all Domains

HTTP Request

Response Status Codes

Requesting Domain Details

HTTP Request

Response Status Codes

Deleting a Domain

HTTP Request

Request Parameters

Response Status Codes

Retrieving the latest Main-URL Scan Report

HTTP Request

Request Parameters

Response Status Codes

Retrieving the latest Full Scan Report

HTTP Request

Request Parameters

Response Status Codes

Retrieving the sealproof data

HTTP Request

Request Parameters

Response Status Codes

Scans

Starting a Freescan

HTTP Request

Request Parameters

Response Parameters

Response Status Codes

Starting a Scan

HTTP Request