RESTful API Documentation

Updated: Wednesday, August 26, 2020 12:10 MDT
Usability Examples
Request Header Tags
Tag Name
Definition
Example
Authorization
Required in: HEAD, GET, PUT, DELETE, POST, OPTIONS.Specify the alias followed by a colon and the key for the endpoint that makes the request. When registering a new endpoint the first time, you create an alias that will be assigned to the endpoint. The key is a unique 36-bit string of type UUID randomly generated for a new endpoint that must be retrieved from the database.
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2019-03-05 14:43:16.526935-07"
            -H "Authorization: Subnet20:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Record: 1234"
            https://your_dedicated_host/api/v1/registration
Host
Required in: HEAD, GET, PUT, DELETE, POST, OPTIONS.Specify the Fully Qualified Domain Name (FQDN) of the endpoint that is making the request. The FQDN of the endpoint must match the registration of the endpoint in the database. Only registered endpoints with the same FQDN that's in the database can make requests. The FQDN of the endpoint must be a public domain name or a public IPv4 address.
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Record: 1234"
            https://your_dedicated_host/api/v1/registration
Date
Required in: HEAD, GET, PUT, DELETE, POST, OPTIONS. An informational tag, primarily used for keeping track of the date and time of a request from the endpoint. When registering a new endpoint the value of this tag will be used to specify when the access key is created. Since the default value for the field "datecreated" is literally the string "empty", you must provide the date and time to create a new access key.
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"    
            -H "Record: 1234"        
            https://your_dedicated_host/api/v1/registration
Record
Required in: GET, PUT, DELETE, POST. Specifies the unique, nonsequential integer of a specific row of a table in the database associated with a specific endpoint. It is also used when an endpoint has more than one row or entry in a table.
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Record: 1234"
            https://your_dedicated_host/api/v1/registration/alias
Content-Type
Valid only in PUT requests and POST requests. Supports five types of input in requests: "text/plain", "application/json", "application/octet-stream", "multipart/form-data", and "base64". This tag is for identifying uploaded data via PUT requests and POST requests, in the Logs of the REST-API.
curl -X PUT -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Content-Type: text/plain"
            -H "Content: Value:bG9jYWxob3N0LmxvY2FsZG9tYWlu"
            -H "Record: 1234"
            https://your_dedicated_host/api/v1/registration/fqdn
Content: File
Valid only in POST requests. Specifies the absolute pathname to a file that exists on the endpoint that contains data. The absolute pathname to the file must be encoded encoded in base64 format. This request uploads the file to a special table in the database named "pendinguploads" that first assigns a unique Object ID to the file in case the uploading of the file is interrupted and needs to be resumed later. Next the special table "pendinguploads" acts like a queue manager and handles which tables in the database are modified by the POST request.
Step #1
/root/path/to/file/filename

Step #2
echo -n '/root/path/to/file/filename' | base64

Step #3
-H "Content: File:bG9jYWxob3N0LmxvY2FsZG9tYWlu" 

Step #4
curl -X POST -H "Host: www.deepsentry.com"
             -H "Date: 2018-07-28 16:06:30.393793-06"
             -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
             -H "Record: 1234"
             -H "Content-Type: text/plain"
             -H "Content: File:bG9jYWxob3N0LmxvY2FsZG9tYWlu"
             https://your_dedicated_host/api/v1/targets/localfile
Content: Value
Valid only in PUT requests. Raw data or compressed binary encoded as base64. This header tag is limited to 16K bits or 2000 bytes. Upload size is restricted due to maximum lengths of base64 encoded strings in header tags and maximum lengths of URIs for HTTP/HTTPS schema.
Step #
echo -n 'AAAAB3NzaC1yc2E AAAABIwAAAQEA klOUpk DHrfHY17 SbrmTIpNLTGK9Tjo  /BWDSUGPl+na fzlHDTYW7 hdI4yZ5e w18JH4JW9jbhUFr viQzM7xlELEVf4h 9lFX5QVkbPppSwg0 cda3Pbv7kOdJ/MTyBlWXFC R+HAo3FX RitBqxiX1nKhX pHAZsMciLq8V6 RjsNAQwdsdMF vSlVK/7XAt3FaoJo AsncM1Q9x5+3 V0Ww68/eIFm b1zu UFljQJKp rrX88 XypNDv jYNby6vw/ Pb0rwert/EnmZ+AW4 OZPnTPI89ZPm VMLuayrD2cE86Z/il8b+gw3r3+ 1nKatmI kjn2so1d01Qr aTlM qVSsbx NrRFi 9wrf+M7Q==' | base64

Step #2
-H "Content: Value:c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBQkl3QUFBUUVBa2xPVXBrREhyZkhZMTdTYnJtVElwTkxUR0s5VGpvbS9CV0RTVUdQbCtuYWZ6bEhEVFlXN2hkSTR5WjVldzE4Skg0Slc5amJoVUZydmlRek03eGxFTEVWZjRoOWxGWDVRVmtiUHBwU3dnMGNkYTNQYnY3a09kSi9NVHlCbFdYRkNSK0hBbzNGWFJpdEJxeGlYMW5LaFhwSEFac01jaUxxOFY2UmpzTkFRd2RzZE1GdlNsVksvN1hBdDNGYW9Kb0FzbmNNMVE5eDUrM1YwV3c2OC9lSUZtYjF6dVVGbGpRSktwcnJYODhYeXBORHZqWU5ieTZ2dy9QYjByd2VydC9Fbm1aK0FXNE9aUG5UUEk4OVpQbVZNTHVheXJEMmNFODZaL2lsOGIrZ3czcjMrMW5LYXRtSWtqbjJzbzFkMDFRcmFUbE1xVlNzYnhOclJGaTl3cmYrTTdRPT0gdXNlcm5hbWVAbG9jYWxkb21haW4ubG9jYWxob3N0X29yX2Z1bGx5X3F1YWxpZmllZF9kb21haW5fbmFtZQ==" 

