Control API reference

The Capuris Control API exposes capture and search operations for approved automation. Develop against a non-production appliance first, use a least-privilege service account, and never embed a live credential in source code.

Connect to the API

The examples use this base URL:

https://<HOST>:8080/api/v1

Replace <HOST> with the Capuris Control hostname. Validate the server certificate instead of disabling TLS checks in permanent automation.

Authenticate

Create or obtain an API credential through the approved Capuris Control workflow. Send it in the authorization header expected by the installed release. Existing deployments commonly use a Basic token:

Authorization: Basic <TOKEN>

Store the token in a secret manager or protected environment variable. Redact it from shell history, request logs, screenshots, and support bundles. Rotate it when ownership changes or exposure is suspected.

Make a read request

Use Accept: application/json and inspect both the HTTP status and response body.

curl --fail-with-body \
  --header "Accept: application/json" \
  --header "Authorization: Basic <TOKEN>" \
  "https://<HOST>:8080/api/v1/is_capturing"

The installed release may use a slightly different authorization prefix. Confirm it in the API help supplied with that system.

Capture settings

Use /capture/capture_settings to read or update the main configuration for a capture port.

Read a port

curl --fail-with-body \
  --header "Accept: application/json" \
  --header "Authorization: Basic <TOKEN>" \
  "https://<HOST>:8080/api/v1/capture/capture_settings?port=0"

Update a port

Read the current object first, change only reviewed fields, and send the complete shape required by your release.

curl --fail-with-body --request PUT \
  --header "Authorization: Basic <TOKEN>" \
  --header "Content-Type: application/json" \
  --data '{
    "Port0": "on",
    "Port_Alias": "edge-west",
    "Filename": "edge-west_",
    "CapDir": "/capture/records/Port0/",
    "Timestamp": "nanosecond",
    "Cap2Disk": "capture",
    "IncFile": "on",
    "SegmentSize": "bysize",
    "Bytesize": "1000",
    "Sizeunit": "MB",
    "compress": "false",
    "Rotation": "on",
    "SyncDetect": "false",
    "Merge_Ports": "false",
    "Port_Slicing": "0",
    "Filtering_Enable": "off"
  }' \
  "https://<HOST>:8080/api/v1/capture/capture_settings?port=0"

Field names, string-versus-boolean conventions, and supported values are release-specific. Use the response from the target appliance as the authoritative schema.

Capture filter settings

Use /capture/capture_filter_settings with both port and filter query parameters.

curl --fail-with-body \
  --header "Accept: application/json" \
  --header "Authorization: Basic <TOKEN>" \
  "https://<HOST>:8080/api/v1/capture/capture_filter_settings?port=0&filter=0"

A filter update may include its name, priority, VLAN, protocol, address, port, direction, and whether unmatched packets should be retained. Fetch the existing record before constructing a PUT request; do not copy a payload from another software version without comparing schemas.

After changing a filter, generate known matching and nonmatching traffic. An accepted API response proves that the configuration was stored, not that the rule captures the intended packets.

Packet searches by time

Date-and-time search helpers typically follow this sequence:

1. Open the Control API helper directory supplied with the installation.
2. Activate its Python virtual environment.
3. Review the helper’s built-in usage for the installed release.
4. Provide the input location, start and end timestamps, output location, and optional filters.
5. Monitor completion and verify the output PCAP.

Use an explicit time zone and a narrow window. Search jobs can be storage- and CPU-intensive, so automation should limit concurrency and poll with backoff rather than submitting duplicates.

Search filters

Common controls include:

BPF-style expressions

The search engine accepts standard primitives supported by the installed release. Common examples are:

host 192.0.2.20
src net 198.51.100.0/24 and dst port 443
tcp and (port 80 or port 443)
vlan 200 and udp port 53
greater 128

Operators usually combine protocol, host, network, port, direction, VLAN, length, and byte-offset tests with and, or, not, and parentheses. Extended inline, hexadecimal, and byte-offset features vary by release. Validate complex expressions against a small known PCAP before running them over a large retention window.

Handle responses safely

Automation should log a sanitized request identifier, target system, operation, start time, duration, status code, and result location. Do not log tokens or packet payload.

Set connection and overall timeouts. Make update operations idempotent where possible by reading current state, comparing the desired state, and writing only when a difference exists.

Production automation checklist

• Pin the target host and validate TLS.
• Retrieve credentials from protected storage at runtime.
• Check current state before changing it.
• Limit concurrent capture and search jobs.
• Validate response content, not only the status code.
• Record an audit trail without secrets.
• Test failure, timeout, retry, and partial-completion behavior.
• Provide a documented stop or rollback path.

For the equivalent interface workflows, see Capture and search.