sqlmap can be controlled through an HTTP REST API by using sqlmapapi.py. The API accepts and returns JSON. This is useful when sqlmap has to be integrated into another tool, service, user interface, automation pipeline or commercial product.

The API server manages scan tasks. A client creates a task, sets sqlmap options, starts a scan, then retrieves status, logs, data and output files.

Note

Use sqlmap and its API only against targets you are authorized to test.

Start the REST API server with -s or --server:

python sqlmapapi.py -s --username sqlmap --password sqlmap

By default, the server listens on 127.0.0.1:8775.

Common server options:

python sqlmapapi.py -s \
  -H 127.0.0.1 \
  -p 8775 \
  --username sqlmap \
  --password sqlmap

Available API-specific command line options:

When using sqlmapapi.py in server or client mode, both --username and --password are required.

The API uses HTTP Basic authentication.

With curl, use -u:

curl -u sqlmap:sqlmap http://127.0.0.1:8775/version

For the examples below, it is convenient to define the API address and credentials first:

API="http://127.0.0.1:8775"
AUTH="sqlmap:sqlmap"

Then requests can be written as:

curl -u "$AUTH" "$API/version"

A typical API workflow is:

1. Start the API server.
2. Create a new task.
3. Start a scan by sending sqlmap options as JSON.
4. Poll the scan status.
5. Retrieve logs and data.
6. Stop, kill or delete the task if needed.

Example:

API="http://127.0.0.1:8775"
AUTH="sqlmap:sqlmap"

taskid=$(curl -s -u "$AUTH" "$API/task/new" | grep -o '[a-f0-9]\{16\}')

curl -u "$AUTH" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"url":"https://sekumart.sekuripy.hr/product.php?id=1"}' \
  "$API/scan/$taskid/start"

curl -u "$AUTH" "$API/scan/$taskid/status"
curl -u "$AUTH" "$API/scan/$taskid/log"
curl -u "$AUTH" "$API/scan/$taskid/data"

The JSON options used with /scan/<taskid>/start correspond to sqlmap's internal option names. For example, command line option --url is represented as JSON key url.

Most API responses are JSON objects containing a success field.

Successful response example:

{
  "success": true,
  "taskid": "1a2b3c4d5e6f7890"
}

Error response example:

{
  "success": false,
  "message": "Invalid task ID"
}

Some API-level errors are returned with HTTP status 200 and success: false, matching the current implementation behavior. HTTP status codes such as 401, 404, 405 and 500 can also be returned for authentication errors, missing routes, invalid methods and server errors.

Returns the sqlmap version and the API contract version exposed by the server.

api_version is the MAJOR version of the REST API contract (semantic versioning), independent of the sqlmap version. Only the major is exposed at runtime because only a major bump breaks clients; use it to check compatibility (e.g. api_version == 2).

Example:

curl -u "$AUTH" "$API/version"

Response:

{
  "success": true,
  "version": "1.10.7.176#dev",
  "api_version": 2
}

A task represents one sqlmap scan context. Options are stored per task, and scans are started against a task ID.

Creates a new task.

Example:

curl -u "$AUTH" "$API/task/new"

Response:

{
  "success": true,
  "taskid": "1a2b3c4d5e6f7890"
}

Save the task ID for later requests:

taskid=$(curl -s -u "$AUTH" "$API/task/new" | grep -o '[a-f0-9]\{16\}')
echo "$taskid"

Deletes an existing task and kills its scan process if it is still running.

Example:

curl -u "$AUTH" "$API/task/$taskid/delete"

Response:

{
  "success": true
}

Options can be set separately before starting a scan, or passed directly to /scan/<taskid>/start.

Lists current task options.

Example:

curl -u "$AUTH" "$API/option/$taskid/list"

Response excerpt:

{
  "success": true,
  "options": {
    "url": null,
    "data": null,
    "cookie": null,
    "level": 1,
    "risk": 1,
    "batch": true
  }
}

Retrieves selected option values.

Example:

curl -u "$AUTH" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '["url", "level", "risk"]' \
  "$API/option/$taskid/get"

Response:

{
  "success": true,
  "options": {
    "url": null,
    "level": 1,
    "risk": 1
  }
}

Unknown option example:

{
  "success": false,
  "message": "Unknown option 'doesNotExist'"
}

Sets one or more task options.

Example:

