Proxy API

Dev Proxy comes with a web API that allows you to interact with the proxy programmatically. The API is available on the IP address and port specified in the proxy settings.

Dev Proxy generates a unique token for each running instance and stores it in a file that's accessible only to the user who started the instance. Get the token using devproxy status or devproxy api token. When the CI environment variable is set, use devproxy api token because Dev Proxy omits the token from status and startup output.

To use a known token instead of a generated one, for example when another tool starts Dev Proxy and calls its API, set the DEV_PROXY_API_TOKEN environment variable before you start Dev Proxy or pass it using the --env option. The value must be at least 32 characters long, not counting trailing = padding, and can contain only ASCII letters, digits, and the characters -, ., _, ~, +, and /, optionally followed by = padding. Dev Proxy trims surrounding whitespace. If the value isn't valid, Dev Proxy doesn't start and exits with an error. Dev Proxy still stores the token, so devproxy status, devproxy api token, and devproxy stop keep working.

Include the token in the Authorization header:

Authorization: Bearer <token>

Requests without a valid token return 401 Unauthorized. Browser requests must also come from an origin listed in the apiAllowedOrigins setting. Other origins return 403 Forbidden.

Operations

The following list shows available API operations.

GET /proxy

Returns an instance of ProxyInfo with information about the currently running Dev Proxy instance.

Example: Get information about the currently running Dev Proxy instance

Request:

GET http://localhost:8897/proxy
Authorization: Bearer <token>

Response:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

POST /proxy

Controls the currently running Dev Proxy instance. To start and stop recording from a script or CI pipeline, see Record from scripts and CI.

Example: start recording

Request:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": true
}

Response:

200 OK

{
  "recording": true,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

Example: stop recording

Request:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": false
}

Response:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

Stop recording and generate reports

Stopping recording does more than stop capturing requests. When you send {"recording": false} while Dev Proxy is recording, Dev Proxy passes the recorded requests to all enabled plugins, in the order they're listed in the configuration file. This is the same as pressing s in the console where Dev Proxy is running. During this step:

• Reporting plugins analyze the recorded requests and produce reports.
• Reporters convert the reports to files. Each reporter writes one file for each report, named <plugin>_<reporter>.<extension>, for example, ExecutionSummaryPlugin_MarkdownReporter.md. <plugin> is the name of the plugin instance that produced the report, and <reporter> is the name of the reporter instance. If a file with that name already exists, the reporter appends a timestamp, for example, ExecutionSummaryPlugin_MarkdownReporter_20261105114500.md.
• Generator plugins, like the OpenApiSpecGeneratorPlugin, write the files they generate.

Dev Proxy writes these files to its current working directory, which is the directory from which you started Dev Proxy.

The API responds after all plugins finish processing the recorded requests. Depending on the plugins you use, for example, plugins that call a language model, this step can take a while, so make sure that your HTTP client doesn't time out too early. When the response arrives, the report files are written to disk.

Dev Proxy also logs the progress of processing the recorded requests:

If Dev Proxy isn't recording when you send {"recording": false}, Dev Proxy doesn't process any requests, doesn't write any files, and doesn't log DONE.

For a complete script that starts Dev Proxy, controls recording through the API, and waits for Dev Proxy to finish, see Use Dev Proxy in CI/CD scenarios.

POST /proxy/jwtToken

Generates a JSON Web Token (JWT).

Request:

POST http://localhost:8897/proxy/jwtToken
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Dev Proxy",
  "audiences": [
    "https://myserver.com"
  ],
  "issuer": "dev-proxy",
  "roles": [
    "admin"
  ],
  "scopes": [
    "Post.Read",
    "Post.Write"
  ],
  "claims": {
    "claim1": "value",
    "claim2": "value"
  },
  "validFor": 60
}

Response:

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IkRldiBQcm94eSIsInN1YiI6IkRldiBQcm94eSIsImp0aSI6IjkyZjM5YzciLCJzY3AiOlsiUG9zdC5SZWFkIiwiUG9zdC5Xcml0ZSJdLCJyb2xlcyI6ImFkbWluIiwiY2xhaW0xIjoidmFsdWUiLCJjbGFpbTIiOiJ2YWx1ZSIsImF1ZCI6Imh0dHBzOi8vbXlzZXJ2ZXIuY29tIiwibmJmIjoxNzI3MTk4MjgyLCJleHAiOjE3MjcyMDE4ODIsImlhdCI6MTcyNzE5ODI4MiwiaXNzIjoiZGV2LXByb3h5In0.E_Gj9E58OrAh9uHgc-TW8DYfq8YHFrhaUTpKA4yXEIg"
}