Step #3
curl -X PUT -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Record: 1234"
            -H "Content-Type: text/plain"
            -H "Content: Value:c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBQkl3QUFBUUVBa2xPVXBrREhyZkhZMTdTYnJtVElwTkxUR0s5VGpvbS9CV0RTVUdQbCtuYWZ6bEhEVFlXN2hkSTR5WjVldzE4Skg0Slc5amJoVUZydmlRek03eGxFTEVWZjRoOWxGWDVRVmtiUHBwU3dnMGNkYTNQYnY3a09kSi9NVHlCbFdYRkNSK0hBbzNGWFJpdEJxeGlYMW5LaFhwSEFac01jaUxxOFY2UmpzTkFRd2RzZE1GdlNsVksvN1hBdDNGYW9Kb0FzbmNNMVE5eDUrM1YwV3c2OC9lSUZtYjF6dVVGbGpRSktwcnJYODhYeXBORHZqWU5ieTZ2dy9QYjByd2VydC9Fbm1aK0FXNE9aUG5UUEk4OVpQbVZNTHVheXJEMmNFODZaL2lsOGIrZ3czcjMrMW5LYXRtSWtqbjJzbzFkMDFRcmFUbE1xVlNzYnhOclJGaTl3cmYrTTdRPT0gdXNlcm5hbWVAbG9jYWxkb21haW4ubG9jYWxob3N0X29yX2Z1bGx5X3F1YWxpZmllZF9kb21haW5fbmFtZQ=="
            https://your_dedicated_host/api/v1/targets/localfile
Content: Website
Valid only in PUT requests. Specifies a URL of a page of a website that contains raw data. This request uploads the raw contents of the URL as the value of the object.
Step #1
http://www.example.com/

Step #2
echo -n 'http://www.example.com/' | base64

Step #3
-H "Content: Website:aHR0cDovL3d3dy5leGFtcGxlLmNvbS8=" 

Step #4
curl -X PUT -H "Host: www.deepsentry.com"
             -H "Date: 2018-07-28 16:06:30.393793-06"
             -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
             -H "Record: 1234"
             -H "Content-Type: text/plain"
             -H "Content: Website:aHR0cDovL3d3dy5leGFtcGxlLmNvbS8="
             https://your_dedicated_host/api/v1/targets/localfile
If-Modified-Since
Required in Conditional GET requests. Valid only in GET requests. When a comparison is made between Last-Modified and If-Modified-Since, the values of both tags will be explicitly typed in PostgreSQL as "::TIMESTAMP WITH TIME ZONE UTC" before the comparison (the default timezone in the database is "UTC"). All successful GET requests that respond with data also respond with the header tag "Last-Modified:" so that users can compare the timestamp of If-Modified-Since to the timestamp of Last-Modified to determine whether or not to execute the GET request. If the comparison is false, the GET request will return code "412 Precondition Failed".
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2018-06-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Record: 1234"
            -H "If-Modified-Since: "2018-06-01 00:00:00.0-06" 
            https://your_dedicated_host/api/v1/predictions/analysis
If-Unmodified-Since
Required in Conditional PUT requests. Valid only in PUT requests. All successful PUT requests that update data or modify data also respond with the header tag "Last-Modified:" so that users can compare the timestamp of If-Unmodified-Since to the timestamp of Last-Modified to determine whether or not to execute the PUT request. When a comparison is made between Last-Modified and If-Unmodified-Since, the values of both tags will be explicitly typed in PostgreSQL as "::TIMESTAMP WITH TIME ZONE UTC" before the comparison (the default timezone in the database is "UTC"). If the comparison is true and the new data replaces the old data, then the PUT request will result with the code "200 Status OK". If the comparison is true and the new data is the same as the old data, then the PUT request will result with the code "204 No Content". If the comparison is false, the PUT request will return code "412 Precondition Failed".
curl -X PUT -H "Host: www.deepsentry.com"
            -H "Date: 2018-06-10 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Record: 1234"
            -H "If-Unmodified-Since: 2018-06-06 16:06:30.393793-06"
            -H "Content-Type: text/plain"
            -H "Content: Value:c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBQkl3QUFBUUVBa2xPVXBrREhyZkhZMTdTYnJtVElwTkxUR0s5VGpvbS9CV0RTVUdQbCtuYWZ6bEhEVFlXN2hkSTR5WjVldzE4Skg0Slc5amJoVUZydmlRek03eGxFTEVWZjRoOWxGWDVRVmtiUHBwU3dnMGNkYTNQYnY3a09kSi9NVHlCbFdYRkNSK0hBbzNGWFJpdEJxeGlYMW5LaFhwSEFac01jaUxxOFY2UmpzTkFRd2RzZE1GdlNsVksvN1hBdDNGYW9Kb0FzbmNNMVE5eDUrM1YwV3c2OC9lSUZtYjF6dVVGbGpRSktwcnJYODhYeXBORHZqWU5ieTZ2dy9QYjByd2VydC9Fbm1aK0FXNE9aUG5UUEk4OVpQbVZNTHVheXJEMmNFODZaL2lsOGIrZ3czcjMrMW5LYXRtSWtqbjJzbzFkMDFRcmFUbE1xVlNzYnhOclJGaTl3cmYrTTdRPT0gdXNlcm5hbWVAbG9jYWxkb21haW4ubG9jYWxob3N0X29yX2Z1bGx5X3F1YWxpZmllZF9kb21haW5fbmFtZQ=="
            https://your_dedicated_host/api/v1/targets/localfile
Search
Valid only in GET requests. Specifies a requirement of the GET request that the analysis must contain a specific phrase. Search performs case-insensitive pattern matching using PostgreSQL's "ILIKE" operator. When the phrase is found in the analysis, the analysis is included in the response. When the phrase is not found in the analysis the HTTP Status is "200 OK" and the message is "No matches found!".
Step #1
a_very_wordy_phrase

Step #2
echo -n 'a_very_wordy_phrase' | base64

Step #3
-H "Search: YV92ZXJ5X3dvcmR5X3BocmFzZQ=="

Step #4
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Record: 1234"
            -H "Search: YV92ZXJ5X3dvcmR5X3BocmFzZQ=="
            https://your_dedicated_host/api/v1/predictions/analysis