curl -u "$AUTH" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"url":"https://sekumart.sekuripy.hr/product.php?id=1","level":2,"risk":1}' \
  "$API/option/$taskid/set"

Response:

{
  "success": true
}

Unsupported, read-only and unknown options are rejected. An unknown (e.g. misspelled) option is rejected with an Unknown option ... message:

{
  "success": false,
  "message": "Unknown option 'doesNotExist'"
}

A handful of interactive/CLI-only options cannot be driven over the API and are rejected as unsupported (Unsupported option '<name>'): sqlShell, wizard, evalCode, alert and reportJson.

Read-only API-controlled options include api, taskid and database.

Starts a scan for an existing task. The request body contains sqlmap options in JSON form.

Example:

curl -u "$AUTH" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"url":"https://sekumart.sekuripy.hr/product.php?id=1"}' \
  "$API/scan/$taskid/start"

Response:

{
  "success": true,
  "engineid": 12345
}

You can also pass more sqlmap options:

curl -u "$AUTH" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"url":"https://sekumart.sekuripy.hr/product.php?id=1","batch":true,"level":2,"risk":1,"technique":"BEUSTQ"}' \
  "$API/scan/$taskid/start"

If a scan is already running for that task, the API returns:

{
  "success": false,
  "message": "Scan already running"
}

Returns scan status.

Example:

curl -u "$AUTH" "$API/scan/$taskid/status"

Response while running:

{
  "success": true,
  "status": "running",
  "returncode": null
}

Possible status values are:

Stops a running scan by terminating the scan process.

Example:

curl -u "$AUTH" "$API/scan/$taskid/stop"

Response:

{
  "success": true
}

Kills a running scan process.

Example:

curl -u "$AUTH" "$API/scan/$taskid/kill"

Response:

{
  "success": true
}

Retrieves all log messages for a task.

Example:

curl -u "$AUTH" "$API/scan/$taskid/log"

Response:

{
  "success": true,
  "log": [
    {
      "time": "12:34:56",
      "level": "INFO",
      "message": "testing connection to the target URL"
    }
  ]
}

Retrieves a subset of log messages by numeric row range.

Example:

curl -u "$AUTH" "$API/scan/$taskid/log/1/20"

Response:

{
  "success": true,
  "log": [
    {
      "time": "12:34:56",
      "level": "INFO",
      "message": "testing connection to the target URL"
    }
  ]
}

Invalid range example:

{
  "success": false,
  "message": "Invalid start or end value, must be digits"
}

Retrieves structured scan data and errors.

Example:

curl -u "$AUTH" "$API/scan/$taskid/data"

Response:

{
  "success": true,
  "data": [
    {
      "status": 1,
      "type": 2,
      "type_name": "DBMS_FINGERPRINT",
      "value": "back-end DBMS: MySQL >= 5.1"
    },
    {
      "status": 1,
      "type": 4,
      "type_name": "CURRENT_USER",
      "value": "root@%"
    }
  ],
  "error": []
}

Each item has a numeric type, its readable type_name (e.g. TARGET, TECHNIQUES, DBMS_FINGERPRINT, BANNER, CURRENT_USER, DBS, TABLES, COLUMNS, DUMP_TABLE), a status (0 = in progress, 1 = complete) and a value. type_name is null for any unmapped type.

The shape of value depends on the type (string, number, boolean, array, object or null). Internal detection/plumbing fields are not exposed and SQL identifiers are unquoted. Notable shapes:

• TECHNIQUES — a list of injection points; each point's data is a list of techniques, each named via a technique field:

  {
    "place": "GET", "parameter": "id", "dbms": "MySQL", "dbms_version": [">= 5.1"], "os": null, "notes": [],
    "data": [
      {"technique": "boolean-based blind", "title": "AND boolean-based blind - WHERE or HAVING clause", "payload": "id=1 AND 7997=7997", "vector": "AND [INFERENCE]", "comment": ""}
    ]
  }

• DUMP_TABLE — {"db": ..., "table": ..., "count": N, "columns": {"<column>": [values, ...]}}. A database NULL value is reported as JSON null.

Downloads a file from sqlmap's output directory. The response contains Base64-encoded file content.

Example:

curl -u "$AUTH" "$API/download/$taskid/sekumart.sekuripy.hr/log"

Response:

{
  "success": true,
  "file": "YmFzZTY0LWVuY29kZWQgZmlsZSBjb250ZW50"
}

