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 /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

  // Other settings
  "authentication": { // authentication details as documented in https://docs.escape.tech/testing/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/testing/ci-cd/configuration-override and https://docs.escape.tech/testing/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