Merge pull request #109 from shravan-lambdatest/docs/api-calls

docs: document making API calls directly in objectives

Author: shravan-lambdatest

.agents/skills/kane-cli/SKILL.md

@@ -199,15 +199,16 @@ kane-cli run "Go to https://app.example.com and login with {{username}} and {{pa
 
 ## 4. Writing objectives
 
-How you phrase the objective string determines what the agent does. Three patterns:
+How you phrase the objective string determines what the agent does. Four patterns:
 
-> For the full catalog — every action verb, every assertion analyze method (Visual / Textual-DOM / URL / Title / DevTools→Network/Console/Performance/Cookies/localStorage/Clipboard), operators, chaining, conditional/negative patterns, and worked examples — Read `references/objectives-cookbook.md`. Same grammar applies to one-shot `kane-cli run` objectives and `_test.md` step bodies.
+> For the full catalog — every action verb, every assertion analyze method (Visual / Textual-DOM / URL / Title / DevTools→Network/Console/Performance/Cookies/localStorage/Clipboard), direct API calls, operators, chaining, conditional/negative patterns, and worked examples — Read `references/objectives-cookbook.md`. Same grammar applies to one-shot `kane-cli run` objectives and `_test.md` step bodies.
 
 | Pattern | Trigger words | Behavior |
 |---|---|---|
 | 🎯 **Action** | "go to", "click", "type", "search", "fill" | Performs browser actions |
 | ✅ **Assertion** | "assert", "verify", "confirm", "check that" | Pass/fail check on a condition |
 | 📦 **Extraction** | "store X as 'name'" | Persists a value into `run_end.final_state` |
+| 🔌 **API call** | "call", "POST/GET a URL", a pasted `curl` | The agent makes the HTTP request itself; "save the response as X", then assert/reference `{{X.status}}` / `{{X.response_body…}}` |
 
 ### The "store as" rule (critical for extraction)
 
@@ -218,6 +219,17 @@ Vague phrasing like "read", "tell me", "report" does NOT reliably extract data 
 
 Stored values appear in `run_end.final_state` and become the second results table per §1.4.
 
+### Calling APIs directly
+
+The agent can make API calls itself — not just observe the page's traffic. Phrase an explicit call and name the response:
+
+```text
+"Call POST https://api.example.com/login with body {...}, save the response as login,
+ assert {{login.status}} is 200"
+```
+
+Reference the saved response as `{{login.status}}`, `{{login.response_body}}`, or `{{login.response_body.<field>}}`; a pasted `curl` works too. Full grammar in `references/objectives-cookbook.md` §3.5.
+
 ### Chaining
 
 Action → extraction → assertion in one objective:

.agents/skills/kane-cli/references/objectives-cookbook.md

@@ -1,4 +1,4 @@
-<!-- Read this when authoring objective strings — for either `kane-cli run "..."` or step bodies inside a `_test.md`. Owns the full catalog of action verbs, assertion patterns, checkpoint analyze methods (Visual, Textual/DOM, URL, Title, DevTools→Network/Console/Performance/Cookies/localStorage), operators, extraction patterns, chaining, variables, and common pitfalls. The same objective grammar applies to one-shot runs and testmd steps. -->
+<!-- Read this when authoring objective strings — for either `kane-cli run "..."` or step bodies inside a `_test.md`. Owns the full catalog of action verbs, assertion patterns, checkpoint analyze methods (Visual, Textual/DOM, URL, Title, DevTools→Network/Console/Performance/Cookies/localStorage), operators, extraction patterns, direct API calls, chaining, variables, and common pitfalls. The same objective grammar applies to one-shot runs and testmd steps. -->
 
 # Writing Kane-CLI Objectives — Pattern Cookbook
 
@@ -81,6 +81,8 @@ Five subdomains. Each one is the right choice when the data you care about lives
 
 The agent captures every HTTP request/response per step. **Resets each step** — assert on traffic in the same step it happens (or extract and carry forward).
 