The filename part can refer to a nested file path under the target output directory. Depending on the client, slashes in nested file names may need to be URL-encoded.

If the file does not exist:

{
  "success": false,
  "message": "File does not exist"
}

The server prints an admin token when started:

Admin (secret) token: 0123456789abcdef0123456789abcdef

Admin endpoints can be called with or without the token. Without the admin token, list and flush operations are limited to tasks created from the same remote address. With the admin token, they apply to the whole task pool.

Lists visible tasks.

Example:

curl -u "$AUTH" "$API/admin/list"

Response:

{
  "success": true,
  "tasks": {
    "1a2b3c4d5e6f7890": "running"
  },
  "tasks_num": 1
}

Lists all tasks when a valid admin token is supplied.

Example:

ADMIN_TOKEN="0123456789abcdef0123456789abcdef"
curl -u "$AUTH" "$API/admin/$ADMIN_TOKEN/list"

Response:

{
  "success": true,
  "tasks": {
    "1a2b3c4d5e6f7890": "running"
  },
  "tasks_num": 1
}

Deletes visible tasks and kills their scan processes.

Example:

curl -u "$AUTH" "$API/admin/flush"

Response:

{
  "success": true
}

Deletes all tasks when a valid admin token is supplied.

Example:

curl -u "$AUTH" "$API/admin/$ADMIN_TOKEN/flush"

Response:

{
  "success": true
}

sqlmap also includes an interactive API client:

python sqlmapapi.py -c --username sqlmap --password sqlmap

To connect to a non-default server address:

python sqlmapapi.py -c \
  -H 127.0.0.1 \
  -p 8775 \
  --username sqlmap \
  --password sqlmap

Useful client commands include:

Example:

api> new -u "https://sekumart.sekuripy.hr/product.php?id=1"
api (1a2b3c4d5e6f7890)> status
api (1a2b3c4d5e6f7890)> log
api (1a2b3c4d5e6f7890)> data

The REST API can also be described with the OpenAPI specification file:

sqlmapapi.yaml

That file can be used by API documentation tools, client generators and API testing tools.

Validate the specification with Redocly:

npm install -g @redocly/cli
redocly lint sqlmapapi.yaml

Postman can import an OpenAPI specification directly. Import sqlmapapi.yaml, set Basic authentication credentials, and use the generated requests.

A standalone Postman collection can also be generated from the OpenAPI file:

npm install -g openapi-to-postmanv2

openapi2postmanv2 \
  -s sqlmapapi.yaml \
  -o sqlmapapi.postman_collection.json \
  -p \
  -O folderStrategy=Tags,includeAuthInfoInExample=true

The OpenAPI file should be treated as the canonical machine-readable API description. A generated Postman collection is only a convenience artifact.

The REST API is intended to be used by trusted clients and trusted integrations.

Important notes for integrators:

• Do not expose the API server directly to untrusted networks.
• Use strong Basic authentication credentials.
• Bind the API server to 127.0.0.1 unless remote access is required.
• Place the API behind a properly configured reverse proxy if TLS, access control or network policy enforcement is needed.
• Treat task IDs as sensitive identifiers. Any authenticated client that knows a task ID can operate on that task.
• The API is not designed as a multi-tenant service boundary.
• Some mutating operations use GET requests for historical compatibility. Avoid placing the API behind caching layers that could replay or cache those requests.
• Scan options are validated by the API before being accepted. Unsupported, read-only and unknown options are rejected.
• The scan engine runs in a separate process. Long-running scans should be monitored through /scan/<taskid>/status, /scan/<taskid>/log and /scan/<taskid>/data.

API="http://127.0.0.1:8775"
AUTH="sqlmap:sqlmap"

# Create a task
taskid=$(curl -s -u "$AUTH" "$API/task/new" | grep -o '[a-f0-9]\{16\}')
echo "Task ID: $taskid"

# Start a scan
curl -u "$AUTH" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"url":"https://sekumart.sekuripy.hr/product.php?id=1","batch":true}' \
  "$API/scan/$taskid/start"

# Poll status
curl -u "$AUTH" "$API/scan/$taskid/status"

# Retrieve logs
curl -u "$AUTH" "$API/scan/$taskid/log"

# Retrieve data
curl -u "$AUTH" "$API/scan/$taskid/data"

# Delete task
curl -u "$AUTH" "$API/task/$taskid/delete"