Skip to content

REST API

Jump to bottom
Miroslav Stampar edited this page Jun 11, 2026 · 2 revisions

REST API

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.

Starting the API server

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:

Option Description
-s, --server Run as a REST-JSON API server
-c, --client Run as a REST-JSON API client
-H, --host Host of the REST API server
-p, --port Port of the REST API server
--adapter Server adapter to use
--database IPC database file path
--username Basic authentication username
--password Basic authentication password

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

Authentication

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"

Basic workflow

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":"http://testasp.vulnweb.com/showforum.asp?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.

Response format

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.

Version

GET /version

Returns the sqlmap version exposed by the API server.

Example:

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

Response:

{
  "success": true,
  "version": "1.9.12.1#dev"
}

Task management

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

GET /task/new

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"

GET /task/<taskid>/delete

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

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

GET /option/<taskid>/list

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

POST /option/<taskid>/get

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'"
}

POST /option/<taskid>/set

Sets one or more task options.

Example:

curl -u "$AUTH" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"url":"http://testasp.vulnweb.com/showforum.asp?id=1","level":2,"risk":1}' \
  "$API/option/$taskid/set"

Response:

{
  "success": true
}

Unsupported, read-only and unknown options are rejected:

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

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

Scans

POST /scan/<taskid>/start

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":"http://testasp.vulnweb.com/showforum.asp?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":"http://testasp.vulnweb.com/showforum.asp?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"
}

GET /scan/<taskid>/status

Returns scan status.

Example:

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

Response while running:

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

Possible status values are:

Status Description
not running The task exists, but no scan process has been started
running The scan process is still running
terminated The scan process has finished

GET /scan/<taskid>/stop

Stops a running scan by terminating the scan process.

Example:

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

Response:

{
  "success": true
}

GET /scan/<taskid>/kill

Kills a running scan process.

Example:

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

Response:

{
  "success": true
}

Logs and data

GET /scan/<taskid>/log

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"
    }
  ]
}

GET /scan/<taskid>/log/<start>/<end>

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"
}

GET /scan/<taskid>/data

Retrieves structured scan data and errors.

Example:

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

Response:

{
  "success": true,
  "data": [
    {
      "status": 1,
      "type": 0,
      "value": "example output"
    }
  ],
  "error": []
}

The shape of value depends on the scan result type. It can be a string, number, boolean, array, object or null.

Downloading output files

GET /download/<taskid>/<target>/<filename>

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

Example:

curl -u "$AUTH" "$API/download/$taskid/testasp.vulnweb.com/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"
}

Admin operations

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.

GET /admin/list

Lists visible tasks.

Example:

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

Response:

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

GET /admin/<token>/list

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
}

GET /admin/flush

Deletes visible tasks and kills their scan processes.

Example:

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

Response:

{
  "success": true
}

GET /admin/<token>/flush

Deletes all tasks when a valid admin token is supplied.

Example:

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

Response:

{
  "success": true
}

Interactive API client

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:

Command Description
new ARGS Start a new scan task with sqlmap command line arguments
use TASKID Switch current client context to an existing task
data Retrieve data for the current task
log Retrieve logs for the current task
status Retrieve status for the current task
option OPTION Retrieve an option value for the current task
options Retrieve all options for the current task
stop Stop the current task
kill Kill the current task
list Display visible tasks
flush Flush visible tasks
version Fetch server version
exit Exit the client

Example:

api> new -u "http://testasp.vulnweb.com/showforum.asp?id=1"
api (1a2b3c4d5e6f7890)> status
api (1a2b3c4d5e6f7890)> log
api (1a2b3c4d5e6f7890)> data

OpenAPI specification

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

Using with Postman

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.

Integration notes

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.

Minimal end-to-end example

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":"http://testasp.vulnweb.com/showforum.asp?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"

Contents

User's manual

  • Introduction - Introductory to sqlmap
  • Techniques - SQLi techniques supported by sqlmap
  • Features - Brief list of supported features
  • Download and update - Keep your copy up-to-date
  • Dependencies - Information about used third-party libraries and tools
  • History - History from 2006 to 2026
  • Usage - Exhaustive breakdown of all options and switches together with examples
  • REST API - Using sqlmapapi.py for programmatic integration and automation
  • License - Copyright information

Miscellaneous

  • FAQ - Frequently Asked Questions
  • Presentations - Materials from sqlmap team presented at conferences
  • Screenshots - Collection of screenshots demonstrating some of features
  • Third party libraries - Detailed information about third-party libraries and tools used by sqlmap

Clone this wiki locally