GET /proxy/logs

Returns the Dev Proxy log output. Equivalent of the logs command. This endpoint is available only when Dev Proxy runs in detached mode. Otherwise, the API returns 404 Not Found.

The since parameter filters log lines by their full date and time, both when returning log lines and when streaming them. Dev Proxy filters each request by the time it started, so a request that started before the specified time isn't returned, even if it finished later.

By default, the API returns the log lines as plain text. To get a JSON array of log entries, set the Accept header to application/json. To stream log lines as server-sent events, set the Accept header to text/event-stream or set follow to true.

Request:

GET http://localhost:8897/proxy/logs?lines=10
Authorization: Bearer <token>

Response:

200 OK
content-type: text/plain

[last 10 lines of the Dev Proxy log]

POST /proxy/mockrequest

Raises a mock request. Equivalent of pressing w in the console where Dev Proxy is running. The API responds after the mock request completes.

Request:

POST http://localhost:8897/proxy/mockrequest
Authorization: Bearer <token>

Response:

204 No Content

GET /proxy/rootCertificate?format=crt

Downloads the public key of the root certificate in PEM (Privacy Enhanced Mail) format that Dev Proxy uses to decrypt HTTPS requests. This API is helpful when you want to trust the root certificate on your host while running Dev Proxy in a Docker container.

At this moment, the only supported format is crt. The API returns a 400 Bad Request error if you specify any other format or don't specify a format at all.

Request:

GET http://localhost:8897/proxy/rootCertificate?format=crt
Authorization: Bearer <token>

Response:

content-type: application/x-x509-ca-cert

-----BEGIN CERTIFICATE-----
[base64 encoded certificate]
-----END CERTIFICATE-----

POST /proxy/stopproxy

Gracefully shuts down Dev Proxy. If Dev Proxy is recording, it stops recording and generates reports before it exits. The API responds immediately, before Dev Proxy finishes shutting down.

Request:

POST http://localhost:8897/proxy/stopproxy
Authorization: Bearer <token>

Response:

202 Accepted

Dev Proxy returns 202 Accepted as soon as it starts shutting down. The response doesn't mean that Dev Proxy has exited. During shutdown, Dev Proxy:

1. Stops accepting new proxy requests. If Dev Proxy is registered as the system proxy, it restores the previous system proxy settings. Dev Proxy waits up to five seconds for open connections to close, and then closes any remaining connections.
2. Stops recording, if recording is on, and runs the reporting plugins on the recorded requests, the same as when you stop recording yourself. When the plugins finish, Dev Proxy writes the reports and logs DONE.
3. Removes its instance information, so devproxy status and devproxy stop no longer list it.
4. Exits with exit code 0.

Dev Proxy doesn't remove its root certificate from the trusted certificate store on shutdown. To remove the certificate, use cert remove.

Shutdown typically takes a few seconds. It can take longer when reporting plugins process a large recording. After shutdown starts, the API is no longer reachable, so don't poll the API to check whether Dev Proxy has exited. Instead, use one of these options:

• Wait for the process ID (PID) that devproxy --detach prints to exit.
• Run devproxy status --pid <pid> until it returns exit code 1, which means that the instance is no longer running. For more information, see status.
• If you were recording, check the Dev Proxy log for the DONE message, which Dev Proxy logs after the reporting plugins finish. For an example, see Use Dev Proxy in CI/CD scenarios.

For example, to wait for a detached Dev Proxy instance to exit on Linux or macOS:

# DEVPROXY_PID is the PID that devproxy --detach printed
# TOKEN is the API token from devproxy api token
curl -X POST http://localhost:8897/proxy/stopproxy -H "Authorization: Bearer $TOKEN"

while ./devproxy/devproxy status --pid $DEVPROXY_PID > /dev/null 2>&1; do
  sleep 1
done

Avoid ending the Dev Proxy process forcefully, for example, by using kill -9. When you end the process this way, Dev Proxy doesn't flush the recording or restore system proxy settings. To stop Dev Proxy from the command line, use stop, which calls this API and waits up to 10 seconds for Dev Proxy to exit.

Models

ProxyInfo

Information about the currently running Dev Proxy instance.

JwtOptions

Options for generating a JWT token.

JwtInfo

Information about a JWT token.

See also

• Record from scripts and CI
• Use Dev Proxy in CI/CD scenarios