Create your first Rule

This guide walks you through the shortest useful HTTPeep workflow: start the proxy, confirm traffic is captured, then create one rule that replaces a real response with local inline content.

What you will build

You will create an enabled rule with this behavior:

1. Start capturing traffic

2. Create a map-local inline-content rule

A map-local inline-content rule intercepts matching requests and returns content stored directly in the rule. In the rule file this resolve type is map_local_inline_content.

{
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ]
}

3. Test the rule

Make a request to the matched URL:

curl https://api.example.com/users

The response should be the inline content you entered in the rule editor.

In HTTPeep, open the captured session and check:

• The request URL is https://api.example.com/users
• The response body matches your inline content
• The session shows that the request was resolved by your rule

Optional: edit the rule as YAML

HTTPeep stores rules in ~/.httpeep/rules/rule.yaml. You can use the app UI for normal editing, or edit the YAML file directly when you want rules under version control.

- id: rule_quickstart_map_local_inline_users
  description: Quickstart - Mock users API
  enabled: true
  match:
    domains:
    - type: exact
      value: api.example.com
    originProtocol: https
    port: null
    path:
      type: exact
      value: /users
    query: null
    method: null
    headers: null
  resolve:
    type: map_local_inline_content
    content: |-
      {
        "users": [
          { "id": 1, "name": "Alice" },
          { "id": 2, "name": "Bob" }
        ]
      }
    mimeType: null
    statusCode: null
    headers: null

Because rules are plain YAML files, you can:

• Edit them directly in any text editor
• Commit them to Git and track changes over time
• Share them with teammates by pushing to a shared repository
• Use different rule files for different environments or projects

Optional: import the rule via deeplink

HTTPeep supports importing rules directly via a httpeep:// deeplink. Clicking the link opens the app and prompts you to confirm before adding the rule.

Inline import (payload in URL)

The quickest way to import this rule is to use an inline deeplink with a Base64-encoded JSON payload:

httpeep://rule/import?scope=inline&payload=WwogICB7CiAgICAgICJpZCI6ICJydWxlX3F1aWNrc3RhcnRfbWFwX2xvY2FsX2lubGluZV91c2VycyIsCiAgICAgICJkZXNjcmlwdGlvbiI6ICJRdWlja3N0YXJ0IC0gTW9jayB1c2VycyBBUEkiLAogICAgICAiZW5hYmxlZCI6IHRydWUsCiAgICAgICJtYXRjaCI6IHsKICAgICAgICAgImRvbWFpbnMiOiBbCiAgICAgICAgICAgIHsKICAgICAgICAgICAgICAgInR5cGUiOiAiZXhhY3QiLAogICAgICAgICAgICAgICAidmFsdWUiOiAiYXBpLmV4YW1wbGUuY29tIgogICAgICAgICAgICB9CiAgICAgICAgIF0sCiAgICAgICAgICJvcmlnaW5Qcm90b2NvbCI6ICJodHRwcyIsCiAgICAgICAgICJwb3J0IjogbnVsbCwKICAgICAgICAgInBhdGgiOiB7CiAgICAgICAgICAgICJ0eXBlIjogImV4YWN0IiwKICAgICAgICAgICAgInZhbHVlIjogIi91c2VycyIKICAgICAgICAgfSwKICAgICAgICAgInF1ZXJ5IjogbnVsbCwKICAgICAgICAgIm1ldGhvZCI6IG51bGwsCiAgICAgICAgICJoZWFkZXJzIjogbnVsbAogICAgICB9LAogICAgICAicmVzb2x2ZSI6IHsKICAgICAgICAgInR5cGUiOiAibWFwX2xvY2FsX2lubGluZV9jb250ZW50IiwKICAgICAgICAgImNvbnRlbnQiOiAie1xuICBcInVzZXJzXCI6IFtcbiAgICB7IFwiaWRcIjogMSwgXCJuYW1lXCI6IFwiQWxpY2VcIiB9LFxuICAgIHsgXCJpZFwiOiAyLCBcIm5hbWVcIjogXCJCb2JcIiB9XG4gIF1cbn0iLAogICAgICAgICAibWltZVR5cGUiOiBudWxsLAogICAgICAgICAic3RhdHVzQ29kZSI6IG51bGwsCiAgICAgICAgICJoZWFkZXJzIjogbnVsbAogICAgICB9CiAgIH0KXQ==

Import Quickstart Rule →

When you click the link, HTTPeep will:

1. Launch the main window
2. Show a confirmation dialog with the rule summary
3. Append the rule to your list after you click Continue

Import from a GitHub repository

For teams or public rule collections, host rules in a GitHub repo and reference them by path:

httpeep://rule/import?scope=repo&repo=HTTPeep/httpeep-deeplink&ref=main&path=rules/quickstart.json

This is useful when you want version-controlled rules that can be shared across your team.

Rule did not match? Check these first

• Condition mismatch: domain, path, or protocol does not exactly match the request
• Rule order: an earlier rule matched first and terminated processing
• Rule disabled: the rule switch is off, or edits were not saved
• Proxy not active: the system proxy is off, or the app making the request does not use the system proxy

If you need a full execution model, continue with Rule engine.

Next steps