+These assertions also cover API calls **you** make directly in an objective (§3.5), not just the requests the page makes on its own — the agent records its own calls and you query them with the same fields below.
+
 Queryable fields: `method`, `url`, `domain`, `path`, `query_params`, `resource_type`, `request_headers`, `request_body`, `response_status`, `response_headers`, `response_body`, `timing.duration_ms`, `timing.ttfb_ms`, `failed`, `failure_reason`.
 
 ```text
@@ -217,6 +219,43 @@ Assertions support these comparisons. Phrase them naturally — the agent maps t
 
 If you're not sure which method, default to **Visual** — that's what the agent does too.
 
+### 3.5 Calling an API directly
+
+Distinct from observing the page's network traffic (§3.2): you can have the agent **make an HTTP request itself** as part of an objective — to seed data, hit a backend, or check a service — then assert on or reuse the response.
+
+Phrase an explicit call and name the response with "save the response as …":
+
+```text
+Call POST https://api.example.com/orders with body {"item": "sku_42", "qty": 1}, save the response as order
+Hit GET https://api.example.com/orders/123, save the response as fetched
+```
+
+A pasted `curl` works too and is kept verbatim (method, headers, body, auth):
+
+```text
+curl -X POST https://api.example.com/login -H 'Content-Type: application/json' -d '{"u":"a","p":"b"}', save the response as login
+```
+
+Once saved, reference the response by name:
+
+| Reference | Resolves to |
+|---|---|
+| `{{order.status}}` | the HTTP status code (e.g. `201`) |
+| `{{order.response_body}}` | the whole response body |
+| `{{order.response_body.<field>}}` | a field from the JSON response body |
+
+Then assert or chain on it — API calls and browser actions mix freely in one objective:
+
+```text
+Call POST https://api.example.com/login with body {"u": "{{user}}", "p": "{{password}}"}, save the response as login,
+assert {{login.status}} is 200,
+then open https://app.example.com and verify the dashboard loads
+```
+
+**Direct call vs. DevTools/Network (§3.2):** use a **direct call** when *you* want the agent to make the request (seed a record, call a backend, set up state). Use **DevTools/Network** when you want to **observe the requests the page itself makes** during a UI flow. They compose: seed via a direct call, drive the UI, then assert on the page's traffic.
+
+**Tokens:** put any credential/token in a variable marked `secret: true` (§6) so it's masked and never logged.
+
 ---
 
 ## 4. Extraction — the "store as" rule
@@ -394,3 +433,15 @@ Store the order number as 'order_id'.
 ```
 
 The step body is exactly the same grammar as `kane-cli run`. Everything in this cookbook applies.
