Capturing Traffic
Optic Capture helps create OpenAPI specifications and keep them up to date by examining the traffic to your API. Under the hood the following happens when running Capture,
- Your API is started via a command you provide.
- A reverse proxy is configured to send traffic to your API.
- A command or set of requests you provide is run, generating traffic to the proxy.
- Optic observes the traffic as it passes through the proxy.
- These observations can then be used to create or update your OpenAPI specification.

By default, all of this happens locally. Your capture details and API specification are not sent to Optic unless you explicitly opt into uploading your results to Optic Cloud.
You can view the capture CLI options with,
optic capture --help
Configuration
Capture is configured inside your optic.yml
file. Whether or not you already have an optic.yml
, getting started is easy via the optic capture init
command.
You can insert a configuration block into your optic.yml
(generating one if necessary) with a complete, commented configuration example:
optic capture init [./path/to/your/]openapi.yml
Configuration Reference
optic capture init
can also display a capture configuration example to stdout, making it a useful reference and source of truth for the Capture configuration options. For example, the following command will display the configuration block without making any changes to optic.yml
.
optic capture init --stdout openapi.yml
capture:
openapi.yml:
server:
# The command to run your server.
# Optional: If omitted, Optic assumes the server is running or started elsewhere.
command: your-server-command
# The url where your server can be reached once running.
# Required: Can be overridden with '--server-override'.
url: http://localhost:8080
# A readiness endpoint for Optic to validate before sending requests.
# Optional: If omitted, perform no readiness checking.
ready_endpoint: /
# The interval to check 'ready_endpoint', in ms.
# Optional: default: 1000
ready_interval: 1000
# The length of time in ms to wait for a successful ready check to occur.
# Optional: default: 10_000, 10 seconds
ready_timeout: 10_000
# At least one of 'requests.run' or 'requests.send' is required below.
requests:
# Run a command to generate traffic. Requests should be sent to the Optic proxy, the address of which is injected
# into 'run.command's env as OPTIC_PROXY or the value of 'run.proxy_variable', if set.
run:
# The command that will generate traffic to the Optic proxy. Globbing with '*' is supported.
# Required if specifying 'requests.run'.
command: your-test-command
# The name of the environment variable injected into the env of the command that contains the address of the Optic proxy.
# Optional: default: OPTIC_PROXY
proxy_variable: OPTIC_PROXY
# Have Optic generate traffic to the proxy itself by specifying endpoint details. A request's 'data' attribute
# is converted to JSON and sent along with the request.
send:
# path: Required
# method: Optional: default: GET
# data: Optional: If omitted on a POST request, default: {}
# headers: Optional: If 'content-type' is omitted, it is set to 'application/json;charset=UTF-8'.
- path: /
method: GET
- path: /users/create
method: POST
headers:
content-type: application/json;charset=UTF-8
data:
name: Hank
config:
# The number of parallel requests to make when using 'requests.send'.
# Optional: default: 4
request_concurrency: 4
Once you've set up your capture configuration you're ready to update, create, and verify your OpenAPI spec!
Create/Update an OpenAPI spec
You can persist changes to (or create) your OpenAPI spec by including --update <mode>
in your capture command.
➜ optic capture openapi.yml --update automatic
Initializing OpenAPI file at openapi.yml
✔ Successfully captured requests
Learning path patterns for unmatched requests...
Documenting new operations:
✔ GET /
✔ GET /users
✔ POST /users/create
There are 3 update modes,
mode | description |
---|---|
interactive | Interactively prompt and confirm observed changes to new and existing endpoints. |
automatic | Automatically apply observed changes to new and existing endpoints. |
documented | Automatically apply observed changes to existing endpoints only. |
Verify an OpenAPI spec
If you already have an OpenAPI spec and run capture without the --update <mode>
option, the requests observed will be compared against your spec without making changes to it.
$ optic capture openapi.yml
✔ Successfully captured requests
✖ GET /
200 response
[404 response body] body is not documented
✔ GET /users
✓ 200 response
✔ POST /users/create
✓ Request Body, ✓ 201 response
Next Steps
View examples generating traffic to Optic, or import existing requests from HAR files or Postman collections.