Response Header Tags
Tag Name
Definition
Example
Server
REST-API's official name and version number.
Server: DeepSentry REST-API v1.0
Cache-Control
Not implemented yet.
Cache-Control: no-cache
X-Content-Type-Options
Not implemented yet.
X-Content-Type-Options: nosniff
Content-Type
Responses will be "text/plain", "application/json", or "base64". Internal errors sometimes result in a non-descriptive error message, these will always be "text/plain". Errors which were the result of RESTful requests should be in JSON format of type "application/json".
Content-Type: application/json
Last-Modified
All successful GET requests that return data also return the header tag "Last-Modified" so that users can compare the timestamp of Last-Modified to the timestamp of If-Modified-Since to determine whether or not to execute the GET request. All successful PUT requests that return data also return the header tag "Last-Modified" so that users can compare the timestamp of Last-Modified to the timestamp of If-Unmodified-Since to determine whether or not to execute the PUT request. When a comparison is made between Last-Modified and If-Modified-Since/If-Unmodified-Since, the values of both tags will be explicitly typed in PostgreSQL as "::TIMESTAMP WITH TIME ZONE UTC" before the comparison (the default timezone in the database is "UTC").
Last-Modified: arbitrary_date_time_format
Error Code Responses
Tag Name
Definition
Example
400 1
You sent a malformed request that's missing a resource, missing an object, missing a parameter, or includes characters not recognized.
{
  "status":"error",
  "code":400,
  "message":"Bad Request",
  "response":"2019-03-04 14:44:23.393031-07 400 Bad Request: Malformed/missing request or invalid characters"
}
400 2
Your request wasn't processed because it's missing the required header tag named Authorization.
{
  "status":"error",
  "code":400,
  "message":"Unauthorized",
  "response":"2019-03-04 14:44:23.393031-07 400 Bad Request: Missing header tag Authorization:..."
}
400 3
Your request wasn't processed because it's missing the required header tag named Host.
{
  "status":"error",
  "code":400,
  "message":"Unauthorized",
  "response":"2019-03-04 14:44:23.393031-07 400 Bad Request: Missing header tag Host:..."
}
400 4
Your request wasn't processed because it's missing the required header tag named Date.
{
  "status":"error",
  "code":400,
  "message":"Unauthorized",
  "response":"2019-03-04 14:44:23.393031-07 400 Bad Request: Missing header tag Date:..."
}
401 1
There's something wrong with one or more of the header tags Host, Date, and Authorization. Your request wasn't processed because you're using credentials that are invalid or malformed.
{
  "status":"error",
  "code":401,
  "message":"Unauthorized",
  "response":"2019-03-04 14:44:23.393031-07 401 Unauthorized: Invalid credentials"
}
401 3
Your request wasn't processed because the header tag named Authorization is malformed, a part of the header tag is missing.
{
  "status":"error",
  "code":401,
  "message":"Unauthorized",
  "response":"2019-03-04 14:44:23.393031-07 401 Unauthorized: Malformed header tag Authorization:..."
}
401 4
Your request wasn't processed because the header tag named Host is malformed, a part of the header tag is missing.
{
  "status":"error",
  "code":401,
  "message":"Unauthorized",
  "response":"2019-03-04 14:44:23.393031-07 401 Unauthorized: Malformed header tag Host:..."
}
401 5
Your request wasn't processed because the header tag named Date is malformed, a part of the header tag is missing.
{
  "status":"error",
  "code":401,
  "message":"Unauthorized",
  "response":"2019-03-04 14:44:23.393031-07 401 Unauthorized: Malformed header tag Date:..."
}
401 6
Your request wasn't processed because the IP address of the endpoint that issued the request does not resolve to the IP address of the FQDN in the database for the endpoint registered in the REST-API. When an endpoint was registered with a FQDN that resolves to a public IP address this 401 error is possible.
{
  "status":"error",
  "code":401,
  "message":"Unauthorized",
  "response":"2019-03-04 14:44:23.393031-07 401 Unauthorized: IP address of request does NOT resolve to the IP address of the FQDN of the registered endpoint."
}
401 7
Your request wasn't processed because the IP address of the endpoint that issued the request does not resolve to the IP address in the database for the endpoint registered in the REST-API. When an endpoint was registered with only an IP address this error is possible.
{
  "status":"error",
  "code":401,
  "message":"Unauthorized",
  "response":"2019-03-04 14:44:23.393031-07 401 Unauthorized: IP address of request does NOT match the IP address of the registered endpoint."
}
401 8
Your request wasn't processed because either the FQDN of the endpoint that issued the request or the IP address of the endpoint that issued the request does not match the information in the database for the endpoint registered in the REST-API.
{
  "status":"error",
  "code":401,
  "message":"Unauthorized",
  "response":"2019-03-04 14:44:23.393031-07 401 Unauthorized: request does NOT match the FQDN or IP of the registered endpoint."
}
404
You sent a malformed request and requested something that doesn't exist. Your request was missing an object or missing a parameter.
{
  "status":"error",
  "code":404,
  "message":"Not Found",
  "response":"2019-03-04 14:44:23.393031-07 404 Not Found: Malformed request or missing object or missing parameter"
}
412 1
You asked the API to compare the header tag If-Modified-Since to the header tag Last-Modified, the condition is false therefore your GET request will not be processed and no data will be returned to you.
{
  "status":"error",
  "code":412,
  "message":"Precondition Failed",
  "response":"2019-03-04 14:44:23.393031-07 412 Precondition Failed: Resource not modified, header tag If-Modified-Since has invalid time"
}
412 2
You asked the API to compare the header tag If-Unmodified-Since to the header tag Last-Modified, the condition is false therefore the new contents of the value or file you requested to be uploaded will not replace the old contents of the value or file in the database.
{
  "status":"error",
  "code":412,
  "message":"Precondition Failed",
  "response":"2019-03-04 14:44:23.393031-07 412 Precondition Failed: Resource not modified, header tag If-Unmodified-Since has invalid time"
}
500 1
A complicated I/O error caused by the database or the operating system; usually, the request is not part of the issue. Unable to log request in database for audit. Suspect DB user lacks necessary permissions.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Unable to log request in database for audit. Suspect DB user lacks necessary permissions"
}
500 2
A complicated I/O error caused by the database or the operating system; usually, the request is not part of the issue. Processing POST request to upload file. Can't modify database table in use.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Processing POST request to upload file. Can't modify database table in use"
}
500 3
A complicated I/O error caused by the database or the operating system; usually, the request is not part of the issue. Processing POST request to upload file. Can't modify database table in use.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Processing POST request to upload file. Can't modify database table in use"
}
500 4
A complicated I/O error that's caused by the database or the operating system; usually, the request is not part of the issue. Processing POST request to upload file. Can't read file.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Processing POST request to upload file. Can't read file"
}
500 5
A complicated I/O error caused by the database or the operating system; usually, the request is not part of the issue. Processing POST request to upload file. Can't create new multipart form file.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Processing POST request to upload file. Can't create new multipart form file"
}
500 6
A complicated I/O error caused by the database or the operating system; usually, the request is not part of the issue. Processing POST request to upload file. Can't open file.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Processing POST request to upload file. Can't open file"
}
500 7
A complicated I/O error caused by the database or the operating system; usually, the request is not part of the issue. Processing POST request to upload file. Can't open file for reading.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Processing POST request to upload file. Can't open file for reading"
}
500 8
A complicated I/O error caused by the database or the operating system; usually, the request is not part of the issue. Processing POST request to upload file. Can't copy file to buffer.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Processing POST request to upload file. Can't copy file to buffer"
}
500 9
A complicated I/O error caused by the database or the operating system; usually, the request is not part of the issue. Processing POST request to upload file. Can't copy file to multipart form file.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Processing POST request to upload file. Can't copy file to multipart form file"
}
500 10
A complicated I/O error caused by the database or the operating system; usually, the request is not part of the issue. Processing POST request to upload file. Can't update contents of table in database with new status message.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Processing POST request to upload file. Can't update contents of table in database with new status message"
}
500 11
A complicated I/O error caused by the database or the operating system; usually, the request is not part of the issue. Processing POST request to upload file. Unknown issue with saving file contents to database.
{
  "status":"error",
  "code":500,
  "message":"Internal Server Error",
  "response":"2019-03-04 14:44:23.393031-07 500 Internal Server Error: Processing POST request to upload file. Unknown issue with saving file contents to database"
}
501
You requested a HTTP method the API has not implemented yet. The current API only supports HEAD, GET, PUT, DELETE, POST, and OPTIONS.
{
  "status":"error",
  "code":501,
  "message":"Not Implemented",
  "response":"2019-03-04 14:44:23.393031-07 501 Not Implemented: Requested HTTP method not implemented"
}
GET all header tags
HEAD Request
curl -I -X GET -H "Host: www.deepsentry.com"
               -H "Date: 2018-07-28 16:06:30.393793-06"
               -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
               https://your_dedicated_host/api/v1/registration
