***
title: Connect with the API Catalog using Postman Insights Agent
updated: 2026-03-01T00:00:00.000Z
max-toc-depth: 2
----------------
The Postman Insights Agent monitors your Kubernetes services and automatically populates your API Catalog. The recommended way to get started is **Discovery Mode** — deploy the agent once and it finds and registers your services automatically, with no per-service configuration needed.
See [Workspace Mode](/docs/insights/reference/agent/api-catalog#get-started-with-workspace-mode) to create a workspace and environment in Postman before deploying.
## Prerequisites
* A Postman API key with required permissions
* Kubernetes cluster v1.19+
* `kubectl` configured for your cluster
## Deploy with Discovery Mode
1. Create the namespace and API key secret. The agent authenticates with Postman using your API key. Store it as a Kubernetes Secret so it never appears in plain text in the manifest:
```bash
kubectl create namespace postman-insights-namespace
kubectl create secret generic postman-agent-secrets \
--namespace postman-insights-namespace \
--from-literal=postman-api-key=
```
2. Download the base DaemonSet manifest, [`postman-insights-agent-daemonset.yaml`](https://releases.observability.postman.com/scripts/postman-insights-agent-daemonset.yaml).
3. Edit the manifest for Discovery Mode. The downloaded manifest requires three changes before it works with Discovery Mode. Open the file and apply the following edits:
* Enable Discovery Mode. Find the `args` section and add `--discovery-mode`:
```yaml
args:
- kube
- run
- --discovery-mode
```
`--discovery-mode` and `--repro-mode` serve different purposes and are not alternatives. Keep any other flags in `args` that your deployment already uses. Just add `--discovery-mode` to enable service discovery.
* Set your cluster name. Discovery Mode requires a unique cluster name to identify your services across environments. Add it to the `env` section:
```yaml
env:
- name: POSTMAN_INSIGHTS_CLUSTER_NAME
value: "" # e.g. "production" or "us-east-staging"
```
The cluster name is combined with the namespace and workload name to build a unique service identifier (`cluster/namespace/workload`). Choose a name that is stable and unique. Changing it later will cause services to appear as new entries.
* Wire the API key. Reference the Secret you created in Step 1. Add this to the `env` section alongside the cluster name:
```yaml
env:
- name: POSTMAN_INSIGHTS_CLUSTER_NAME
value: ""
- name: POSTMAN_INSIGHTS_API_KEY
valueFrom:
secretKeyRef:
name: postman-agent-secrets
key: postman-api-key
```
After all three changes, the relevant part of your manifest should look like this:
```yaml
containers:
- name: postman-insights-agent
image: public.ecr.aws/postman/postman-insights-agent:latest
args:
- kube
- run
- --discovery-mode
env:
- name: POSTMAN_INSIGHTS_CLUSTER_NAME
value: ""
- name: POSTMAN_INSIGHTS_API_KEY
valueFrom:
secretKeyRef:
name: postman-agent-secrets
key: postman-api-key
- name: POSTMAN_INSIGHTS_K8S_NODE
valueFrom:
fieldRef:
fieldPath: spec.nodeName
- name: POSTMAN_INSIGHTS_CRI_ENDPOINT
value: /var/run/containerd/containerd.sock
```
4. Apply the manifest.
```bash
kubectl apply -f postman-insights-agent-daemonset.yaml
```
5. Verify the deployment.
Check that the agent pods are running on each node:
```bash
kubectl get pods -n postman-insights-namespace
```
Then, inspect the logs to confirm services are being discovered:
```bash
kubectl logs -n postman-insights-namespace -l name=postman-insights-agent --tail=50
```
You can expect to see log lines indicating pods are being discovered and services are being registered with Postman. If pods aren't appearing, see [Troubleshooting](/docs/insights/reference/agent/api-catalog#troubleshooting).
6. Complete onboarding in Postman. From **Home**, click **API Catalog > Service Discovery > Postman Insights Catalog**. Then, select the service and the environment to integrate into API Catalog.
The Postman API key must belong to a user with write access to target workspaces (workspace Admin or Super Admin). The agent creates and links applications on behalf of this user.
Discovered services have a traffic capture window. If a service isn't onboarded in the Postman app within that window, the agent pauses capture for that service. Completing onboarding lifts the restriction. See [Traffic TTL](/docs/insights/reference/agent/api-catalog#discovery-traffic-ttl) for details.
## Optional: Limit discovery to specific namespaces
By default, the agent discovers pods in all namespaces except a built-in exclusion list (for example, Kubernetes system, monitoring, GitOps tools). To capture only specific namespaces, add `--include-namespaces` to the `args` section in the manifest:
```yaml
args:
- kube
- run
- --discovery-mode
- --include-namespaces=production,staging
```
For the full list of filtering options — namespace exclusions, label filtering, per-pod opt-out — see the [Pod Filtering reference](/docs/insights/reference/agent/api-catalog#pod-filtering).
## Choosing an approach
| | Discovery Mode | Workspace Mode |
| ------------------- | ------------------------------------------- | ---------------------------------------- |
| **Setup** | Deploy once, agent handles registration | Configure Postman first, then deploy |
| **Best for** | Many microservices, zero-config onboarding | Per-service control, Postman-first teams |
| **New services** | Picked up automatically as they're deployed | Must configure each service manually |
| **Required inputs** | API key + cluster name | Workspace ID + system environment ID |
For sidecar injection, Workspace Mode instructions, advanced filtering, environment variable reference, and troubleshooting, see [Insights Agent deployment modes](/docs/insights/reference/agent/api-catalog#sidecar).