+
+### Example D — Seed via API, then verify in the UI
+
+```text
+"Call POST https://api.example.com/orders with body {"item": "sku_42", "qty": 1},
+ save the response as order,
+ assert {{order.status}} is 201,
+ then open https://app.example.com/orders,
+ assert an order for 'sku_42' is visible"
+```
+
+The agent makes the API call directly, captures the response, asserts on its status, then drives the UI to confirm the seeded data appears. (Direct call → UI verify — contrast with §3.2, where you observe the page's own traffic.)

.claude/skills/kane-cli/SKILL.md

@@ -199,15 +199,16 @@ kane-cli run "Go to https://app.example.com and login with {{username}} and {{pa
 
 ## 4. Writing objectives
 
-How you phrase the objective string determines what the agent does. Three patterns:
+How you phrase the objective string determines what the agent does. Four patterns:
 
-> For the full catalog — every action verb, every assertion analyze method (Visual / Textual-DOM / URL / Title / DevTools→Network/Console/Performance/Cookies/localStorage/Clipboard), operators, chaining, conditional/negative patterns, and worked examples — Read `references/objectives-cookbook.md`. Same grammar applies to one-shot `kane-cli run` objectives and `_test.md` step bodies.
+> For the full catalog — every action verb, every assertion analyze method (Visual / Textual-DOM / URL / Title / DevTools→Network/Console/Performance/Cookies/localStorage/Clipboard), direct API calls, operators, chaining, conditional/negative patterns, and worked examples — Read `references/objectives-cookbook.md`. Same grammar applies to one-shot `kane-cli run` objectives and `_test.md` step bodies.
 
 | Pattern | Trigger words | Behavior |
 |---|---|---|
 | 🎯 **Action** | "go to", "click", "type", "search", "fill" | Performs browser actions |
 | ✅ **Assertion** | "assert", "verify", "confirm", "check that" | Pass/fail check on a condition |
 | 📦 **Extraction** | "store X as 'name'" | Persists a value into `run_end.final_state` |
+| 🔌 **API call** | "call", "POST/GET a URL", a pasted `curl` | The agent makes the HTTP request itself; "save the response as X", then assert/reference `{{X.status}}` / `{{X.response_body…}}` |
 
 ### The "store as" rule (critical for extraction)
 
@@ -218,6 +219,17 @@ Vague phrasing like "read", "tell me", "report" does NOT reliably extract data 
 
 Stored values appear in `run_end.final_state` and become the second results table per §1.4.
 
+### Calling APIs directly
+
+The agent can make API calls itself — not just observe the page's traffic. Phrase an explicit call and name the response:
+
+```text
+"Call POST https://api.example.com/login with body {...}, save the response as login,
+ assert {{login.status}} is 200"
+```
+
+Reference the saved response as `{{login.status}}`, `{{login.response_body}}`, or `{{login.response_body.<field>}}`; a pasted `curl` works too. Full grammar in `references/objectives-cookbook.md` §3.5.
+
 ### Chaining
 
 Action → extraction → assertion in one objective:

.claude/skills/kane-cli/references/objectives-cookbook.md

@@ -1,4 +1,4 @@
-<!-- Read this when authoring objective strings — for either `kane-cli run "..."` or step bodies inside a `_test.md`. Owns the full catalog of action verbs, assertion patterns, checkpoint analyze methods (Visual, Textual/DOM, URL, Title, DevTools→Network/Console/Performance/Cookies/localStorage), operators, extraction patterns, chaining, variables, and common pitfalls. The same objective grammar applies to one-shot runs and testmd steps. -->
+<!-- Read this when authoring objective strings — for either `kane-cli run "..."` or step bodies inside a `_test.md`. Owns the full catalog of action verbs, assertion patterns, checkpoint analyze methods (Visual, Textual/DOM, URL, Title, DevTools→Network/Console/Performance/Cookies/localStorage), operators, extraction patterns, direct API calls, chaining, variables, and common pitfalls. The same objective grammar applies to one-shot runs and testmd steps. -->
 
 # Writing Kane-CLI Objectives — Pattern Cookbook
 
@@ -81,6 +81,8 @@ Five subdomains. Each one is the right choice when the data you care about lives
 
 The agent captures every HTTP request/response per step. **Resets each step** — assert on traffic in the same step it happens (or extract and carry forward).
 
+These assertions also cover API calls **you** make directly in an objective (§3.5), not just the requests the page makes on its own — the agent records its own calls and you query them with the same fields below.
+
 Queryable fields: `method`, `url`, `domain`, `path`, `query_params`, `resource_type`, `request_headers`, `request_body`, `response_status`, `response_headers`, `response_body`, `timing.duration_ms`, `timing.ttfb_ms`, `failed`, `failure_reason`.
 
 ```text
@@ -217,6 +219,43 @@ Assertions support these comparisons. Phrase them naturally — the agent maps t
 
 If you're not sure which method, default to **Visual** — that's what the agent does too.
 
+### 3.5 Calling an API directly
+
+Distinct from observing the page's network traffic (§3.2): you can have the agent **make an HTTP request itself** as part of an objective — to seed data, hit a backend, or check a service — then assert on or reuse the response.
+
+Phrase an explicit call and name the response with "save the response as …":
+
+```text
+Call POST https://api.example.com/orders with body {"item": "sku_42", "qty": 1}, save the response as order
+Hit GET https://api.example.com/orders/123, save the response as fetched
+```
+
+A pasted `curl` works too and is kept verbatim (method, headers, body, auth):
+
+```text
+curl -X POST https://api.example.com/login -H 'Content-Type: application/json' -d '{"u":"a","p":"b"}', save the response as login
+```
+
+Once saved, reference the response by name:
+
+| Reference | Resolves to |
+|---|---|
+| `{{order.status}}` | the HTTP status code (e.g. `201`) |
+| `{{order.response_body}}` | the whole response body |
+| `{{order.response_body.<field>}}` | a field from the JSON response body |
+
+Then assert or chain on it — API calls and browser actions mix freely in one objective:
+
+```text
+Call POST https://api.example.com/login with body {"u": "{{user}}", "p": "{{password}}"}, save the response as login,
+assert {{login.status}} is 200,
+then open https://app.example.com and verify the dashboard loads
+```
+
+**Direct call vs. DevTools/Network (§3.2):** use a **direct call** when *you* want the agent to make the request (seed a record, call a backend, set up state). Use **DevTools/Network** when you want to **observe the requests the page itself makes** during a UI flow. They compose: seed via a direct call, drive the UI, then assert on the page's traffic.
+
+**Tokens:** put any credential/token in a variable marked `secret: true` (§6) so it's masked and never logged.
+
 ---
 
 ## 4. Extraction — the "store as" rule
@@ -394,3 +433,15 @@ Store the order number as 'order_id'.
 ```
 
 The step body is exactly the same grammar as `kane-cli run`. Everything in this cookbook applies.
+
+### Example D — Seed via API, then verify in the UI
+
+```text
+"Call POST https://api.example.com/orders with body {"item": "sku_42", "qty": 1},
+ save the response as order,
+ assert {{order.status}} is 201,
+ then open https://app.example.com/orders,
+ assert an order for 'sku_42' is visible"
+```
+
+The agent makes the API call directly, captures the response, asserts on its status, then drives the UI to confirm the seeded data appears. (Direct call → UI verify — contrast with §3.2, where you observe the page's own traffic.)

docs/user-guide/features/api-calls.md

@@ -0,0 +1,60 @@
+# API Calls
+
+Objectives can have the agent **make an API call directly** — not just observe the requests a page makes. This is useful for seeding data before a flow, hitting a backend to set up state, or checking a service, then asserting on or reusing the response.
+
+## Making a call
+
+Phrase an explicit HTTP request and name its response with "save the response as …":
+
+```
+Call POST https://api.example.com/orders with body {"item": "sku_42", "qty": 1}, save the response as order
+Hit GET https://api.example.com/orders/123, save the response as fetched
+Call DELETE https://api.example.com/orders/123
+```
+
+A pasted `curl` works too and is kept exactly as written — method, headers, body, and auth:
+
+```
+curl -X POST https://api.example.com/login -H 'Content-Type: application/json' -d '{"u":"a","p":"b"}', save the response as login
+```
+
+## Using the response
+
+Once you've saved a response under a name, reference it elsewhere in the objective:
+
+| Reference | Resolves to |
+|-----------|-------------|
+| `{{order.status}}` | the HTTP status code (e.g. `201`) |
+| `{{order.response_body}}` | the whole response body |
+| `{{order.response_body.<field>}}` | a field from the JSON response body |
+
+Assert on it, or feed it into later actions — API calls and browser actions mix freely in one objective:
+
+```
+Call POST https://api.example.com/login with body {"u": "{{user}}", "p": "{{password}}"}, save the response as login,
+assert {{login.status}} is 200,
+then open https://app.example.com and verify the dashboard loads
+```
+
+```
+Call POST https://api.example.com/orders with body {"item": "sku_42", "qty": 1}, save the response as order,
+assert {{order.status}} is 201,
+then open https://app.example.com/orders and verify an order for "sku_42" is visible
+```
+
+## Tokens and secrets
+
+Put any API token or credential in a variable marked `secret: true` (see [Variables and Context](../variables-and-context.md)) so it is masked in logs and never stored in plain text:
+
+```
+curl -X DELETE https://api.example.com/records/42 -H "Authorization: Bearer {{api_token}}"
+```
+
+## Make a call vs. observe page traffic
+
+These are two different things:
+
+- **Make a call (this page)** — *you* tell the agent to send a request: seed a record, call a backend, set up state.
+- **[Network assertions](./checkpoints/devtools/network.md)** — *observe* the requests the page itself makes during a UI flow (status codes, bodies, timing).
+
+They compose: seed state with a direct call, drive the UI, then assert on the page's own network traffic.

docs/user-guide/features/checkpoints/devtools/network.md

@@ -2,6 +2,8 @@
 
 Network assertions let you verify HTTP traffic — API responses, status codes, headers, response bodies, and request timing.
 
+> These network assertions also cover API calls **you** make directly in an objective — not just the requests the page makes on its own. The agent records its own calls and you query them with the same fields below. To *make* a call (seed data, hit a backend), see [API Calls](../../api-calls.md).
+
 ## How Capture Works
 
 KaneAI captures all HTTP network traffic automatically during each test step:

docs/user-guide/running-tests.md

@@ -39,6 +39,9 @@ Open https://app.example.com, set a cookie named session with value
 Objectives can also set, delete, and clear cookies, localStorage, and the
 test clipboard directly — see [Browser State Actions](./features/browser-state.md).
 
+Objectives can also make API calls directly — POST/GET a URL or paste a `curl`,
+save the response, and assert on it — see [API Calls](./features/api-calls.md).
+
 ### Bad to better
 
 | | Objective |