Skip to main content

Public API Reference

API base URL

Escape's REST public API can be reached at https://public.escape.tech

Authentication

API key

Pass your API via the Authorization header. You can find your API key in your Escape settings.

Basic example

export APPLICATION_ID=<YOUR APPLICATION ID>
export API_KEY=<YOUR API KEY>

curl -X POST \
-H "Authorization: Key $API_KEY" \
https://public.escape.tech/applications/$APPLICATION_ID/start-scan

GET /organization/:organizationId/applications

Retrieve the list of applications bound to an organization

Request parameters

organizationId

The ID of the organization on Escape. It can be found on the organization section

Example response

[
{
"name": "Gontoz",
"id": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"url": "https://gontoz.escape.tech/graphql",
"createdAt": "2022-03-07T11:44:20.968Z",
"hasCI": true,
"cron": "0 3 * * *",
"scans": [
{
"id": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"status": "SUCCESS",
"createdAt": "2022-12-05T14:32:32.968Z",
"alertCounts": {
"HIGH": 10,
"MEDIUM": 7,
"LOW": 9,
"INFO": 3
},
"commitHash": "11fb1c9f83f371ca9c1e353ef9f16bc36934ab83",
"betterThan": 0.7205479452054795
},
{
"id": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"status": "SUCCESS",
"createdAt": "2022-10-24T09:02:05.662Z",
"alertCounts": {
"HIGH": 1,
"MEDIUM": 8,
"LOW": 9,
"INFO": 2
},
"commitHash": "11fb1c9f83f371ca9c1e353ef9f16bc36934ab83",
"betterThan": 0.7205479452054795
],
"lastSuccessfulScan": {
"id": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"createdAt": "2022-12-05T14:32:32.968Z",
"alertCounts": {
"HIGH": 10,
"MEDIUM": 7,
"LOW": 9,
"INFO": 3
},
"commitHash": "11fb1c9f83f371ca9c1e353ef9f16bc36934ab83",
"betterThan": 0.7205479452054795
}
}
]

GET /organization/:organizationId/applications/search

Retrieve a paginated list of applications based on some search criteria

Request parameters

organizationId

The ID of the organization on Escape. It can be found on the organization section

Query parameters

The search query to filter applications by name or url.

cursor

The cursor to paginate the results.

Example response

{
"cursor": "eyJ2Ij...",
"data": [
{
"name": "Gontoz",
"id": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"url": "https://gontoz.escape.tech/graphql",
"createdAt": "2022-03-07T11:44:20.968Z",
"hasCI": true,
"cron": "0 3 * * *"
}
]
}

GET /v1/organization/:organizationId/services

Retrieve the list of services bound to an organization

Request parameters

organizationId

The ID of the organization on Escape. It can be found on the organization section

Example response

[
{
"id": "99092d10-69a2-45b3-80f8-d35b04ede64e",
"url": "https://gontoz.escape.tech/graphql",
"cloudProvider": "AWS",
"wafProvider": "AWS_ELASTIC_LOAD_BALANCER",
"authTechnology": "AUTH0",
"type": "GRAPHQL",
"createdAt": "2024-09-03T10:24:29.412Z",
"lastSeenAt": "2024-09-03T10:24:29.412Z",
"tags": [
{
"id": "497639c6-70b7-443f-bb9f-2639c01b711b",
"name": "tag",
"color": "a271b5"
}
],
"domain": {
"id": "escape.tech",
"faviconUrl": ""
},
"applicationsCount": 0,
"softwareType": "FIRST_PARTY",
"framework": "apollo",
"ipAddresses": ["192.168.0.1", "192.168.0.2"],
"countryCodes": [],
"endpoints": [
{
"id": "770235b7-36f6-44c9-b150-98c31cf4ce47",
"operation": "query",
"name": "me"
}
]
}
]

POST /v1/organization/:organizationId/domains

Set the domains for an organization, will fully replace the existing domains and preserve existing ones (they have to be included).

Request parameters

organizationId

The ID of the organization on Escape. It can be found on the organization section

Example request

{
"domains": ["test.com", "example.com"] // the list can be empty if you want to reset all domains
}

Example response

{
"message": "Domains set successfully"
}

GET /scans/:scanId

Retrieve a specific scan and its results

Request parameters

scanId

The ID of the scan on Escape.

Example response

{
"id": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"status": "SUCCESS",
"createdAt": "2022-12-05T14:32:32.968Z",
"score": 0.009737885064620144,
"completionRatio": 1,
"commitHash": "11fb1c9f83f371ca9c1e353ef9f16bc36934ab83",
"application": {
"id": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"createdAt": "2022-03-07T11:44:20.968Z",
"engine": "Ariadne",
"manuallySetEngine": null,
"name": "Gontoz",
"updatedAt": "2022-12-15T14:42:23.275Z",
"activeIntrospection": {
"id": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"applicationId": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"createdAt": "2022-08-05T07:42:54.562Z"
}
},
"configuration": {
"applicationId": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"content": {
"auth": {
"schema1": {
"tech": "manual"
}
},
"users": {
"user0": {
"auth": "schema1",
"headers": {
"hello": "world"
}
}
},
"checks": {},
"scan": {
"read_only": false
}
},
"createdAt": "2022-08-08T10:32:37.140Z",
"isAuthenticationValid": true,
"isConfigurationValid": true,
"readWrite": true,
"updatedAt": "2022-08-08T10:32:37.140Z",
"applicationUsers": [
{
"headerName": "hello",
"headerValue": "world",
"name": "user0"
}
]
},
"alerts": [
{
"id": "99679d55-b4f5-4edb-b558-4c1cefda870c",
"status": "NO_STATUS",
"severity": "HIGH",
"tags": [],
"securityTestUid": "injection/xxe"
},
...,
]
}

POST /applications/:applicationId/start-scan

Start a new scan for the given application.

Request parameters

applicationId

The ID of the application on Escape.

Request body parameters

You can pass additional parameters via the request body.

configurationOverride string

See the configuration override section.

commitHash string

See the commit identification section.

introspection string

The stringified JSON introspection. See the introspection update section.

POST /applications/:applicationId/upload-introspection

Upload an introspection response or schema on Escape for a given application.

Request parameters

applicationId

The ID of the application on Escape.

Request body parameters

Providing an introspection response within the body is mandatory

introspectionResponse string

The stringified JSON introspection. See the introspection update section.

Example response

{
"id": "5d1b0249-a6fd-4d64-997a-99675ca6afac",
"applicationId": "5d1b0249-a6fd-4d64-997a-99675ca6afac"
}

POST /create-application

Programmatically create an application on Escape and start a scan.

Request body

The route expects a JSON body with the following fields:

{
// Application settings
"organizationId": "<organizationId>",
"name": "Application name",
"type": "GRAPHQL" | "REST",
"serverUrl": "<url>",

// Application schema, provide exactly one of the two fields
"schema": "<stringified schema>",
"schemaUrl": "<public schema url>",

// Scan settings
"readWrite": true | false, // false makes the scan safe for production

// Scheduling
"cron": "0 3 * * *", // Optional, cron expression to customize the scheduling
"disableScheduling": true | false, // Optional, disable scheduling, false by default

// Other settings
"authentication": { // authentication details as documented in https://docs.escape.tech/api-dast/authentication/#overall-structure-of-an-authentication-configuration
"presets": [
{
"type": "headers",
"users": [
{
"username": "user1",
"headers": {
"Authorization": "Bearer user1Token"
}
}
]
}
],
"validation": false
},
"fullConfiguration": { // full expert configuration as documented in https://docs.escape.tech/api-dast/ci-cd/configuration-override and https://docs.escape.tech/api-dast/advanced-usage/
// you can simply copy your expert configuration from a scan and use it here
// fullConfiguration and authentication are mutually exclusive
"scan": {
"profile": "default",
"blacklist": {},
"read_only": false
},
"client": {
"requests_per_minute": 300
},
"authentication": {
"users": [
{
"name": "public"
}
]
}
},
"labels": ["<label1>", "<label2>"], // Optional, labels to categorize the application
"repeaterId": "<repeaterId>" // Optional, if you want to use a repeater
}

If you are adding a GraphQL application with an open introspection endpoint, set schemaUrl to serverUrl.

Example:

{
"organizationId": "<uuid>",
"name": "Gontoz",
"type": "GRAPHQL",
"serverUrl": "https://gontoz.escape.tech/graphql",
"schemaUrl": "https://gontoz.escape.tech/graphql",
"readWrite": true
}

Response body

{
"id": "<application uuid>",
"name": "Application name",
"scans": {
"edges": [
{
"node": {
// A scan is created and started automatically
"id": "<scan uuid>"
}
}
]
},
"href": "https://app.escape.tech/scan/<scan uuid>"
}

OpenAPI Specifcation

openapi: 3.0.3
info:
title: Escape's Public API
version: 1.0.0
servers:
- url: https://public.escape.tech
paths:
/organization/{organizationId}/applications:
get:
parameters:
- name: organizationId
in: path
required: true
description: The ID of the organization on Escape.
schema:
type: string
responses:
200:
description: A list of applications bound to an organization.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Application"

/scans/{scanId}:
get:
parameters:
- name: scanId
in: path
required: true
description: The ID of the scan on Escape.
schema:
type: string
responses:
200:
description: Details of a specific scan.
content:
application/json:
schema:
$ref: "#/components/schemas/Scan"

/application/{applicationId}/start-scan:
post:
parameters:
- name: applicationId
in: path
required: true
description: The ID of the application on Escape.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
configurationOverride:
type: string
description: See the configuration override section.
commitHash:
type: string
description: See the commit identification section.
introspection:
type: string
description: The stringified JSON introspection. See the introspection update section.
responses:
200:
description: OK
content:
application/json:
schema:
type: object

/applications/{applicationId}/upload-introspection:
post:
parameters:
- name: applicationId
in: path
required: true
description: The ID of the application on Escape.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
introspectionResponse:
type: string
description: The stringified JSON introspection. See the introspection update section.
required:
- introspectionResponse
responses:
200:
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/IntrospectionResponse"

components:
schemas:
Application:
type: object
properties:
name:
type: string
id:
type: string
url:
type: string
createdAt:
type: string
hasCI:
type: boolean
cron:
type: string
scans:
type: array
items:
$ref: "#/components/schemas/Scan"
lastSuccessfulScan:
$ref: "#/components/schemas/Scan"

Scan:
type: object
properties:
id:
type: string
status:
type: string
createdAt:
type: string
score:
type: number
completionRatio:
type: number
commitHash:
type: string
application:
$ref: "#/components/schemas/Application"
configuration:
type: object
alerts:
type: array
items:
type: object

IntrospectionResponse:
type: object
properties:
id:
type: string
applicationId:
type: string