> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Payload Capture API

> Configure opt-in, sanitized input payload capture

Payload capture is off by default. These endpoints configure capture only. MeshAI does not currently expose captured payload records through a public read or export endpoint.

<Warning>
  Enabling capture is a tenant processing instruction, not proof of end-user consent or another lawful basis. Your organization remains responsible for establishing and documenting its lawful basis.
</Warning>

## Get Configuration

```
GET /payload-capture/config
```

Requires `payload:read`. An unconfigured tenant receives the default-off response:

```bash theme={null}
curl https://api.meshai.dev/api/v1/payload-capture/config \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "enabled": false,
      "configured": false,
      "maximum_retention_days": 30,
      "legal_basis_notice": "Enabling capture is a tenant processing instruction, not proof of end-user consent or another lawful basis. The tenant remains responsible for that basis."
    }
  }
  ```
</ResponseExample>

## Update Configuration

```
PUT /payload-capture/config
```

Requires `payload:write`. `retention_days` must be from 1 through 30 and cannot exceed the tenant plan's telemetry retention. `processing_purpose` must contain 10 through 500 characters. You can provide up to 25 redaction rules with unique IDs.

```bash theme={null}
curl -X PUT https://api.meshai.dev/api/v1/payload-capture/config \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "retention_days": 7,
    "processing_purpose": "Audit regulated agent input evidence",
    "redaction_rules": [
      {
        "id": "customer.account",
        "field_path": "messages.content",
        "pattern": "account-[0-9]+"
      }
    ]
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "configured": true,
      "enabled": true,
      "retention_days": 7,
      "processing_purpose": "Audit regulated agent input evidence",
      "redaction_rules": [
        {
          "id": "customer.account",
          "field_path": "messages.content",
          "pattern": "account-[0-9]+"
        }
      ],
      "config_version": 1,
      "updated_by": "01JKEY0000000000000000001",
      "created_at": "2026-08-10T14:30:00Z",
      "updated_at": "2026-08-10T14:30:00Z",
      "maximum_retention_days": 30,
      "legal_basis_notice": "Enabling capture is a tenant processing instruction, not proof of end-user consent or another lawful basis. The tenant remains responsible for that basis."
    }
  }
  ```
</ResponseExample>

A rule `field_path` is a dot-separated sequence of field names, such as `messages.content`. Array selectors such as `messages[*].content` are not accepted. `pattern`, when supplied, must be a valid regular expression no longer than 500 characters.

Each update increments `config_version` and creates a `payload_capture.configured` audit event. To disable future capture, send the same required fields with `enabled: false`; `retention_days` and `processing_purpose` remain required. The disabled configuration stops requests that read it from starting capture, but work already in flight or queued can still finish. Disabling does not delete existing sanitized records.

Each record receives an `expires_at` value from the retention setting in effect when it was written, so a later retention change applies only to new records. Expiry makes the record eligible for scheduled deletion; it is not a guarantee of deletion at that exact instant. There is currently no public payload read, export, delete, or self-service data-subject-request endpoint.

See [Sanitized Input Capture](/governance/payload-capture) for supported inputs, redaction, and failure semantics.