Output
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Type: application/json
Server: DeepSentry REST-API v1.0
X-Content-Type-Options: nosniff
Date: 2018-07-18 01:17:23 GMT
Content-Length: 463
GET all HTTP methods
OPTIONS Request
curl -I -X OPTIONS -H "Host: www.deepsentry.com"
                   -H "Date: 2018-07-28 16:06:30.393793-06"
                   -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                   https://your_dedicated_host/api/v1/registration
Output
HTTP/1.1 200 OK
Allow: HEAD, GET, PUT, DELETE, POST, OPTIONS
Cache-Control: no-cache
Content-Type: application/json
Server: DeepSentry REST-API v1.0
X-Content-Type-Options: nosniff
Date: 2018-07-18 01:32:17 GMT
Content-Length: 57
GET a value of a parameter
GET Request
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Alias: U3VibmV0MjA="
            https://your_dedicated_host/api/v1/registration/alias
The output to a GET request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the GET request. Message is the explanation of the HTTP status code for the GET request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings.
{
  "status":"data",
  "code":200,
  "message":"OK",
  "response":"{\"alias\":\"Subnet20\"}"
}
GET all parameter names
GET Request
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            https://your_dedicated_host/api/v1/registration
The output to a GET request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the GET request. Message is the explanation of the HTTP status code for the GET request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings.
{
  "status":"data",
  "code":200,
  "message":"OK",
  "response":"/api/v1/registration /api/v1/registration/record /api/v1/registration/alias /api/v1/registration/key /api/v1/registration/fqdn /api/v1/registration/ipaddress /api/v1/registration/datecreated /api/v1/registration/lastmodified /api/v1/registration/valid"
}
GET all values of all parameters
GET Request
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            https://your_dedicated_host/api/v1/registration/all
The output to a GET request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the GET request. Message is the explanation of the HTTP status code for the GET request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings.
{
  "status":"data",
  "code":200,
  "message":"OK",
  "response":"{\"record\":6,\"alias\":\"Subnet20\",\"key\":\"e3075055-a69b-4f2c-a488-b157b6eebb80\",\"fqdn\":\"www.deepsentry.com\",\"ipaddress\":\"162.255.119.250\",\"datecreated\":\"2019-03-02 15:43:16.167351-07\",\"lastmodified\":\"2019-03-02 15:48:07.183744-07\",\"valid\":true}"
}
GET Request Aggregation
GET Request
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            https://your_dedicated_host/api/v1/registration/record,alias
The output to a GET request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the GET request. Message is the explanation of the HTTP status code for the GET request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings.
{
  "status":"data",
  "code":200,
  "message":"OK",
  "response":"{\"record\":6,\"alias\":\"Subnet20\"}"
}
Conditional GET
Get the header tag Last-Modified before making the Conditional GET request
curl -I -X GET -H "Host: www.deepsentry.com"
               -H "Date: 2018-07-17 15:25:29.00-06"
               -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
               -H "Alias: U3VibmV0MjA="
               http://your_dedicated_host/api/v1/registration/alias,valid
Output
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Type: application/json
Last-Modified: 2018-03-19 01:20:20.000000-06
Server: DeepSentry REST-API v1.0
X-Content-Type-Options: nosniff
Date: 2018-07-18 02:22:21.000000 GMT
Content-Length: 98
Check if the values of the parameters were modified since today's timestamp (it's false)
curl -I -X GET -H "Host: www.deepsentry.com"
               -H "Date: 2018-07-17 15:00:00.000000-06"
               -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
               -H "Alias: U3VibmV0MjA="
               -H "If-Modified-Since: 2018-07-17 01:22:20.393793-06"
               http://your_dedicated_host/api/v1/registration/alias,valid
