Getting Started with ApiCatcher

ApiCatcher captures, inspects, and analyzes an app’s HTTP/HTTPS and WebSocket traffic on device.

This guide covers everyday capture work: certificates, traffic filters, request history, exports, and API docs. Rewrite, scripts, combo replay, and other advanced features live in the docs below.

Further reading:

• Rewrite & Scripts
• Script Guide
• Custom CA
• Protobuf Decode
• Combo Replay
• Scheduled Tasks
• Real-time Sync
• Cloud Sync

Table of Contents

1. Certificates
2. Traffic filters
3. Capture sessions and history search
4. Find Cookie
5. Export HAR, files, and single requests
6. Auto-generated API docs
7. API Scan

1. Certificates

1.1 Install and trust the CA certificate (required for HTTPS)

Most app traffic is HTTPS. ApiCatcher does not capture HTTPS by default: without a trusted CA it cannot decrypt the stream, so there is nothing useful to inspect. Install and fully trust the CA before you capture HTTPS.

Two ways to set up a certificate:

1. Use the CA ApiCatcher generates (recommended in most cases). Follow the steps below.
2. Import your own certificate (enterprise CA). Skip ahead to 1.2.

Default CA:

1. Tap Install Certificate in the app. iOS opens Safari and downloads a configuration profile.
2. Open Settings → General → VPN & Device Management and install the ApiCatcher profile.
3. Then open Settings → General → About → Certificate Trust Settings, find the certificate whose name starts with ApiCatcher CA, and turn on Full Trust.

Troubleshooting

• Timeouts or odd status codes while debugging usually mean step 3 was skipped.
• After deleting and reinstalling the app, the old profile is stale. Remove it in Settings and run through the steps again.

1.2 Enterprise certificates

Some internal apps only trust the company’s CA.

• What it does: import a .pem or .p12 from your org and bind it to internal hosts (for example *.corp.internal) so local TLS handshakes succeed.
• Note: import or edit this while capture is stopped. Restart capture afterwards.

1.3 Custom / self-signed certificates

If you do not have an enterprise CA and do not want ApiCatcher’s generated cert, import your own through the same enterprise-certificate flow. See Custom CA.

2. Traffic filters

System and background apps generate a lot of noise. Filters decide what gets recorded so you can stay on the project you are debugging.

• Blocklist: matching hosts are not recorded. With an empty allowlist, everything else is recorded.
• Allowlist: once it has any rule, only matching requests are recorded.
• Wildcards: * works. *.example-api.com matches every subdomain of that host.

Troubleshooting

• Missing traffic: check that the host is not sitting on the blocklist, and that the allowlist is not on without that host.
• Use simple star matches such as *.api.com. Regular expressions are not supported here.

3. Capture sessions and history search

Block/allow lists decide what is stored. On the History page, Session and search filters narrow what you already captured.

3.1 Capture session

A session is one VPN capture run. The UI labels it with the start time (yyyy-MM-dd HH:mm:ss). You cannot rename it.

Starting VPN capture creates a session. Stopping VPN writes the end time and request count. A session with zero requests is deleted. While capture is running, the end time shows Capturing....

The History Session filter can pin one run or show All. The picker also shows the time range, duration, request count, and up to five hosts seen in that run. Deleting a session removes its request records.

3.2 Filters

The History filter bar is configurable. Use Configure Filters to choose which chips appear, or Reset Filters to clear them.

3.3 Keyword search

The search field matches URL by default (placeholder: Search url...). The keyword is a case-insensitive substring. No regex, no AND / OR.

Change the field from History … → Switch Search Target:

Body search only reads text Content-Types (HTML / XML / JSON / plain text / form-urlencoded / form-data). Images, video, and other binary bodies are skipped.

4. Find Cookie

Find Cookie returns the Cookie header from the most recent request to a host. It reads request Cookie only — not Set-Cookie, and it does not merge cookies across requests.

1. Open History.
2. Top-right … → Find Cookie.
3. Enter a Host (required; pick one you have already captured, or type it).
4. Optionally pick a Session. Leave it empty to search all sessions.
5. Tap Search Cookie.

A match shows Recent Cookie found and the name/value pairs. Otherwise: No request with Cookie found.

5. Export HAR, files, and single requests

5.1 Export as HAR

The file is HAR 1.2 JSON and opens in Charles, Fiddler, Burp, and similar tools. The name looks like apicatcher-export-yyyyMMddHHmmss.har.

The UI reports: Total requests to export: N. You can modify filters to change the requests to export. Do not leave the page while the export is running.

5.2 Export images / video / audio

Open file management from History (folder icon).

• Three buckets: Image, Video, Audio.
• Narrow by Session and Host.
• Range / Content-Range pieces are merged before export.
• Export one file, or batch-export as a ZIP grouped by host.

From request details you can also Export File on the request or response body; the file type follows Content-Type.

5.3 Export a single request

In request details, Export Request:

• Raw: original HTTP request + response (.txt)
• cURL: a command you can replay in a terminal (.sh)
• Markdown: Markdown preview (.md)

6. Auto-generated API docs

After eligible HTTP/HTTPS requests are captured, the app builds or updates API docs locally, grouped by Host. When the same endpoint is seen again, new fields are appended; existing parameter names are not overwritten.

6.1 What gets documented

Only HTTP/HTTPS requests that have a response and whose status is not 301–308. The request Content-Type must be JSON / XML / multipart/form-data / x-www-form-urlencoded, or the response must be JSON / XML. Images, video, HTML, and plain text are skipped.

Requests changed by a rewrite rule or script are not documented. The identity key is method + host + path (for example GET + api.example.com + /v1/user).

Merge rules:

• Query, Header, and Body fields: add missing names only.
• Body example: updated only when this response is status 200.
• Common headers such as Cookie and User-Agent are omitted. Authorization, Content-Type, and custom headers are kept.

6.2 Export to Postman / Apifox / Bruno

Where to start:

• Export from the Host’s API list (every endpoint under that host).
• Export from a single API’s detail page (that endpoint only).
• Settings → API Favorites → Export for favorited endpoints only.

Step-by-step screenshots:

• How to Export Captured HTTPS Requests to Postman
• How to Export Captured HTTPS Requests to Apifox

7. API Scan

API Scan reviews locally captured traffic for quality, obvious leaks, and latency. Analysis stays on device.

7.1 Built-in checks

• Sensitive data: phone numbers, national IDs, emails, and cloud credentials (AWS keys, OpenAI API keys) sent in the clear.
• Stack traces: Java, Python, or SQL error stacks that leaked in a response body.
• Chatty endpoints: calls whose average interval falls below a threshold you set — often a loop or a retry bug.
• Latency: p95 / p99 per endpoint.

7.2 Custom Scan

Write a JS check for your own rules.

• Return null when the request looks fine. Return a short note (≤200 characters) when it does not (oversized body, missing security header, …). That note lands in the scan report.

Troubleshooting

• Empty results: confirm the scan scope (Host / Session) actually contains JSON/API traffic, not only static assets. Each run has a record cap.