The output to a GET request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the GET request. Message is the explanation of the HTTP status code for the GET request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings.
{
  "status":"error",
  "code":412,
  "message":"Precondition Failed",
  "response":"Tuesday,July 17 2018,20:30:53:964122370 412 Precondition Failed: Resource not modified, time of header tag If-Modified-Since invalid"
}
Check if the values of the parameters were modified after the timestamp "Mon, 01 Mar 2018 01:20:20 -0600" (it's true)
curl -X GET -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-17 15:25:29.000000-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Alias: U3VibmV0MjA="
            -H "If-Modified-Since: 2018-03-01 01:20:20.000000-06"
            http://your_dedicated_host/api/v1/registration/alias,valid
The output to a GET request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the GET request. Message is the explanation of the HTTP status code for the GET request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings.
{
  "status":"data",
  "code":200,
  "message":"OK",
  "response":"{\"alias\":\"Subnet20\"} {\"valid\":true}"
}
PUT a value of a parameter
PUT Request
curl -X PUT -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Content-Type: text/plain"
            -H "Content: Value:c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBQkl3QUFBUUVBa2xPVXBrREhyZkhZMTdTYnJtVElwTkxUR0s5VGpvbS9CV0RTVUdQbCtuYWZ6bEhEVFlXN2hkSTR5WjVldzE4Skg0Slc5amJoVUZydmlRek03eGxFTEVWZjRoOWxGWDVRVmtiUHBwU3dnMGNkYTNQYnY3a09kSi9NVHlCbFdYRkNSK0hBbzNGWFJpdEJxeGlYMW5LaFhwSEFac01jaUxxOFY2UmpzTkFRd2RzZE1GdlNsVksvN1hBdDNGYW9Kb0FzbmNNMVE5eDUrM1YwV3c2OC9lSUZtYjF6dVVGbGpRSktwcnJYODhYeXBORHZqWU5ieTZ2dy9QYjByd2VydC9Fbm1aK0FXNE9aUG5UUEk4OVpQbVZNTHVheXJEMmNFODZaL2lsOGIrZ3czcjMrMW5LYXRtSWtqbjJzbzFkMDFRcmFUbE1xVlNzYnhOclJGaTl3cmYrTTdRPT0gdXNlcm5hbWVAbG9jYWxkb21haW4ubG9jYWxob3N0X29yX2Z1bGx5X3F1YWxpZmllZF9kb21haW5fbmFtZQ=="
            -H "Record: 1234"
            https://your_dedicated_host/api/v1/targets/blacklist
The output to a PUT request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the PUT request. Message is the explanation of the HTTP status code for the PUT request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings. The response confirms that the value of the tag is Base64, so it will be added to the database without being encoded.
{
  "status":"data",
  "code":202,
  "message":"Accepted",
  "response":"Updated /api/v1/targets/blacklist with new values for [blacklist]"
}
PUT Request Aggregation
Define all of the values for the parameters of the object in a flat JSON structure.
{
  \"directories\": {\"/home/david/.local\",\"/home/david/.ssh\"},
  \"valid\": true
}
Encode the flat JSON structure in base64 format. You could also encode the flat JSON structure in the base64 format using a freely available online base64 generator.
echo -n '{\"directories\":{\"/home/david/.local\",\"/home/david/.ssh\"},\"valid\":true}' | base64
Assemble the PUT request with the appropriate header tags "Record" and "Content: Value:"
"Content: Value:e1wiZGlyZWN0b3JpZXNcIjp7XCIvaG9tZS9kYXZpZC8ubG9jYWxcIixcIi9ob21lL2RhdmlkLy5zc2hcIn0sXCJ2YWxpZFwiOnRydWV9"
PUT Request
curl -X PUT -H "Host: www.deepsentry.com"
            -H "Date: 2018-08-28 19:37:24.781867-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "Content-Type: application/json"
            -H "Content: Value:e1wiZGlyZWN0b3JpZXNcIjp7XCIvaG9tZS9kYXZpZC8ubG9jYWxcIixcIi9ob21lL2RhdmlkLy5zc2hcIn0sXCJ2YWxpZFwiOnRydWV9"
            -H "Record: 1234" 
            https://your_dedicated_host/api/v1/targets/all
The output to a PUT request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the PUT request. Message is the explanation of the HTTP status code for the PUT request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings.
{
  "status":"data",
  "code":202,
  "message":"Accepted",
  "response":"Updated /api/v1/targets/all with new values for [blacklist, valid]"
}
Conditional PUT
Get the header tag Last-Modified before making the Conditional PUT request
curl -I -X GET -H "Host: www.deepsentry.com"
               -H "Date: 2017-07-17 15:25:29.000000-06"
               -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
               http://your_dedicated_host/api/v1/targets/blacklist
Output
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Type: application/json
Last-Modified: 2018-07-17 20:56:39.000000-06
Server: DeepSentry REST-API v1.0
X-Content-Type-Options: nosniff
Date: 2018-07-18 03:01:11 GMT
Content-Length: 1391
Check if the contents of the blacklist of targets of the host were modified after the timestamp "Mon, 01 Mar 2018 01:20:20 -0600" (it's true)
curl -X PUT -H "Host: www.deepsentry.com"
            -H "Date: 2018-07-28 16:06:30.393793-06"
            -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
            -H "If-Modified-Since: 2018-03-01 01:20:20.000000-06"
            -H "Content-Type: text/plain"
            -H "Content: Value:c3NoLXJzYSBBQUFBQjNOemFDMXljMkVBQUFBQkl3QUFBUUVBa2xPVXBrREhyZkhZMTdTYnJtVElwTkxUR0s5VGpvbS9CV0RTVUdQbCtuYWZ6bEhEVFlXN2hkSTR5WjVldzE4Skg0Slc5amJoVUZydmlRek03eGxFTEVWZjRoOWxGWDVRVmtiUHBwU3dnMGNkYTNQYnY3a09kSi9NVHlCbFdYRkNSK0hBbzNGWFJpdEJxeGlYMW5LaFhwSEFac01jaUxxOFY2UmpzTkFRd2RzZE1GdlNsVksvN1hBdDNGYW9Kb0FzbmNNMVE5eDUrM1YwV3c2OC9lSUZtYjF6dVVGbGpRSktwcnJYODhYeXBORHZqWU5ieTZ2dy9QYjByd2VydC9Fbm1aK0FXNE9aUG5UUEk4OVpQbVZNTHVheXJEMmNFODZaL2lsOGIrZ3czcjMrMW5LYXRtSWtqbjJzbzFkMDFRcmFUbE1xVlNzYnhOclJGaTl3cmYrTTdRPT0gdXNlcm5hbWVAbG9jYWxkb21haW4ubG9jYWxob3N0X29yX2Z1bGx5X3F1YWxpZmllZF9kb21haW5fbmFtZQ=="
            -H "Record: 1234"
            https://your_dedicated_host/api/v1/targets/blacklist
The output to a PUT request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the PUT request. Message is the explanation of the HTTP status code for the PUT request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings.
{
  "status":"data",
  "code":202,
  "message":"Accepted",
  "response":"Updated /api/v1/targets/blacklist with new values for [blacklist]"
}
POST contents of a file
POST Request
curl -X POST -H "Host: www.deepsentry.com"
             -H "Date: 2018-07-28 16:06:30.393793-06"
             -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
             -H "Content-Type: text/plain"
             -H "Content: File:bG9jYWxob3N0LmxvY2FsZG9tYWlu"
             -H "Record: 1234"
             https://your_dedicated_host/api/v1/targets/whitelist
The output to a POST request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the POST request. Message is the explanation of the HTTP status code for the POST request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings.
{
  "status":"data",
  "code":202,
  "message":"Accepted",
  "response":"none"
}
POST contents of a website
POST Request
curl -X POST -H "Host: www.deepsentry.com"
             -H "Date: 2018-07-28 16:06:30.393793-06"
             -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
             -H "Content-Type: text/plain"
             -H "Content: Website:aHR0cDovL3d3dy5leGFtcGxlLmNvbS8"
             -H "Record: 1234"
             https://your_dedicated_host/api/v1/targets/blacklist
The output to a POST request is a JSON structure with the members status, code, message, and response. Status is either "data" or "error". Code is the HTTP status code for the POST request. Message is the explanation of the HTTP status code for the POST request. Response is the actual answer to the request. Default values in the response that were created by the database will be returned as raw strings. Values in the response that were externally modified by users will be returned as base64-encoded strings.
{
  "status":"data",
  "code":202,
  "message":"Accepted",
  "response":"none"
}
DELETE a value of a parameter
DELETE Request
curl -X DELETE -H "Host: www.deepsentry.com"
               -H "Date: 2018-07-28 16:06:30.393793-06"
               -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
               -H "Record: 1234"
               https://your_dedicated_host/api/v1/predictions/record
JSON Output
{
  "status":"data",
  "code":200,
  "message":"OK",
  "response":"Successfully removed contents"
}
Getting Started
Setup the REST-API
  • 1. We will ask you a few questions about the identity of your first endpoint.
  • 2. The information you have to provide is an Alias, FQDN and IP. The alias is an unique string characters you want to use to identify your endpoint in public. The FQDN (not a local hostname) is the fully qualified domain name of your endpoint. Alternatively you could use a public IPv4 address as the fully qualified domain name. And, the public IPv4 address that your FQDN resolves to.
  • 3. An email will be sent to you containing a temporary access key you can use to finialize the registration of your first endpoint.
Register your first endpoint
  • 1. Retrieve the access key from the email we sent you.
    e3075055-a69b-4f2c-a488-b157b6eebb80
    
  • 2. Retrieve the complete URL of where your REST-API is located on your Amazon EC2 Dedicated Host from the email we sent you.
    https://your_dedicated_host/api/v1
    
  • 3. Send a GET request to "/api/vi/registration" to register the endpoint with the REST-API. The value for "Host" is the FQDN (or IP address) of your registered endpoint. The value for "Date" is the timestamp of when you would like your endpoint to be seen in the logs as being a registered endpoint. The value for "Authorization" has two parts. The first part is an alias for your endpoint that will be assigned to the endpoint upon authorization. The second part is the access key that was sent to you.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-03-09 00:00:01.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                https://your_dedicated_host/api/v1/registration
    
Register your endpoints
  • 1. Send a POST request to "/api/v1/registration/record" to receive a new record number to register the endpoint.
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2019-03-11 00:12:20.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 https://your_dedicated_host/api/v1/registration/record
    
  • 2. Send a PUT request to "/api/v1/registration/all" to register the endpoint. Define the required parameters for your endpoint in JSON then encode it in base64 for the header tag "Content: Value:".
    Step #1
    {
      \"alias\": \"Endpoint1\",
      \"fqdn\": \"162.255.119.43\",
      \"ipaddress\": \"162.255.119.43\",
      \"datecreated\": \"2019-03-11 00:12:20.000001-07\",
      \"valid\": true
    }
    
    Step #2
    echo -n '{\"alias\":\"Endpoint1\",\"fqdn\":\"162.255.119.43\",\"ipaddress\":\"162.255.119.43\",\"datecreated\":\"2019-03-11 00:12:20.000001-07\",\"valid\":true}' | base64
    
    Step #3
    -H "Content: Value:e1wiYWxpYXNcIjpcIkVuZHBvaW50MVwiLFwiZnFkblwiOlwiMTYyLjI1NS4xMTkuNDNcIixcImlwYWRkcmVzc1wiOlwiMTYyLjI1NS4xMTkuNDNcIixcImRhdGVjcmVhdGVkXCI6XCIyMDE5LTAzLTExIDAwOjEyOjIwLjAwMDAwMS0wN1wiLFwidmFsaWRcIjp0cnVlfQ=="    
    
    Step #4
    curl -X PUT -H "Host: www.deepsentry.com"
                -H "Date: 2019-03-11 00:12:20.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Content: Value:e1wiYWxpYXNcIjpcIkVuZHBvaW50MVwiLFwiZnFkblwiOlwiMTYyLjI1NS4xMTkuNDNcIixcImlwYWRkcmVzc1wiOlwiMTYyLjI1NS4xMTkuNDNcIixcImRhdGVjcmVhdGVkXCI6XCIyMDE5LTAzLTExIDAwOjEyOjIwLjAwMDAwMS0wN1wiLFwidmFsaWRcIjp0cnVlfQ==" 
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/registration/all
    
Perform training using files
  • When a POST request is sent to "/api/v1/targets/localfile" with the header tag "Content: File:" the local file on the endpoint specified by its absolute pathname is uploaded into the database.
  • 1. Send a POST request to "/api/v1/targets/record" to receive a new record number to setup storage.
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2020-02-28 14:32:20.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 https://your_dedicated_host/api/v1/targets/record
    
  • 2. Send a POST request to "/api/v1/targets/localfile" with the header tag "Content: File:" that specifies the absolute pathname to the local file on the endpoint.
    Step #1
    /root/path/to/file/filename
    
    Step #2
    echo -n '/root/path/to/file/filename' | base64
    
    Step #3
    -H "Content: File:bG9jYWxob3N0LmxvY2FsZG9tYWlu" 
    
    Step #4
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2020-02-28 14:32:20.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 -H "Record: 1234"
                 -H "Content: File: bG9jYWxob3N0LmxvY2FsZG9tYWlu"
                 https://your_dedicated_host/api/v1/targets/localfile
    
  • 4. Check the POST request to determine whether or not it has completed, send a GET request to "/api/v1/targets/active". If the POST request is still running, the value of active will be "true".
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2020-02-28 14:32:20.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/targets/active
    
  • 5. Check the POST request to determine whether or not it completed successfully, send a GET aggregation request to "/api/v1/targets/status" and "api/v1/targets/message". If the POST request completed successfully, the value of status will be "passed" and the value of "message" will be a message like "Updated /api/v1/targets/localfile with new values for [localfile]". If the POST request did not finish successfully, the value of status will be "failed" and the value of message will be the results of what exactly happened when executing the POST request.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2020-02-28 18:45:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"    
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/targets/status,message
    
  • 6. Send a POST request to "/api/v1/targets/training" to start training using the uploaded file.
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2020-02-28 18:45:00.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 -H "Record: 1234"
                 https://your_dedicated_host/deepsentry/api/v1/targets/training
    
  • 7. Check the POST request to determine whether or not it has completed, send a GET request to "/api/v1/targets/active". If the POST request is still running, the value of active will be "true".
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2020-02-28 18:45:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/targets/active
    
  • 8. Check the POST request to determine whether or not it completed successfully, send a GET aggregation request to "/api/v1/targets/status" and "/api/v1/targets/message". If the POST request completed successfully, the value of status will be "passed" and the value of "message" will be the word "Ingested" followed by "localfile" and the total size of the amount of data read by the AI, a message like "Ingested /root/path/to/file/filename 100MB". If the POST request did not finish successfully, the value of status will be "failed" and the value of message will be the results of what exactly happened when executing the POST request.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2020-02-28 18:45:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"    
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/targets/status,message
    
Perform training using websites
  • 1. Send a POST request to "/api/v1/targets/record" to receive a new record number to setup storage.
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2020-02-28 14:32:20.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 https://your_dedicated_host/api/v1/targets/record
    
  • 2. Send a PUT request to "/api/v1/targets/localfile" with the header tag "Content: Website:" that specifies the URL of a website that contains raw data. When a PUT request is sent to "/api/v1/targets/localfile" with the header tag "Content: Website:" the content of a website specified by its URL is uploaded into the database.
    Step #1
    http://www.example.com/
    
    Step #2
    echo -n 'http://www.example.com/' | base64
    
    Step #3
    -H "Content: Website:aHR0cDovL3d3dy5leGFtcGxlLmNvbS8="
    
    Step #4
    curl -X PUT -H "Host: www.deepsentry.com"
                 -H "Date: 2020-02-28 14:32:20.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 -H "Record: 1234"
                 -H "Content: Website:aHR0cDovL3d3dy5leGFtcGxlLmNvbS8=" 
                 https://your_dedicated_host/api/v1/targets/localfile
    
  • 6. Send a POST request to "/api/v1/targets/training" to upload file.
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2020-02-28 18:45:00.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 -H "Record: 1234"
                 https://your_dedicated_host/api/v1/targets/training
    
  • 7. Check the POST request to determine whether or not it has completed, send a GET request to "/api/v1/targets/active". If the POST request is still running, the value of active will be "true".
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2020-02-28 18:45:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/targets/active
    
  • 8. Check the POST request to determine whether or not it completed successfully, send a GET aggregation request to "/api/v1/targets/status" and "api/v1/targets/message". If the POST request completed successfully, the value of status will be "passed" and the value of "message" will be the word "Ingested" followed by "localfile" and the total size of the amount of data read, a message like "Ingested http://www.example.com/ 100MB". If the POST request did not finish successfully, the value of status will be "failed" and the value of message will be the results of what exactly happened when executing the POST request.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2020-02-28 18:45:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"    
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/targets/status,message
    
Make predictions using files
  • 1. Send a POST request to "/api/v1/targets/record" to retrieve a new record number.
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2019-12-11 23:21:00.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 https://your_dedicated_host/api/v1/targets/record
    
  • 2. Send a POST request to "/api/v1/targets/localfile" and set the value of "localfile" to an absolute pathname of a file on the endpoint. Encode the absolute pathname in base64. Include the record number in the new POST request.
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2019-12-11 23:21:00.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 -H "Record: 1234"
                 -H "Content: Value:L3Jvb3QvcGF0aC90by9maWxl"
                 https://your_dedicated_host/api/v1/targets/localfile
    
  • 3. Check the POST request to determine whether or not it has completed, send a GET request to "/api/v1/targets/active". If the POST request is still running, the value of active will be "true".
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-12-11 23:21:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/targets/active
    
  • 4. Check the POST request to determine whether or not it completed successfully, send a GET aggregation request to "/api/v1/targets/status" and "api/v1/targets/message". If the POST request completed successfully, the value of status will be "passed" and the value of "message" will be "empty". If the POST request did not finish successfully, the value of status will be "failed" and the value of message will be the results of what exactly happened when executing the POST request.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-12-11 23:21:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"    
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/targets/status,message
    
  • 5. Send a POST request to "/api/v1/predictions/analysis".
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2020-02-28 14:32:20.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 -H "Record: 1234"
                 https://your_dedicated_host/api/v1/predictions/analysis
    
  • 6. Check the POST request to determine whether or not it has completed, send a GET request to "/api/v1/predictions/active". If the POST request is still running, the value of active will be "true".
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-12-11 23:21:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/active
    
  • 7. Check the POST request to determine whether or not it completed successfully, send a GET aggregation request to "/api/v1/predictions/status" and "api/v1/predictions/message". If the POST request completed successfully, the value of status will be "passed" and the value of "message" will be "empty". If the POST request did not finish successfully, the value of status will be "failed" and the value of message will be the results of what exactly happened when executing the POST request.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-12-11 23:21:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"    
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/status,message
    
  • 8. Send a GET request to "/api/v1/predictions/analysis" to retrieve the predictions report.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2020-02-28 14:32:20.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/analysis
    
Make predictions using websites
  • 1. Send a POST request to "/api/v1/predictions/record" to retrieve a new record number.
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2019-12-11 23:21:00.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 https://your_dedicated_host/api/v1/targets/record
    
  • 2. Send a PUT request to "/api/v1/predictions/localfile" with the header tag "Content: Website:" that specifies the URL of a website that contains raw data. When a PUT request is sent to "/api/v1/predictions/localfile" with the header tag "Content: Website:" the content of a website specified by its URL is uploaded into the database.
    Step #1
    http://www.example.com/
    
    Step #2
    echo -n 'http://www.example.com/' | base64
    
    Step #3
    -H "Content: Website:aHR0cDovL3d3dy5leGFtcGxlLmNvbS8="
    
    Step #4
    curl -X PUT -H "Host: www.deepsentry.com"
                 -H "Date: 2020-02-28 14:32:20.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 -H "Record: 1234"
                 -H "Content: Website:aHR0cDovL3d3dy5leGFtcGxlLmNvbS8=" 
                 https://your_dedicated_host/api/v1/predictions/localfile
    
  • 3. Check the POST request to determine whether or not it has completed, send a GET request to "/api/v1/predictions/active". If the POST request is still running, the value of active will be "true".
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-12-11 23:21:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/active
    
  • 4. Check the POST request to determine whether or not it completed successfully, send a GET aggregation request to "/api/v1/targets/status" and "api/v1/targets/message". If the POST request completed successfully, the value of status will be "passed" and the value of "message" will be "empty". If the POST request did not finish successfully, the value of status will be "failed" and the value of message will be the results of what exactly happened when executing the POST request.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-12-11 23:21:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"    
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/status,message
    
  • 5. Send a POST request to "/api/v1/predictions/analysis".
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2020-02-28 14:32:20.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 -H "Record: 1234"
                 https://your_dedicated_host/api/v1/predictions/analysis
    
  • 6. Check the POST request to determine whether or not it has completed, send a GET request to "/api/v1/predictions/active". If the POST request is still running, the value of active will be "true".
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-12-11 23:21:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/active
    
  • 7. Check the POST request to determine whether or not it completed successfully, send a GET aggregation request to "/api/v1/predictions/status" and "api/v1/predictions/message". If the POST request completed successfully, the value of status will be "passed" and the value of "message" will be "empty". If the POST request did not finish successfully, the value of status will be "failed" and the value of message will be the results of what exactly happened when executing the POST request.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-12-11 23:21:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"    
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/status,message
    
  • 8. Send a GET request to "/api/v1/predictions/analysis" to retrieve the predictions report.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2020-02-28 14:32:20.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/analysis
    
Get a predictions report
  • Predictive security analytics are created when a new source of machine data assigned to an endpoint is uploaded to "/api/v1/predictions/localfile" and a security report is requested at "/api/v1/predictions/analysis". Predictions are compared against training to determine whether or not the new source of machine data that was uploaded to "/api/v1/predictions/localfile" has hacker activity.
  • When the POST operation for a security report is completed and there were no errors, the analysis is available at "/api/v1/predictions/analysis". Subsequent requests sent for additional reports will overwrite the analysis at "/api/v1/predictions/analysis".
  • 1. Send a POST request to "/api/v1/predictions/analysis".
    curl -X POST -H "Host: www.deepsentry.com"
                 -H "Date: 2020-02-28 14:32:20.000001-07"
                 -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                 -H "Record: 1234"
                 https://your_dedicated_host/api/v1/predictions/analysis
    
  • 2. Check the POST request to determine whether or not it has completed, send a GET request to "/api/v1/predictions/active". If the POST request is still running, the value of active will be "true".
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-12-11 23:21:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/active
    
  • 3. Check the POST request to determine whether or not it completed successfully, send a GET aggregation request to "/api/v1/predictions/status" and "api/v1/predictions/message". If the POST request completed successfully, the value of status will be "passed" and the value of "message" will be "empty". If the POST request did not finish successfully, the value of status will be "failed" and the value of message will be the results of what exactly happened when executing the POST request.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2019-12-11 23:21:00.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"    
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/status,message
    
  • 4. Send a GET request to "/api/v1/predictions/analysis" to retrieve the predictions report.
    curl -X GET -H "Host: www.deepsentry.com"
                -H "Date: 2020-02-28 14:32:20.000001-07"
                -H "Authorization: Subnet255:e3075055-a69b-4f2c-a488-b157b6eebb80"
                -H "Record: 1234"
                https://your_dedicated_host/api/v1/predictions/analysis
    
Endpoint Registration
Attack Vector Targeting
  • Each source of machine data for an endpoint starts with a POST request to "/api/v1/targets/record" to retrieve a new record number. Define the new record to use the right alias and right key for the endpoint. Send a POST request to "/api/v1/targets/localfile" to upload the machine data. The machine data can be modified through a POST request to "/api/v1/targets/blacklist". Additional sources of machine data for an endpoint can be included by sending a POST request to "/api/v1/targets/record" to retrieve a new record number then modifying the new record to use the same value for the "alias" of the endpoint and the same value for the "key" of the endpoint.
  • When a POST request is sent to "/api/v1/targets/training" the resource ingests all of the sources of machine data assigned to the endpoint to create a single, aggregate of all sources of machine data. Training contains absolute standards for determining normality, baseline measurements and threshold measurements about the environment of an endpoint and the history of an endpoint's normal activity. While the POST operation is still in progress the parameter "active" is set to "true" and the parameter "status" is set to "pending" and the parameter "message" is set to "empty". If a error occurs the parameter "active" is set to "false" and the parameter "status" is set to "failed" and the parameter "message" will contain STDERR and STDOUT encoded in base64. When the POST operation is completed the parameter "active" is set to "false" and the parameter "status" is set to "passed" and the parameter "message" will contain STDOUT encoded in base64.
  • A subsequent POST request sent to "/api/v1/targets/training" overwrites the old training for the endpoint. So you will have to add/remove sources of machine data assigned to an endpoint then run "/api/v1/targets/training" again.
Predictive Security Analytics
  • Predictive security analytics are created when a new source of machine data assigned to an endpoint is uploaded to "/api/v1/predictions/localfile" and a security report is requested at "/api/v1/predictions/analysis". Predictions are compared against training to determine whether or not the new source of machine data that was uploaded to "/api/v1/predictions/localfile" has hacker activity.
  • While the POST operation is still in progress the parameter "active" is set to "true" and the parameter "status" is set to "pending" and the parameter "message" is set to "empty". If a error occurs the parameter "active" is set to "false" and the parameter "status" is set to "failed" and the parameter "message" will contain STDERR and STDOUT encoded in base64. When the POST operation is completed the parameter "active" is set to "false" and the parameter "status" is set to "passed" and the parameter "message" will contain STDOUT encoded in base64.
  • When the POST operation for a security report is completed and there were no errors, the analysis is available at "/api/v1/predictions/analysis". Subsequent requests sent for additional reports will overwrite the analysis at "/api/v1/predictions/analysis".
Logging