DEV Community: Hassann

How to Add If/Else Branching and Flow Control to API Test Scenarios in Apidog

Hassann — Wed, 15 Jul 2026 09:49:32 +0000

Most API tests run in a straight line: call login, call checkout, call the receipt endpoint, and assert each response. That approach breaks down when a later request depends on an earlier result. If login returns 401, running checkout adds noise and can hide the root cause. A better scenario reads the login response, branches on its result, and reports exactly where execution stopped.

Try Apidog today

This guide shows how to add if/else logic to an API test scenario in Apidog. You will build a scenario that logs in, checks the response status, and runs checkout only when login succeeds. If you need the linear scenario basics first, see how to write a test scenario with Apidog. For a language-level introduction to branching, see the MDN guide to conditional statements.

What flow control is—and is not

In Apidog, automated tests are built in the Tests module. The main unit is a Test Scenario, similar to a Collection in Postman. A scenario contains Test Steps, which can be API requests or control-flow elements, such as branches, loops, and delays.

Flow control lets a scenario make decisions instead of executing every request sequentially. The Apidog flow control and conditional branching documentation covers the available controls.

This article focuses on Conditional Branching, Apidog's if/else implementation:

if login status is 200:
  run checkout
else:
  report login failure

Do not confuse branching with looping:

Conditional Branching evaluates a condition and chooses a path once.
For Loops and ForEach Loops repeat a block of steps.

For example, use a ForEach loop to process multiple order IDs. Use a branch to decide whether a checkout request should run at all. See the ForEach loop tutorial for iteration workflows.

Apidog documentation lists no free-versus-paid restriction for flow control, branching, loops, or passing data between steps. It also does not identify a cloud-versus-self-hosted difference for these features.

Build a scenario that branches on the login response

The target workflow is simple:

Send a login request.
Check whether it returns HTTP 200.
Run checkout only if login succeeds.
Run a failure-reporting step if login fails.

Step 1: Create a test scenario

Open Apidog.
Go to the Tests module.
Click the + next to the search bar.
Create a Test Scenario.
Select its directory and priority.

You now have an empty scenario ready for steps.

Step 2: Add the login request

Add a Test Step for your login endpoint. You can import an existing endpoint, use a saved endpoint case, paste cURL, or create a custom request.

For a quick implementation, create a custom POST request:

POST https://api.your-store.com/v1/login
Content-Type: application/json

{
  "email": "dana@example.com",
  "password": "correct-horse-battery-staple"
}

Run the request once to confirm its expected response. For example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "usr_10482"
}

The important part for this tutorial is the HTTP status: a successful login should return 200.

Step 3: Enter orchestrate mode

Click any scenario step to open orchestrate mode.

The left panel shows the complete execution flow.
The right panel shows configuration for the selected step.
Drag the ≡ handle to reorder steps when needed.

You will use this view to place and configure the conditional branch.

Step 4: Add a Conditional Branching step

Click Add Step.
Choose Conditional Branching.
Configure the condition using the login response status.

Apidog supports these judgment operators:

Equals
Does not equal
Exists
Does not exist
Less than
Less than or equal
Greater than
Greater than or equal
Matches with Regex
Contains
Does not contain
Is empty
Is not Empty
In List
Not in List

For this scenario, configure the branch as:

Login response status Equals 200

Step 5: Reference the login response

Use Retrieve pre-step data to read a value from an earlier step.

Click the condition value field.
Click the magic wand icon.
Select Retrieve pre-step data.
Choose the login step.
Select its response status.

Apidog uses pre-step references in this format:

{{$.<step id>.response.body.<field path>}}

For example, to retrieve the login token from step 1:

{{$.1.response.body.token}}

Keep these constraints in mind:

Retrieve pre-step data works only in the Tests module.
It resolves only when you run the full scenario.
Running a single step in isolation does not provide data from earlier scenario steps.

For this status-code condition, retrieving the prior step's status is the fastest option.

Alternative: extract a named variable

If you need to reuse a response value across multiple steps or modules, extract it into a variable.

In the login request:

Open Post-processors.
Add Extract Variable.
Use a JSONPath expression such as:

$.token

Save it under a variable name such as token.

You can then use the token later as:

{{token}}

This approach works in both the Tests and APIs modules. For more examples, see how to pass data between test steps.

Step 6: Add the else path

Hover over the If block and click + Else.

You now have two paths to configure:

If: login succeeded

Add the checkout request inside the If block.

If checkout requires authentication, add the login token to the request:

Authorization: Bearer {{token}}

You can also use a pre-step response reference instead of an extracted variable. This is the same bearer-token pattern used by authenticated APIs such as those documented in the Stripe API reference.

Else: login failed

Add a step that makes the failure explicit. Options include:

Sending a request to a logging endpoint.
Sending a notification request.
Adding a custom request with an assertion that always fails.

The resulting workflow is:

if login status == 200:
  create checkout
else:
  report failure

This prevents checkout from running after an invalid login response.

Step 7: Save and run the scenario

Click Save All to persist the scenario. If Apidog shows an unsaved-change dot, save before running.

Then run the full scenario:

Use valid credentials to verify that the If path runs.
Use invalid credentials to verify that the Else path runs.

Variations and advanced flow control

Branch on a response body field

You are not limited to status codes. A branch can evaluate any value you can reference.

For example, your login API might return 200 for a locked account but include account state in the body:

{
  "status": "locked",
  "token": null
}

Reference the field:

{{$.1.response.body.status}}

Then configure a condition such as:

status Equals "active"

Other practical examples include:

Contains for a response message.
Greater than for a balance or stock count.
In List for role-based access checks.

Combine branches with loops

Branches can run inside loops.

For example, a ForEach loop can iterate over product IDs, while a Conditional Branching step skips out-of-stock products:

for each product:
  if product.stock > 0:
    process product
  else:
    skip product

Within loop contexts, Apidog supports references such as:

{{$.<loop step id>.index}}

The loop index starts at 0.

To access the current ForEach element:

{{$.<loop step id>.element.<field path>}}

For a complete iteration walkthrough, see the ForEach loop tutorial.

Stop a loop with Break If

Inside a loop, use Break If condition to stop iterating when a condition becomes true.

For example:

Break If response.status Equals "complete"

You can reposition the element in the loop and add multiple break conditions where appropriate.

Configure loop error handling

Loops include an On Error element at the beginning of the loop. Its location is fixed.

Available behaviors are:

Ignore: continue with the next request.
Continue: skip the remaining requests in the current iteration.
Break execution: end the loop and continue after it.
End execution: stop the entire scenario.

Choose the behavior based on whether one failed item should fail the whole workflow.

Add a Wait step

Use the Wait element when a downstream system needs time to reflect an update.

For example:

POST /orders
Wait 1000 ms
GET /orders/{id}

The delay is measured in milliseconds.

Use scripts for complex logic

If the built-in operators are not enough, use a pre-processor or post-processor script to calculate the result you need.

Inside scripts, do not use {{variable}} syntax directly. Instead, use:

pm.variables.get("$.2.response.body.token")

Update the step ID and field path to match your scenario.

For related workflows, see request chaining and API test orchestration and passing data.

A scenario cannot reference the original test scenario itself. This prevents accidental infinite loops when nesting scenarios.

Automate the workflow with the Apidog CLI

A branching scenario does not need to run only in the Apidog UI. Use the Apidog CLI to execute saved scenarios in CI.

Install the CLI and authenticate:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Run a scenario by scenario ID:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Arguments:

-t: test scenario ID
-e: environment ID
-r: reporter

Use cli for terminal output. Use html or junit to generate pipeline artifacts:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <scenario_id> \
  -e <env_id> \
  -r html,cli

The CLI resolves the branch exactly as the app does: it evaluates the login response, runs the If or Else path, and returns an exit code based on the outcome.

For setup details, see the Apidog CLI installation guide. For CI integration, see the Apidog CLI GitHub Actions guide. To run scenarios on a schedule, see how to schedule API tests in Apidog.

FAQ

What is the difference between Conditional Branching and a loop in Apidog?

Conditional Branching evaluates a condition once and chooses a path. A loop repeats a block of steps.

Use a branch for an either/or decision:

if login succeeds:
  run checkout
else:
  stop checkout

Use a For or ForEach loop to repeat requests across a count or array. See the ForEach loop tutorial for details.

Why is Retrieve pre-step data empty?

Two common causes:

It works only in the Tests module.
It resolves only when you run the entire scenario.

If you run one request by itself, it has no previous scenario response to reference.

Can I branch on a response body field instead of a status code?

Yes. Use a pre-step reference such as:

{{$.1.response.body.status}}

Or extract the value into a named variable. Then evaluate it with operators such as Equals, Contains, or In List.

For data-passing patterns, see how to pass data between test steps.

How do I use a scenario value inside a script?

Scripts do not support direct {{variable}} references. Use:

pm.variables.get("$.2.response.body.token")

Adjust the step ID and response path for your scenario.

Does branching require a paid or self-hosted plan?

The Apidog documentation lists no plan restriction for flow control, conditional branching, loops, or passing data between steps. It also lists no cloud-versus-self-hosted distinction for these features.

Wrapping up

A linear test can tell you that something failed. A branching scenario tells you where it failed and prevents requests from running when their prerequisites are missing.

To implement this pattern:

Add a login request.
Add a Conditional Branching step.
Read the prior response with Retrieve pre-step data or an extracted variable.
Configure the If condition, such as status Equals 200.
Put checkout in the If path.
Put explicit failure handling in the Else path.
Run the same scenario in CI with apidog run.

Try Apidog free and turn straight-line API tests into scenarios that can make decisions.

How to Schedule Automated API Tests in Apidog (Cloud, Runner, and CLI)

Hassann — Wed, 15 Jul 2026 08:59:42 +0000

A passing test suite only helps if it keeps passing. Your checkout flow works today, but a dependency can ship a breaking change at 2 a.m., a certificate can expire over the weekend, or config drift can take down payments on a Sunday. If an angry customer finds it before your tests do, your checks are not doing their job. The practical fix: run API tests on a schedule and alert the team as soon as something fails.

Try Apidog today

Apidog includes a Scheduled Tasks feature for this workflow. Select existing test scenarios, configure a cadence, choose a machine to execute them, and set up alerts. If you are new to unattended checks against live endpoints, start with this primer on API monitoring. For UI-specific details, use the Apidog Scheduled Tasks documentation.

Scheduled Tasks is currently labeled Beta. The number of scheduled runs available depends on your plan.

What Scheduled Tasks do—and what they do not do

A scheduled task runs one or more saved Test Scenarios on a recurring cycle. Common uses include:

Nightly regression tests for core API flows
A staging smoke test every few hours
Weekend health checks for production endpoints
Scheduled checks for authentication, payments, or other critical paths

Each task stores:

The test scenarios to run
The target environment
The schedule
The Runner that executes requests
Notification settings

Scheduled Tasks are not web scrapers or data-collection jobs. They run API test scenarios, including assertions, chained requests, extracted variables, and test data. The output is a pass/fail report for your API tests—not a scraped dataset.

That changes the setup: you do not configure CSS selectors or crawl rules. You select test scenarios you already built and define when and where they run.

Before you start: configure a self-hosted Runner

Scheduled Tasks require a self-hosted Runner.

A Runner is the machine that executes your test suite. When a task fires, Apidog sends the job to the selected Runner. Requests do not run from your desktop client; they originate from the Runner machine.

Good Runner choices include:

An always-on VM
A CI server
A small server inside your VPC
A dedicated monitoring host

Make sure the Runner stays online during the scheduled window.

The runner target currently offers:

Apidog Cloud — marked “coming soon”
Self-hosted Runner

Because Apidog Cloud is not available yet, select a self-hosted Runner for scheduled execution.

Also account for the Runner's network location. A Runner behind a VPN, in another region, or inside a firewalled subnet may receive different responses than your laptop. This is often useful because it tests the API from a realistic network environment, but it also explains why local and scheduled results can differ.

Step by step: create a scheduled task

This example creates a nightly regression suite for an e-commerce API covering signup, product browsing, cart operations, and checkout with Stripe.

1. Open Scheduled Tasks in the Tests module

In the Apidog client:

Open the Tests module.
In the Tests folder tree, select Scheduled Tasks.

This view lists scheduled tasks for the current project and shows what is configured to run.

2. Create the task

Click + New to create a scheduled task.

Set a clear task name and description, for example:

Task Name: Nightly regression - production
Description: Validates signup, catalog, cart, and checkout flows against production.

You can also create folders to group tasks. For example:

Scheduled Tasks
├── Production
│   ├── Nightly regression
│   └── Payment smoke test
└── Staging
    ├── Pre-release smoke test
    └── Contract regression

Tasks can be enabled or disabled at any time, so you can pause a noisy suite without deleting its configuration.

3. Select test scenarios

Under Test Scenario, select one or more scenarios.

For an e-commerce regression task, select scenarios such as:

Signup and login
Browse and add to cart
Checkout with Stripe test card

Each scenario can use its own execution settings:

Environment
Test data
Iterations
Delay
Whether to save requests and responses

If every scenario should use identical settings, enable Use same execution config. This applies one runtime configuration across all selected scenarios.

For most scheduled suites, keep the environment consistent:

Use production for real production monitoring.
Use staging for pre-release smoke tests.

Although a task can use different environments per scenario, a single environment per task is usually easier to operate and troubleshoot.

4. Set the run cycle

Configure the schedule using the run-schedule field. Depending on the UI, this may appear as Run Cycle or Run Mode.

Examples include:

Every Sunday at 11 PM
Every 6 hours
Every 8 hours

Choose a cadence based on risk and test cost:

Use case	Suggested cadence
Production regression suite	Nightly
Staging smoke test	Every 6 hours
Critical health flow	Every few hours
Resource-intensive end-to-end suite	Nightly or weekly

A nightly run is usually a good starting point for broad regression coverage because it catches failures before the next workday without putting unnecessary load on the environment.

5. Choose where the task runs

Set the Runner field to your self-hosted Runner.

Depending on the screen, this may be labeled:

Runs on
Run On
Runs On

All labels refer to the machine that sends the test requests.

If you have multiple Runners, choose the one that best represents the traffic you want to validate. For example, select a Runner in the same VPC as your API if you want to validate internal connectivity.

Remember: every request in the scenario originates from this Runner machine.

6. Enable notifications

Enable Notification so failures reach the team automatically.

Supported channels include:

Slack
Teams
Webhook
Jenkins
Email

For email notifications, project member addresses can auto-complete, and you can manually add non-member addresses such as an on-call inbox.

Choose when notifications fire:

After every run: useful while validating a new task or during an active rollout.
On failures only: best for stable nightly suites, where silence indicates success.

For example, use failures-only notifications for production regression:

Channel: Slack
When to notify: Failures only
Target: #api-alerts

Use every-run notifications temporarily when you need confirmation that the task itself is executing.

7. Save and enable the task

Save the configuration, then enable the task using its toggle.

The task begins running on the configured cadence. Disable it later if you need to pause monitoring during planned maintenance, an outage, or a migration window.

8. Review run history

After each run, the Runner uploads results back to the server.

Open Scheduled Tasks - Run History to inspect:

Pass/fail status
Execution time
Failed assertions
Request and response details, if saved
The time each run occurred

When a Slack or email alert arrives, use Run History to investigate the failing scenario and assertion.

Advanced settings and variations

Once the basic task works, configure variable handling and folder structure carefully.

Variable scope

Apidog provides three levels of variable sharing:

Share only in the current test scenario

Keeps variables isolated to one scenario.
Share across all test scenarios in the current scheduled task

Allows scenarios in the same task to use shared values.
Share across all scheduled tasks in the current scheduled task folder

Lets related tasks inside a folder share variables.

Use the narrowest scope that supports your workflow. For example, avoid sharing an authentication token across unrelated scenarios unless those scenarios explicitly require it.

Variable persistence

To preserve values between scheduled runs, enable Keep variable values on the test scenario design page.

Without this option, each scheduled run starts with fresh variable values.

Enable persistence only when your tests require cross-run state, such as a captured order ID or refreshed token.

Group tasks with folders

Use folders to separate task types:

Scheduled Tasks
├── Production monitors
├── Staging smoke tests
├── Payment checks
└── Pre-release regression

Folders also support the widest scheduled-task variable-sharing scope, which can help related tasks reuse setup data.

Check plan limits before increasing frequency

The number of scheduled runs available depends on your subscription. Before configuring hourly or high-frequency tasks, check your plan limits.

For deeper scheduling patterns, see:

Automate with the Apidog CLI

The Scheduled Tasks UI is one option. You can also run saved scenarios headlessly with the Apidog CLI and let cron or your CI platform provide the schedule.

The CLI does not include a native schedule command. Scheduling happens outside Apidog through cron, GitHub Actions, or another CI scheduler.

Install the CLI, authenticate, and run a scenario against a chosen environment:

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli,junit

The relevant flags are:

Flag	Purpose
`-t`	Test scenario ID
`-e`	Environment ID
`-r`	Reporter format

Available reporters include cli, html, and junit. Combine reporters with commas:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 4471 \
  -e 88 \
  -r cli,junit

Schedule a nightly CLI run with cron

Add a cron entry to run the scenario every night at 2:00 a.m.:

0 2 * * * cd /srv/api-tests && apidog run --access-token $APIDOG_ACCESS_TOKEN -t 4471 -e 88 -r junit >> run.log 2>&1

This command:

Changes into the test directory.
Runs the selected scenario against environment 88.
Produces a JUnit report.
Appends output and errors to run.log.

You can also schedule the command through GitHub Actions. The JUnit output can then feed into existing CI reporting workflows.

For implementation details, see:

FAQ

Can I run scheduled tests on Apidog Cloud today?

Not yet. Apidog Cloud is marked “coming soon,” so use a self-hosted Runner for scheduled execution.

How often can scheduled tasks run?

The cadence is flexible, with examples such as every 6 hours or every Sunday at 11 PM. However, the number of scheduled runs is limited by your subscription plan.

How do I receive alerts only when a test fails?

In the task's Notification settings:

Select a channel: Slack, Teams, Webhook, Jenkins, or Email.
Choose the failures-only notification option.
Save the task.

This keeps channels quiet when tests pass and alerts the team when a failure occurs. Pair it with an API health check for a faster liveness signal alongside deeper regression coverage.

Why do scheduled results differ from local test runs?

Scheduled requests originate from the Runner machine, not your laptop. Its network, region, VPN configuration, and firewall rules can affect API responses.

Why do my variables reset after every run?

Enable Keep variable values on the test scenario design page. Without it, every scheduled run starts with fresh values.

Wrapping up

Scheduled tests turn “we think the API works” into “we know, and we would have heard if it did not.”

Start with this implementation checklist:

Build and validate your test scenarios.
Register a self-hosted Runner.
Create a scheduled task.
Select scenarios and an environment.
Set a run cadence.
Configure failure notifications.
Review Run History when alerts arrive.

For CI-driven scheduling, run the same scenarios with the CLI and schedule them with cron or GitHub Actions.

Download Apidog to set up your first scheduled regression suite.

How to Use Database Queries in API Tests with Apidog (MySQL, MongoDB, Redis)

Hassann — Wed, 15 Jul 2026 06:51:20 +0000

A green status code can lie. Your POST /orders endpoint returns 201 Created, the response body looks correct, and the HTTP assertion passes—but did the row reach the database with the expected status? Did inventory decrement? HTTP-only tests verify what the API reported, not what the system persisted. Query the database to close that gap.

Try Apidog today

Database queries let a scenario seed known data, call an API, and verify the resulting state in one workflow. Apidog supports this with Database Connections and the Database Operation processor, so you can run SQL or NoSQL commands before and after HTTP requests without external scripts. If you need the request-level foundation first, see how to write a test scenario with Apidog. For relational-database fundamentals, MDN’s server-side overview is a useful primer.

What database operations add to API tests

An API test that never checks persistence is a black-box test: it trusts the response. That is often enough for contract validation, but it misses bugs such as:

A status field that was never updated.
A foreign key that references the wrong record.
A soft-delete endpoint that hard-deletes data.
A successful response returned before a write fails or is rolled back.

Database steps add three practical capabilities:

Seed a deterministic starting state so tests do not depend on leftover records.
Assert against persisted state rather than relying only on the response body.
Extract database-generated values for later requests.

In Apidog, configure a reusable connection under Settings > Database Connections, then add a Database Operation as either:

A Pre Processor, which runs before the HTTP request.
A Post Processor, which runs after the HTTP request.

Create a connection once and reuse it across scenarios in the project.

Plan support: MySQL, SQL Server (2014+), PostgreSQL, and Oracle are available on the free plan. ClickHouse, MongoDB, and Redis require a paid plan. The MySQL examples below work on the free tier; the MongoDB and Redis examples require paid access.

Step 1: Create a database connection

Open Settings > Database Connections, then click + New.

Select your database type and provide:

Host, such as db.staging.internal or 127.0.0.1
Port, such as 3306 for MySQL
Username
Password
Database Name, such as shop

If the database is behind a bastion host, expand SSH Tunnel and configure the jump host.

For MySQL, choose an SSL mode:

Prefer: attempts SSL, then falls back if unavailable.
Require
Verify CA
Verify Full

Use the strictest mode supported by your server, then click Save.

MySQL 8 authentication issue

MySQL 8 commonly uses caching_sha2_password. If your connection fails with an authentication error, switch the test user to mysql_native_password:

ALTER USER 'tester'@'%'
IDENTIFIED WITH mysql_native_password BY '...';

See the MySQL reference manual for details about authentication plugins.

Connection credentials are local

Database connection details are stored locally and are not synced to the cloud project. Each teammate must configure their own connection. For team workflows, see sharing database connection settings.

Step 2: Seed test data with a Pre Processor

Assume you are testing order creation. Before calling POST /api/orders, seed a known active customer.

In the request:

Open Pre Processors.
Hover Add Database Processor.
Choose Database operation.
Name the step seed customer.
Select the MySQL connection.
Add an insert statement.

Use environment variables with {{variable_name}} syntax:

INSERT INTO customers (id, email, status)
VALUES ({{customer_id}}, '{{customer_email}}', 'active')
ON DUPLICATE KEY UPDATE status = 'active';

This setup makes the test self-contained:

The customer exists.
The customer is active.
The ID is known before the API request runs.
The scenario does not depend on execution order or existing database contents.

Step 3: Verify persistence with a Post Processor

Now call the API that creates an order:

POST /api/orders
Content-Type: application/json

{
  "customer_id": {{customer_id}},
  "items": [{ "sku": "APRON-01", "qty": 2 }]
}

Capture the returned order ID from the response into order_id using a normal response assertion.

Then add a database check:

Open Post Processors.
- In DESIGN Mode, use the Run tab.
- In DEBUG Mode, use the Request tab.
Hover Add PostProcessor.
Select Database operation.
Name it verify order row.
Choose the database connection.
Run this query:

SELECT id, status, total_cents
FROM orders
WHERE id = {{order_id}};

Database query results are returned as an array of objects. Extract the status from the first result:

Variable Name: db_order_status
JSONPath Expression:

$[0].status

Click Send, then inspect the Console to view the raw database result and extracted variable.

Finally, add an assertion that db_order_status equals pending:

db_order_status == pending

Now a response that returns 201 Created but persists status = 'draft' will fail the scenario.

Step 4: Reuse a database value in a later request

Database extraction is also useful when an API does not return a server-generated value.

For example, creating an order might generate an internal fulfillment_ref that is stored in the orders table but omitted from the API response. Query it after order creation:

SELECT fulfillment_ref
FROM orders
WHERE id = {{order_id}};

Extract the value with:

Variable Name: fulfillment_ref
JSONPath Expression: $[0].fulfillment_ref

Use it in the next request:

GET /api/fulfillments/{{fulfillment_ref}}

This follows the same chaining pattern as HTTP response variables, except the source is the database. See passing data between test steps and API test orchestration and passing data.

MongoDB and Redis: NoSQL variants

MongoDB and Redis use the same Database Operation concept, but their configuration differs from SQL databases. Both require a paid plan. See the Apidog documentation for the complete field reference.

MongoDB

Add a Database Operation and select MongoDB.

Instead of SQL, select an Operation Type:

Find
Insert
Update
Delete
Run Database Command

For CRUD operations, Collection Name is required. Enter JSON in Query Condition:

{ "_id": "65486728456e79993a150f1c" }

Apidog automatically converts a matching ID string to an ObjectId.

When you need BSON-specific types, these helpers are supported:

ISODate(...)
ObjectId(...)
NumberDecimal(...)
NumberLong(...)

Refer to the MongoDB manual for the stored-value mappings. You can configure the connection with either a full connection string or individual host and credential fields.

The SQL workflow documents JSONPath extraction through Extract Result To Variable. MongoDB and Redis documentation does not describe the same extraction mechanism. Use NoSQL operations for setup and state verification, and verify any extraction behavior in the Console before relying on it in a scenario.

Redis

A Redis connection requires:

Host
Port
Password
Database Index

Visual operations support GET, SET, and DELETE.

To verify a cached session:

Select GET.
Set Key to a value such as user:session:123.

For commands not covered by the dropdown, use Run Redis Command:

KEYS user:*

Use this to confirm that an endpoint wrote a cache entry or to clear a key before testing whether the endpoint repopulates it.

Advanced patterns and limits

Iterate through rows

When using a ForEach step, reference the current item with:

{{$.StepID.element.field}}

Replace StepID with the actual loop step number. This is useful when asserting one database row per iteration.

Branch based on a database value

Extract a database status, then route the scenario based on that value. Combine database reads with conditional logic in API test scenarios to take one path for paid records and another for pending records.

Route safely by environment

Create one database connection per environment, such as local and staging. Apidog selects the matching connection when you switch the active environment.

Keep SQL operations straightforward

The visual interface does not support complex operations such as stored procedures. Use direct statements such as:

SELECT ...
INSERT ...
UPDATE ...
DELETE ...

Oracle requires a local client

Oracle requires the Oracle Client to be installed on your machine before Apidog can connect.

Handle database credentials per environment

Never point tests at production accidentally.

Create separate connections for each environment:

local
staging
Any other isolated test environment

Each connection has its own host, credentials, and database name.

When you switch the active environment using the top-right dropdown, Apidog routes database operations to the matching connection automatically:

Select staging: the scenario queries staging.
Select local: the same scenario queries your local database.

The SQL and test steps do not need to change.

Because credentials are stored locally rather than synced into the shared cloud project, production passwords remain outside the shared project configuration.

Run database-backed scenarios in CI with the Apidog CLI

After the scenario passes locally, run it in CI so pull requests validate persistence as well as HTTP behavior.

Install the CLI and authenticate:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Run a scenario by scenario ID and environment ID:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Options:

-t: test scenario ID
-e: environment ID
-r: reporter

Supported reporters include:

cli
html
junit

Use multiple reporters by comma-separating them:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r html,cli

Database connections are local, so your CI runner needs the exported configuration required to reach the target database.

For data-driven execution, see data-driven testing with the Apidog CLI. To run scenarios on a schedule, see scheduling API tests with Apidog.

Frequently asked questions

Which databases are free and which require a paid plan?

MySQL, SQL Server (2014+), PostgreSQL, and Oracle are available on the free plan. ClickHouse, MongoDB, and Redis require a paid plan.

Try the free database integrations first by downloading Apidog.

Can I use a database value in a later request?

Yes. Add a Post Processor with a Database Operation, run a SELECT, and use Extract Result To Variable.

For example:

SELECT fulfillment_ref
FROM orders
WHERE id = {{order_id}};

Extract with:

$[0].fulfillment_ref

Then reference it later:

{{fulfillment_ref}}

For response-based chaining, see passing data between test steps.

Do teammates automatically receive my database connections?

No. Connection credentials are local to each client and are not synced to the cloud. Every teammate configures their own connection.

Why does my MySQL 8 connection fail?

MySQL 8 defaults to caching_sha2_password, which can prevent a connection. Switch the user to mysql_native_password:

ALTER USER ... IDENTIFIED WITH mysql_native_password;

Then reconnect.

Can I run stored procedures?

Not through the visual interface. Use direct SELECT, INSERT, UPDATE, and DELETE statements for database test steps.

Wrap up

Database operations turn an API test from “the response looked right” into “the persisted data is correct.”

A practical workflow is:

Seed a known state with a Pre Processor.
Call the API.
Query the resulting row with a Post Processor.
Assert persisted values.
Extract server-generated database values for downstream requests.
Configure separate connections for local and staging environments.

Start with one request: point a MySQL connection at your development database, create an order, and add a Post Processor that reads the created row back from orders.

Download Apidog to try the free database integrations.

How to Run a Self-Hosted Mock Server on Your Intranet with Apidog

Hassann — Wed, 15 Jul 2026 06:48:36 +0000

Some teams cannot send API traffic to the cloud. Corporate firewalls may block third-party services, compliance policies may require request and response data to stay on infrastructure you control, or the environment may be fully air-gapped. In these cases, even a hosted mock endpoint with fake data is not an option. Apidog supports this setup with a self-hosted runner: you deploy the runner on your own server and serve mock responses from inside your network, while keeping API definitions and mock design in your Apidog project. For broader context, see self-hosted API mock servers and the OpenAPI Initiative.

Try Apidog today

What the self-hosted runner is

The Apidog Self-hosted Runner, officially called the General Runner, is a program you host on a standalone server. It can:

Run scheduled automated tests.
Import API documents.
Serve mock responses.

This article focuses on mock serving.

After you deploy a General Runner and configure its Server Host, Apidog automatically creates a Runner Mock environment in your project. Requests sent through that environment receive responses from your self-hosted runner rather than Apidog cloud mock.

The mock definition and generated data remain the same. Only the machine serving the response changes.

Use the runner when you need one or more of the following:

Outbound traffic to external hosts is blocked or audited.
Compliance policies require request data to remain on internal infrastructure.
Your environment is air-gapped.
You need mock latency measured on your LAN rather than over the public internet.

If your team can access the internet and has no data-location restrictions, Apidog cloud mock is usually simpler because there is no server to deploy.

You need team or project admin permissions to deploy a runner. Runner configuration is managed in Team Resources, which is available to admins.

What you need before you start

The General Runner is distributed as a Docker container. Your host needs Docker 20.10.0 or later; Docker 20.10.13 or newer is recommended.

Verify your Docker version:

docker --version

You also need:

A Linux, macOS, or Windows machine to run the container.
A stable internal IP address or hostname for shared use.
Network access between your Apidog clients, the runner host, and the Apidog service.
Team or project admin permissions.

Configure the rest from Apidog.

Deploy the General Runner

Apidog generates the Docker command for you. Do not create the command manually because it contains a runner token.

1. Generate the deployment command

In Apidog:

Open Home.
Select your team.
Open Resources in the right sidebar.
Choose Deploy General Runner.

Configure the deployment dialog:

Server OS: Select Linux, macOS, or Windows.
Docker Image:
- General includes Node.js 18, Java 21, Python 3, and PHP 8.
- Slim includes Node.js 18 only.
- Custom lets you provide a Dockerfile for additional test-script runtimes.
Exposed Port: Configure Docker port mapping with -p, such as -p 80:4524.
Mounted Data Directory: Configure persistent storage with -v.

Copy the generated command immediately. Apidog displays it only once because it includes your token. If you lose it, generate a new command and token.

2. Run the command on your server

Paste the generated command into a terminal on the runner host.

A typical command looks like this:

docker run -d \
  --name apidog-runner \
  -p 80:4524 \
  -v /opt/apidog-runner/data:/app/data \
  apidog/runner:latest \
  --token <YOUR_GENERATED_TOKEN>

Your actual command will include the token generated by Apidog.

Confirm that the container is running:

docker ps

You should see the runner container and its port mapping. You can also verify this in Docker Desktop.

3. Confirm that the runner registered

Back in Apidog:

Open Team Resources.
Select General Runner.
Click Refresh.

The runner should appear with a Started status.

Runner statuses mean:

Started: The runner is enabled, connected to Apidog, and ready to process tasks.
Stopped: The runner was manually stopped in Apidog and will not process tasks.
Offline: The runner lost its connection to Apidog. Check the container and network connectivity.

Enable Runner Mock

Deploying the container creates the runner agent. Next, point mock traffic at it.

In Team Resources > General Runner, set Server Host to the address where the runner is reachable.

Examples:

http://127.0.0.1:80

http://runner.internal.example.com:80

If you place a TLS-terminating reverse proxy in front of the runner:

https://runner.example.com:443

After you save Server Host, Apidog automatically adds a Runner Mock environment to the project.

Verify it:

Open the project.
Go to Environment Management.
Confirm that Runner Mock appears in the environment list.

Send a request through the self-hosted mock

Assume your internal order-management API has this endpoint:

GET /orders/{orderId}

To use the self-hosted mock:

Open the endpoint in Apidog.
Select Runner Mock from the environment dropdown.
Send the request.

You can also call the runner directly:

curl http://runner.internal.example.com:80/orders/10583

For a well-defined Order schema, the response can contain generated, schema-aware values:

{
  "orderId": 10583,
  "customerEmail": "amelia.turner@example.com",
  "status": "shipped",
  "total": 148.5,
  "currency": "USD",
  "createdAt": "2026-07-14T09:32:11Z"
}

The response is generated and served inside your network. The runner uses the same schema-driven mock behavior as cloud mock.

To return a specific response for a request, add a mock expectation to the endpoint. The runner serves that expectation the same way cloud mock does. For more on generated data, see auto-generating realistic mock data with smart mock. General API mocking concepts apply whether you use cloud mock or a self-hosted runner.

HTTPS, mounts, and deployment details

Use a reverse proxy for HTTPS

The runner does not include built-in HTTPS certificate support or automatic certificate provisioning. To expose the runner over HTTPS, terminate TLS at a reverse proxy such as Nginx.

For example, this Nginx configuration accepts HTTPS traffic and forwards it to a runner listening on port 4524:

server {
    listen 443 ssl;
    server_name runner.example.com;

    ssl_certificate     /etc/ssl/certs/runner.example.com.pem;
    ssl_certificate_key /etc/ssl/private/runner.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4524;
        proxy_set_header Host $host;
    }
}

Set Server Host to:

https://runner.example.com:443

Without a reverse proxy, use an HTTP address such as http://host:port. Do not configure an https:// Server Host unless TLS is terminated before traffic reaches the runner.

See the MDN HTTPS guide for more on HTTPS and TLS termination.

Mount files at the required container paths

If tests or mocks need external files, mount them at the paths expected by the runner:

Use case	Container path
External programs	`/app/external-programs/`
Database connection configuration	`/app/database/database-connections.json`
SSL client certificates	`/app/ssl/ssl-client-cert-list.json`

Use Docker -v mounts so these files persist across container restarts.

Understand redeploy and upgrade behavior

When a new runner version is available, Apidog provides an Upgrade option. You can also use More Actions > Redeploy.

Both operations stop the active container while the replacement starts. Existing scheduled tasks remain configured in Apidog, but live mock serving is interrupted for the duration of the container restart.

Use the Apidog CLI for CI, not mock serving

The General Runner and the Apidog CLI solve different problems:

Tool	Purpose
General Runner	Long-running agent that serves mocks and runs scheduled tasks
Apidog CLI	One-shot test runner for local automation and CI

The CLI does not serve, start, or host a mock server. There is no apidog run mock or apidog mock serve command.

Use apidog run to execute test scenarios, scenario folders, and test suites. The CLI mock command group manages mock expectations as data, but it does not host mock traffic.

A practical workflow looks like this:

Define or update endpoints and schemas in Apidog.
Use Runner Mock to unblock frontend development inside your network.
Run test scenarios against the real backend in CI.

For example:

apidog run -t <scenario_id> -e <env_id> -r html,cli

This runs a test scenario against the selected environment and produces HTML and CLI reports.

Install the CLI with:

npm install -g apidog-cli

The CLI requires Node.js v16 or later. See the Apidog CLI installation guide for apidog login and token setup, then use the Apidog CLI CI/CD guide to run tests on every push.

For the distinction between managing mock definitions and hosting mocks, see mocking APIs from the CLI.

FAQ

Do I need a self-hosted runner if my team can access the internet?

Usually not. Cloud mock is simpler because it requires no infrastructure. Use a runner when outbound traffic is blocked or audited, compliance requires internal data handling, or your environment is air-gapped.

See the Apidog cloud mock guide for the hosted option.

Can the Apidog CLI start a self-hosted mock server?

No. The CLI runs tests with apidog run and manages mock expectations through its mock command group. Mock serving is handled by the General Runner or cloud mock.

Does the runner support HTTPS directly?

No. Put a reverse proxy such as Nginx in front of the runner to terminate TLS, then configure Server Host with the proxy's https:// URL. Otherwise, use http://host:port.

Why does my runner not appear after deployment?

Try these checks:

In Apidog, open Team Resources > General Runner and click Refresh.
Confirm that the container is running:

   docker ps

Verify that the runner host has the required network connectivity.

An Offline status indicates a lost connection. The expected status is Started.

Can multiple teams share one runner?

A runner registers with the team where it was deployed, and Runner Mock environments appear per project. If you need a distributed setup, see sharing mock environments across global teams.

Wrapping up

The General Runner lets you serve Apidog mocks from infrastructure you control while keeping API definitions and mock configuration in your Apidog project.

The implementation path is straightforward:

Deploy the Docker container.
Configure Server Host.
Select the automatically created Runner Mock environment.
Send requests without routing mock traffic through the public internet.

Use self-hosted mock when cloud access is restricted. Otherwise, cloud mock remains the lower-maintenance option. To get started, download Apidog, deploy a runner, and serve your first internal mock response.

How to Host a Shareable Cloud Mock Server with Apidog

Hassann — Wed, 15 Jul 2026 06:16:11 +0000

Your frontend team is blocked: the design is approved, screens are partially built, and the backend API is still a sprint away. A local mock may unblock you temporarily, but it disappears when the machine hosting it goes offline—breaking teammates, QA, and partners who depend on that endpoint.

Try Apidog today

Apidog Cloud Mock provides a hosted URL at mock.apidog.com that remains available independently of your laptop. Frontend, QA, and partner developers can call realistic endpoints before backend implementation is complete. For more background, see what an API mock is and when to use one and MDN’s HTTP request/response overview.

What Cloud Mock solves

Apidog generates a mock endpoint for every API endpoint you define. By default, that mock is local: it runs through your Apidog instance and stops responding when your machine is offline.

That is useful for individual debugging, but it does not work as a shared integration environment.

Cloud Mock hosts the mock independently of any developer machine. Once enabled, the endpoint stays available 24/7, even if every teammate closes Apidog.

Use it to create a shared contract-first workflow:

Define the endpoint and response schema.
Enable Cloud Mock for the project.
Share the generated URL with frontend, QA, or partners.
Let consumers build and test against the contract while backend work continues.

For distributed teams, see sharing mock servers and environments with global teams.

Enable Cloud Mock and get a public URL

Assume you are designing a users service with this endpoint:

GET /users

The endpoint should return a list of customer records. Here is how to make it available as a shared cloud mock.

Step 1: Enable Cloud Mock

In your Apidog project, open:

Project Settings > Feature Settings > Mock Settings

Enable Cloud Mock.

You only need to do this once per project. After Cloud Mock is enabled, endpoints in that project have a cloud mock URL in addition to their local mock URL.

Step 2: Copy the Cloud Mock URL

Open GET /users, then select the Mock tab. Copy the Cloud Mock URL.

It will look similar to this:

https://mock.apidog.com/m1/2689726-0-default/users?apidogToken=GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi

The URL generally follows this structure:

mock.apidog.com/m1/<projectId>-<num>-<env>/<path>

Do not construct these URLs manually. Copy the URL generated by Apidog, since the documentation presents the format by example rather than as a fixed public template.

Step 3: Validate the response in Apidog

Before sharing the endpoint, test it from the same Mock tab.

Send a request to the mock URL and verify that the generated data matches your schema. For example, a GET /users response might look like this:

[
  {
    "id": 1,
    "name": "Amelia Turner",
    "email": "amelia.turner@example.com",
    "city": "Portland"
  },
  {
    "id": 2,
    "name": "Marcus Bell",
    "email": "marcus.bell@example.com",
    "city": "Austin"
  }
]

Apidog uses the field names and types in your schema to generate plausible values. This lets frontend developers work with data that better resembles production responses than placeholder values such as "string".

Step 4: Call the URL from your app

For GET endpoints, paste the full Cloud Mock URL into a browser to quickly inspect the JSON response.

Your frontend can call it like any API endpoint:

curl "https://mock.apidog.com/m1/2689726-0-default/users?apidogToken=GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"

That is the core workflow:

Design the endpoint.
Enable Cloud Mock.
Copy the hosted URL.
Share it with consumers.

Protect Cloud Mock with token authentication

A public mock URL is convenient, but you may not want unrestricted access to mocks for unreleased features or partner integrations.

To require authentication, open:

Project Settings > Feature Settings > Mock Settings

Set the access permission to Token Authentication.

Once enabled, requests must include a valid apidogToken. Requests without one are rejected.

Option 1: Send the token as a query parameter

The copied Cloud Mock URL already uses this format:

curl "https://mock.apidog.com/m1/2689726-0-default/users?apidogToken=GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"

Option 2: Send the token as a request header

Using a header keeps the token out of the URL and reduces the chance of exposing it in URL logs or browser history.

curl "https://mock.apidog.com/m1/2689726-0-default/users" \
  -H "apidogToken: GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi"

For frontend code, this is usually the cleaner option:

const res = await fetch(
  "https://mock.apidog.com/m1/2689726-0-default/users",
  {
    headers: {
      apidogToken: "GdfNrEm6lxM9nDGGIMCWC1OPSiZ6hGOi",
    },
  }
);

const users = await res.json();

Option 3: Send the token in a form body

You can also provide apidogToken as a body parameter in a form-data or x-www-form-urlencoded request.

If you enable token authentication after sharing an unauthenticated URL, coordinate the change with all consumers. They must update their requests with the token before calls begin failing.

Generate region-aware mock data with locales

Mock responses such as this are rarely useful:

{
  "name": "string"
}

Realistic names, addresses, phone numbers, and timestamps help teams find UI issues early, including:

text overflow
address formatting assumptions
non-Latin character rendering
timestamp localization issues
table and card layout problems

Apidog uses Faker.js for generated mock data and supports locale controls.

Use the project language as the default locale

By default, generated data follows the project language configured in:

Project Settings > Basic Settings

For example, setting the project language to French makes generated names and addresses French-flavored without configuring each field individually.

Override the locale for the entire project

To use a locale different from the project language, open:

Project Settings > Feature Settings > Mock Settings

Choose a Faker locale from the locale dropdown.

This setting overrides the Basic Settings language for all mock values in the project.

For example, setting the project mock locale to Japan can help you test names, addresses, and scripts that differ from English-language data. For more on schema-driven generation, see Apidog’s smart mock and how it reads your schema.

Override the locale for one field

For mixed-region datasets, set the locale directly in a mock expression:

{{$person.fullName(locale='ja')}}

This generates Japanese names, such as 田中太郎, for that field while other fields continue using the project-level locale.

The precedence order is:

Field-level locale
Project-level mock locale
Basic Settings language

Use the project-level setting as the default, then add field-level overrides only where needed.

The documentation uses ja as an example but does not publish a complete locale list. Confirm your target locale in the Apidog mock documentation before depending on it. Faker’s locale conventions are documented in the Faker.js localization reference.

Configure time zones too

Mock settings also include a project-level time zone control. You can override the time zone per field with the timeZone parameter in a mock expression.

Use this when generating fields such as createdAt, updatedAt, or scheduled event timestamps. It helps ensure mock timestamps match the region your UI is simulating.

Combined locale and time-zone settings let you model a Japanese user base, a German user base, or a mixed international dataset from the same API schema. See practical API mocking use cases for additional scenarios.

Cloud Mock vs. self-hosted mock servers

Cloud Mock is the hosted option. It is useful when you want a shared endpoint without running infrastructure yourself.

Use a self-hosted mock service when your organization has requirements such as:

data residency restrictions
internal-only test environments
policies against routing test traffic through a vendor cloud

The trade-off is simple:

Option	Best for	Trade-off
Cloud Mock	Fast setup and always-on shared URLs	Hosted by Apidog
Self-hosted mock	Infrastructure and traffic control	You operate the service

For self-hosting details, see self-hosting the Apidog mock server. For a broader comparison, see online API mocking tools.

The Cloud Mock and locale documentation does not state a specific plan requirement. Check availability in your workspace rather than relying on a blog post for plan details. You can Download Apidog and test the workflow in your account.

Keep mock contracts current with the Apidog CLI

Cloud Mock itself is a hosted capability: Apidog generates responses from your endpoint schema and serves them through its hosted mock engine.

The Apidog CLI does not start or host a mock server. Its role is to help keep the API definitions that drive your mocks accurate.

A practical workflow looks like this:

Create or update endpoint schemas in your project.
Let Cloud Mock generate responses from the updated schema.
Build frontend features against the mock URL.
Implement the backend against the same contract.
Run saved API test scenarios against the live backend in CI.

When an AI coding agent such as Cursor or Claude Code updates an endpoint schema, the Cloud Mock response can reflect the changed contract without manually editing mock payloads.

Once the real backend is available, run a saved Apidog scenario from the CLI:

apidog run -t <scenario_id> -e <env_id> -r cli

This command runs a saved test scenario against an environment and reports the results.

Copy the generated command from your Apidog scenario instead of assembling -t and -e values manually. For pipeline integration, see running Apidog in a CI/CD pipeline.

FAQ

Does the Cloud Mock URL work after I close Apidog?

Yes. Cloud Mock is served from Apidog’s infrastructure, so it remains available 24/7 even when your computer is offline.

Can I open a Cloud Mock URL in a browser?

For GET requests, yes. Paste the full URL, including the apidogToken query parameter, into the browser to view the JSON response.

For other HTTP methods—or to avoid exposing tokens in URL history—use curl, Postman, Apidog, or your application client and send the token as a header.

What happens when a request does not include the token?

When Token Authentication is enabled, requests without a valid apidogToken are rejected.

Provide the token through:

a query-string parameter
a request header
a form request body parameter

How do I generate mock data for a specific country?

Choose one of these levels:

Set the project language in Basic Settings.
Set a project-wide Faker locale in Feature Settings > Mock Settings.
Set a field-level locale in a mock expression.

For example:

{{$person.fullName(locale='ja')}}

Field-level settings override project-level settings, and project-level settings override the Basic Settings default. See the smart mock walkthrough for schema-aware generation details.

Should I use Cloud Mock or a headless mock tool?

Use Cloud Mock when you need a hosted, low-maintenance endpoint connected to your API design.

If you need mocks embedded in an automated build with no GUI workflow, review headless API mock tooling. Most tools in this space build on API contracts, often using the OpenAPI Initiative specification.

Wrapping up

A mock that runs only on your laptop unblocks one developer. Cloud Mock creates a shared mock.apidog.com endpoint that frontend developers, QA engineers, and partners can use while backend implementation is still in progress.

Use Cloud Mock to:

share a stable mock URL
protect endpoints with token authentication
generate locale-aware test data
keep frontend work moving from the API contract
validate the eventual backend with tests tied to the same project

Define the endpoint, enable Cloud Mock, share the URL, and let frontend work continue without waiting for the backend. Download Apidog to create your first shareable cloud mock.

How to Return Conditional Mock Data in Apidog (Custom Rules and Mock Scripts)

Hassann — Wed, 15 Jul 2026 06:10:55 +0000

Smart mock creates a fake API in seconds. It reads your endpoint schema and returns plausible data: realistic emails, sensible timestamps, and usable names. For most frontend work, that is enough to unblock development.

Try Apidog today

But some cases require request-aware behavior. You may want /login to return 200 for a known user and 401 for everyone else. Or /orders/{id} to return a shipped order for one ID and a cancelled order for another. You may also need to force a 500 so error handling is tested before production.

Smart mock returns one generated response shape per endpoint, so it cannot branch on the incoming request. This guide shows how to fill that gap with:

Mock expectations for rule-based conditional responses.
Mock scripts for logic that fixed rules cannot express.

For background, see the API mocking overview. This tutorial uses Apidog and follows the contract-first workflow described by the OpenAPI Initiative.

What conditional mocking means

A conditional mock is a rule:

When the request looks like this, return that response.

Apidog provides two layers for mocking.

Field-level customization inside an endpoint schema

Use fixed values or dynamic Faker.js expressions. This controls individual field values, but the endpoint still has one response shape.
Full-response mock expectations

An expectation is a named rule with optional conditions, a response body, status code, headers, and delay.

An expectation with no conditions always returns its configured response. An expectation with conditions responds only when the request matches. By combining expectations, you can return:

A different body for each path parameter.
An error when a required header is absent.
A specific status code for a known request body.
A fallback response for every other request.

Field-level dynamic values first

Before adding request-based branches, configure dynamic values for a single response shape.

In an endpoint schema, string fields can use Faker.js expressions in the format {{$category.method}}. Apidog resolves these expressions on every mock call using the types declared in your JSON Schema.

{
  "id": "{{$number.int(min=1000,max=9999)}}",
  "customer": "{{$person.fullName}}",
  "email": "{{$internet.email}}",
  "product": "{{$commerce.productName}}",
  "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
  "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}

Parameterized methods let you constrain generated values:

{{$number.int(min=1000,max=9999)}} generates IDs in a known range.
{{$date.between(...)}} constrains dates and output format.
You can combine static text and multiple expressions in one field.

Apidog also supports configurable mock locales for region-specific names, addresses, and phone numbers. See the Faker.js reference in Apidog for available methods.

This is Smart mock territory: values are dynamic, but the response is not conditional. To branch based on the request, use expectations.

Walkthrough: return `200` or `401` from `POST /login`

Assume POST /login accepts this JSON body:

{
  "username": "alice@example.com",
  "password": "whatever"
}

The desired behavior is:

alice@example.com receives 200 and a token.
Every other user receives 401.

1. Open the expectation list

The UI location depends on your working mode:

In DEBUG (Request-first) mode, open the endpoint and select the Mock tab.

In DESIGN (Design-first) mode, open the endpoint and select the Advanced mock tab.

Both views open the same expectation list. If needed, download Apidog and create or import a /login endpoint first.

2. Add the success expectation

Click New expectation and configure the following:

Expectation name: login-success
Condition type: body parameter
Name: username
Condition: equals
Value: alice@example.com

For JSON request bodies, body conditions use the JSON path entered in the name field. For nested properties, use dot notation such as user.email.

Set Response data to:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "alice@example.com",
    "role": "member"
  }
}

Save the expectation. The default HTTP status is 200, so no additional status configuration is required.

3. Add the catch-all failure expectation

Create another expectation:

Expectation name: login-failure
Conditions: none

Leaving conditions blank makes this rule a catch-all. Set Response data to:

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect."
}

Open the expectation’s More tab and set:

HTTP Status Code: 401

The More tab also lets you configure:

Response Delay in milliseconds, defaulting to 0.
Custom response headers.

For example, set a 400 ms delay to verify that your loading UI appears during login.

4. Put expectations in the correct order

Expectations run from top to bottom, and the first matching rule wins.

Order the rules like this:

login-success
login-failure

The success rule must be first. If the blank-condition failure rule comes first, it matches every request and the success rule never runs.

Test both responses using the endpoint’s mock URL:

# Known user -> 200 with a token
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"whatever"}'

# Any other user -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"stranger@example.com","password":"whatever"}'

Walkthrough: return different `/orders/{id}` bodies

Path parameters are another common conditional-mocking use case.

For example, configure /orders/{id} so that:

/orders/5001 returns a shipped order.
/orders/5002 returns a cancelled order.
Any other ID returns a generic pending order.

Create one expectation for each state.

Shipped order

Create an expectation named order-shipped:

Condition type: path parameter
Parameter: id
Condition: equals
Value: 5001

Use this response body:

{
  "id": 5001,
  "status": "shipped",
  "total": 129.9,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}

Cancelled order

Create an expectation named order-cancelled:

Condition type: path parameter
Parameter: id
Condition: equals
Value: 5002

Use this response body:

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}

Add a fallback

Add one final expectation with no conditions. Return a generic pending order so unknown IDs still get a valid response.

Place the rules in this order:

order-shipped
order-cancelled
Generic pending-order fallback

You can combine condition types. For example, add both a path parameter condition and a header condition. Apidog combines multiple conditions with AND logic, so every configured condition must match.

Conditions can target:

Request body parameters
Path parameters
Query parameters
Headers
Cookies
IP addresses

Force error states on demand

You do not need a failing backend to test frontend error handling.

To force a 500 response, add an expectation that matches a client-controlled header:

Header: X-Mock-Scenario
Condition: equals
Value: server-error
HTTP Status Code: 500

Set the response body to:

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "Something went wrong on our end. Please retry."
}

Now the endpoint can return its usual 200 response by default and return 500 only when the client sends:

X-Mock-Scenario: server-error

Use the same pattern for other states:

404 for missing resources
429 with a Retry-After response header
503 for temporary unavailability

If you validate these cases in tests, pair this approach with API assertions.

In shared projects, each expectation can be independently enabled or disabled for local and cloud mock environments. For example, keep a forced 500 rule enabled locally but disabled in the cloud mock used by teammates.

When expectations are not enough: mock scripts

Expectations are declarative: they match requests and return predefined responses. They do not compute values.

Use a mock script when the response must be derived from the incoming request, such as:

Summing order line items.
Calculating tax.
Changing response shape based on several inputs.
Echoing request headers into the response.

Mock scripts are JavaScript and run in the Mock Script section at the bottom of the Mock tab.

The runtime exposes two globals:

$$.mockRequest for reading the incoming request.
- getParam(key)
- headers
- cookies
- body
- formdata
- urlencoded
$$.mockResponse for changing the outgoing response.
- setBody()
- setCode()
- setDelay()
- json()
- headers
- code

For example, this script calculates an order total from posted line items and returns the caller’s currency header:

const body = $$.mockRequest.body;
const items = body.items || [];

const subtotal = items.reduce((sum, item) => {
  return sum + item.price * item.quantity;
}, 0);

const currency = $$.mockRequest.headers["x-currency"] || "USD";

$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
  orderId: Math.floor(Math.random() * 90000) + 10000,
  currency: currency,
  subtotal: subtotal,
  tax: Number((subtotal * 0.08).toFixed(2)),
  total: Number((subtotal * 1.08).toFixed(2))
});

The execution flow is:

Smart mock generates an initial response.
The script reads $$.mockRequest and the current $$.mockResponse.
The script applies custom logic.
The script calls setBody(), setCode(), setDelay(), or modifies headers.
Apidog returns the final response.

Use the MDN JavaScript reference when you need more complex array, date, or object logic.

Important: scripts do not run with expectations

Mock scripts work only with Smart mock.

They do not apply to:

Mock expectations
Response examples

If an expectation matches a request, the mock script does not run.

Choose one approach per endpoint:

Use expectations for fixed, rule-based branching.
Use mock scripts for computed output built on Smart mock.

How mock priority works

For every mock request, Apidog resolves the response in this order:

Evaluate expectations from top to bottom

The first expectation whose conditions all match wins. Its response is returned immediately.
Fall back to Mock method priority

If no expectation matches, Apidog uses the priority configured in:

   Project Settings → Feature Settings → Mock Settings

This is where Smart mock, including any attached mock script, generates the response.

Use this mental model:

Specific rules first, generated data second.

Put the most specific expectations first, place a blank-condition fallback at the bottom when you need a guaranteed response, and let Smart mock handle the remaining cases.

For more examples, see the API mocking use cases guide.

Gotchas to check before shipping

Keep these constraints in mind:

Parameter conditions do not support {{variables}}. Apidog project and environment variables are unavailable in mock expectations, so use literal values.
Body-parameter conditions support JSON only. Use JSON paths in the condition name field.
The request body format in the condition must match the API specification. For a form-data endpoint, configure a form-data condition rather than a JSON condition.
Mock scripts have no logging function.
The pm object is unavailable in mock scripts because they run in a different environment from test scripts.
Apidog variables cannot be used inside mock scripts, so keep script logic self-contained.

The docs do not describe plan gating for these features. The local-versus-cloud difference is functional: expectations can be toggled independently in each environment.

Automate the workflow with the Apidog CLI

Mocking itself is a GUI and cloud capability. The mock engine serves endpoints through local and cloud mock URLs; there is no CLI command to start a running mock server.

The Apidog CLI helps manage the API resources that mocks are generated from.

Because mock responses come from endpoint schemas, mock accuracy depends on spec accuracy. The CLI and AI coding agents that use it—such as Cursor, Claude Code, Trae, and Codex—can create and update endpoints and schemas in a project.

A practical workflow looks like this:

Update the API contract in code.
Sync the contract to the project.
Let the mock output reflect the updated schema.
Run test scenarios in CI against the real backend.

Run a scenario headlessly with:

apidog run -t <scenario_id> -e <env_id> -r cli

This executes test scenarios and reports results, letting the mock contract and backend verification use the same source of truth.

See the Apidog CLI installation guide for setup and the Apidog CLI in GitHub Actions guide for CI integration.

FAQ

Why is my expectation ignored even though the condition looks correct?

Check ordering and request format. Expectations run top to bottom, so a broad blank-condition expectation above a specific one will match first. Also verify that the condition uses the request format defined in the API spec: JSON paths for JSON bodies and form-data placement for form endpoints. Review the API mocking overview if needed.

Can I use a mock script and a mock expectation for the same response?

No. Mock scripts only run with Smart mock. They do not run for mock expectations or response examples. Use expectations for rule-based branches and scripts for computed responses.

How do I return 401 or 500 without breaking the default 200 response?

Create a dedicated expectation with a condition controlled by the client, such as a header. In the expectation’s More tab, set the HTTP status code. The default response remains 200, and the error response is returned only when the condition matches.

Can conditions use environment variables?

No. Apidog {{variable}} values are unavailable in mock expectations, and parameter conditions do not support {{variables}}. Use literal condition values.

What happens when no expectation matches?

Apidog falls back to the Mock method priority configured under Project Settings → Feature Settings → Mock Settings. Smart mock then generates a response from the schema. Add a blank-condition expectation when you need a specific fallback response instead.

Wrapping up

Smart mock handles generated schema-based data. Mock expectations handle request-aware behavior:

200 for a known user and 401 for everyone else.
Different order bodies for different IDs.
A forced 500 for error-state testing.

Use mock scripts only when you need computed output that declarative rules cannot express. Remember the priority order: matching expectations run first, and Smart mock is the fallback.

Download Apidog to build your first conditional mock.

How to Mock an API in Apidog Without Writing Any Code

Hassann — Wed, 15 Jul 2026 06:02:00 +0000

Your frontend team is blocked: GET /users and GET /orders are not ready, but the UI needs realistic data for lists, pagination, loading states, and empty states. Hand-maintained JSON fixtures work briefly, then drift from the real API contract. If you already have an API specification, Apidog can generate a mock directly from each endpoint’s response schema with no mock-server code or configuration.

Try Apidog today

This feature, Smart Mock, uses property names and schema types to generate plausible values. For example, a name property can return a realistic name, while email returns an email-shaped value. This guide shows how to mock two e-commerce endpoints, call their mock URLs, control generated values, and understand response priority. For background, see what API mocking is and how it works and the JSON Schema documentation.

What Smart Mock does

Apidog supports several ways to generate mock responses:

Smart Mock: generates data automatically from the API response schema.
Response Example: returns an example defined in the endpoint specification.
Custom Response: returns a manually configured response.
Conditional Mocking: returns different responses based on request parameters.
Mock Scripts: generates values related to the incoming request.

Smart Mock is the zero-configuration option. Add a response schema to an endpoint, and Apidog fills its properties with generated data. If an endpoint does not have a predefined response example, Smart Mock can act as the fallback instead of returning an empty result.

For frontend work, this means the API schema becomes the source of truth for both the contract and the mock. Update a field in the schema, and the mock updates with it.

Prerequisite: define a response schema

Smart Mock requires a response definition on the endpoint.

If you design APIs in Apidog, add a response schema under the endpoint response definition. If you import an OpenAPI document, response schemas typically import with the endpoints.

Without a response schema, Smart Mock has no structure to generate from.

To use Local Mock, install the Apidog desktop client. Local Mock runs on your machine and is not available in Apidog Web. Download Apidog to follow along.

Step-by-step: mock `GET /users` and `GET /orders`

Use a small store API as an example.

Step 1: Define `GET /users`

Create a GET /users endpoint and add a response schema such as:

{
  "id": 1024,
  "name": "Amara Osei",
  "email": "amara.osei@example.com",
  "phone": "+1-415-555-0148",
  "createdAt": "2026-03-11T09:24:00Z",
  "isActive": true
}

Make sure the schema declares property types:

id: integer
name, email, phone: string
createdAt: string, optionally with a date-time format
isActive: boolean

Step 2: Define `GET /orders`

Create GET /orders with an array response:

[
  {
    "orderId": "ORD-58210",
    "userId": 1024,
    "total": 84.5,
    "currency": "USD",
    "status": "shipped",
    "createdAt": "2026-05-02T14:03:00Z"
  }
]

Use explicit types for every property. Smart Mock uses both property names and schema constraints to choose generated values.

Step 3: Copy the mock URL

Each endpoint receives a mock URL automatically.

In DESIGN mode, find it in the endpoint’s API tab.
In DEBUG mode, find it in the Mock tab.

Use Click to copy to copy the URL.

The copied value is only the URL. When calling non-GET endpoints, set the HTTP method and request body in your client.

A Local Mock URL uses 127.0.0.1:4523. In path mode, it looks like this:

http://127.0.0.1:4523/m1/{projectID}-{versionNo}-{serverNo}/users

Apidog starts Local Mock automatically while the desktop client is open.

You can also target a specific endpoint using ID mode:

http://127.0.0.1:4523/m2/{projectID}-{versionNo}-{serverNo}/{endpointId}

Step 4: Call the mock

Call GET /users with curl:

curl http://127.0.0.1:4523/m1/1234567-0-0/users

Smart Mock can return a response similar to:

{
  "id": 3187,
  "name": "Diego Marchetti",
  "email": "diego.marchetti@example.net",
  "phone": "+1-628-555-0113",
  "createdAt": "2026-01-27T18:41:22Z",
  "isActive": true
}

The name and email values are generated through property-name matching rather than random strings. Refresh the request to generate new dynamic values and test how the UI handles different content lengths and values.

Call the orders endpoint the same way:

curl http://127.0.0.1:4523/m1/1234567-0-0/orders

You now have an array of generated order objects for an order-list UI.

How Smart Mock chooses values

Smart Mock uses a three-level priority order for each property:

Mock Field
Property Name Matching
JSON Schema defaults and constraints

1. Mock Field

A property-level Mock Field has the highest priority.

Use one of these input types:

Fixed value: always return the same value.
Faker statement: return varied generated values.

For example, use a fixed value for a constant currency:

USD

Or configure a Faker statement for status to return values such as:

shipped
pending
delivered

2. Property Name Matching

If no Mock Field is configured, Smart Mock matches property names against built-in wildcard or regular-expression rules.

That is why fields such as email and createdAt can receive appropriate generated values. You can review or add rules in Mock Settings.

3. JSON Schema

If a property has no Mock Field and no matching property-name rule, Smart Mock falls back to its schema type and constraints.

For example, a string property with no matching name or extra constraints receives a generic string value.

Smart Mock respects JSON Schema constraints, including:

enum
string length
numeric minimum and maximum values
array minItems and related length constraints

For example:

{
  "type": "string",
  "enum": ["pending", "shipped", "delivered"]
}

A status field with this schema only returns one of those three values.

You can also select mock locales to generate regionalized data. For example, switching to a Japanese locale changes generated names and addresses to match that format.

Fixing incorrect Smart Mock values

Smart Mock is schema-driven inference, so some field names may need more guidance.

For example:

sku may fall back to a generic string.
total may be generated as a number outside the range your UI expects.
A domain-specific identifier may not match a built-in name rule.

Apply these fixes in order.

Tighten the schema

Start by expressing the rule in JSON Schema.

For example:

{
  "type": "number",
  "minimum": 0,
  "maximum": 10000
}

Use an enum for known states:

{
  "type": "string",
  "enum": ["pending", "paid", "shipped", "delivered"]
}

Use a pattern for identifiers:

{
  "type": "string",
  "pattern": "^SKU-[A-Z0-9]{8}$"
}

Schema constraints keep generated output within the expected shape without requiring custom mock values.

Set a Mock Field

Use a Mock Field when schema constraints are not enough.

Use a Fixed value when a property must never change:

USD

Use a Faker statement when you need controlled variation.

Apidog’s Faker support follows ideas similar to the Mock.js library. See the guide to using Faker in Apidog for expression syntax.

Add a Property Name Matching rule

If the same field appears across multiple endpoints, add a reusable rule instead of configuring each property separately.

Go to Settings.
Open General Settings.
Open Feature Settings.
Open Mock Settings.
Click New.
Define a field-name condition and mock expression.

For example, add a rule for sku so every matching property uses your defined SKU pattern rather than a generic string.

Mock response priority: which response wins?

An endpoint can have a Mock Expectation, a Response Example, and Smart Mock available. Apidog resolves them using the Default mock method setting in Project Settings → Mock Settings.

Available modes:

Smart Mock First: Mock Expectation → Smart Mock
Response example first: Mock Expectation → Response Example → Smart Mock

Read the order from left to right.

Under the default Smart Mock First setting, Apidog first checks for a matching Mock Expectation. If none matches, Smart Mock generates the response.

Under Response example first, Apidog checks a Response Example before falling back to Smart Mock.

A matching Mock Expectation always has the highest priority. For example, you can configure a conditional 404 response when userId=9999, and it will override the other response methods. See mocking conditional API responses in Apidog for a parameter-driven workflow.

Local Mock, Cloud Mock, and Runner Mock

Smart Mock defines how a response is generated. Local, Cloud, and Runner Mock define where it runs.

Local Mock runs through the Apidog desktop client on your computer. It is reachable only while the client is open and listens on 127.0.0.1:4523. To access it from another device on your local network, use your machine’s LAN IP. It is not available in Apidog Web.
Cloud Mock runs on Apidog servers and is available 24/7. Enable it in environment management when teammates or deployed previews need access. Its URLs use https://mock.apidog.com with the same m1 and m2 path formats. It is intended for testing rather than production traffic.
Runner Mock is self-hosted on your team infrastructure, which is useful when the mock must stay within your own network.

Use:

Local Mock for individual frontend development.
Cloud Mock for shared or remote testing.
Runner Mock for self-hosted internal environments.

For more context, see the comparison of online API mocking tools and the Apidog Cloud Mock guide.

Routing gotchas

Keep these rules in mind when a mock endpoint does not route as expected.

Start endpoint paths with `/`

Use paths such as:

/orders

A complete URL that does not begin with / does not use the mock environment. A path without a leading slash only works in ID mode.

Disambiguate duplicate method-and-path endpoints

If two endpoints share the same HTTP method and path, path mode cannot distinguish them automatically.

Add the endpoint ID as a query parameter:

?apidogApiId={endpointId}

Refresh to regenerate dynamic data

Dynamic mock data regenerates when you refresh the request. If you receive the same generated body repeatedly, check whether your API client, browser, or UI is showing a cached response.

Automate contract checks with the Apidog CLI

The Apidog CLI does not start or host a mock server. Local, Cloud, and Runner Mock serve the responses.

The CLI helps keep the schema behind Smart Mock accurate as the API evolves. Because Smart Mock is generated from endpoint schemas, updating the specification updates the generated mock output.

The CLI and AI coding agents such as Cursor, Claude Code, Trae, and Codex can create and update endpoints and schemas in the project. Once frontend work is unblocked, run the project’s test scenarios in CI against the real backend using the same API contract.

apidog run -t <scenario_id> -e <env_id> -r html,cli

Install and authenticate:

npm install -g apidog-cli
apidog login --with-token <your-token>

The CLI requires Node.js v16 or later. See running Apidog in a CI/CD pipeline for setup details.

FAQ

Do I need to write code to use Smart Mock?

No. Define an endpoint response schema and Smart Mock generates data automatically. Use a Faker statement or mock script only when you need to override a specific value. See the mock API overview for the core concepts.

Why is my mock URL returning nothing?

First, verify that the endpoint has a response definition. Smart Mock needs a response schema. Also confirm that the path starts with / and, for Local Mock, that the Apidog desktop client is open.

How do I return a fixed value instead of generated data?

Set the property’s Mock Field to a Fixed value. Mock Fields have higher priority than property-name matching and schema defaults.

Can teammates access a mock running on my laptop?

Only over your local network and only while the Apidog client is running. Local Mock listens on 127.0.0.1:4523. For always-on shared access, enable Cloud Mock at https://mock.apidog.com.

Which response wins when both a Response Example and Smart Mock exist?

It depends on the Default mock method:

Smart Mock First uses Smart Mock after no Mock Expectation matches.
Response example first uses the Response Example before Smart Mock.

A matching Mock Expectation overrides both.

Wrap up

Smart Mock turns a response schema into a working API mock without hand-writing fixture files. Define the response schema, copy the endpoint mock URL, and call it from your frontend. When generated data needs adjustment, tighten the JSON Schema, configure a Mock Field, or add a reusable property-name rule.

How to Let an AI Agent Update Your API Spec with the Apidog CLI

Hassann — Wed, 15 Jul 2026 03:22:38 +0000

Editing an API spec by hand is error-prone: rename a field, add an enum value, or change a required flag, and every dependent endpoint must remain valid. With the Apidog CLI, an AI agent can make these changes with guardrails: validate before writing, work in an isolated branch, and submit changes for review.

Try Apidog today

This is the mutation companion to letting an agent create API documentation. Documentation generation is additive and relatively low-risk. Updating an existing API contract needs a safer workflow.

What “update the spec” means in the CLI

An Apidog project contains endpoints and data schemas. You typically update a spec with one of these commands:

endpoint update: Change a path, parameter, request, or response.
schema update: Change a data model referenced by endpoints.
import: Reconcile an entire OpenAPI file with the project.

Before giving an agent access to these commands, establish two rules:

update is a full replacement, not a patch.
The agent should work in an isolated AI branch.

Critical behavior: `update` replaces the full object

Apidog CLI update commands are not JSON Patch operations.

If you submit only one item from a parameters array, the CLI does not merge that item into the existing array. It replaces the entire array with the value you submitted. Any omitted parameters are removed.

Use a full read-modify-validate-write loop every time:

# 1. Fetch the complete current resource
apidog endpoint get <endpointId> --project <projectId>

# 2. Edit the complete structure locally.
# Keep every field that should remain unchanged.

# 3. Get the payload schema and validate the complete object
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. Write the complete object back
apidog endpoint update <endpointId> --project <projectId> --file ./endpoint-full.json

Put this directly in the agent instructions:

Never send a partial object to update. Always fetch the full resource, modify it, validate it, and send it back as a complete object.

Skipping get can silently remove fields. Running cli-schema validate before writing catches malformed payloads locally.

Safe workflow: use an AI branch

Avoid granting an agent direct write access to main when starting out. Use an AI branch instead.

An AI branch isolates agent changes from the source branch. Nothing reaches main until you review and merge it.

Step 1: Create an AI branch

apidog branch create --project <projectId> --type ai \
  --from main --name "ai/20260713-from-main-refund-fields"

Use a name that makes the source and purpose obvious:

ai/YYYYMMDD-from-source-feature

The --from branch must be main or a normal sprint branch, not a general branch.

An AI branch with no differences from its source is automatically archived after 24 hours, which keeps abandoned experiments from accumulating.

Step 2: Import existing resources into the branch

An AI branch starts empty. It does not automatically clone all resources from its source branch.

Before an agent can modify an existing endpoint or schema, import that resource using pick-to:

apidog branch pick-to --project <projectId> --type ai \
  --from main --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>

Use pick-to only for existing resources the agent needs to edit or delete. Resources created from scratch on the AI branch do not need to be picked first.

Step 3: Run the full update loop on the AI branch

Point each command to the branch:

apidog endpoint get <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

apidog endpoint update <endpointId> --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json

The agent can make changes, validate them, and retry as needed without modifying main.

Step 4: Review and merge

AI branch changes are not merged automatically. Review the diff first.

For protected targets, use a merge request rather than a direct merge:

apidog merge-request --help

apidog branch merge --project <projectId> --type ai \
  --from "ai/20260713-from-main-refund-fields" \
  --to main --endpoint-ids <ids>

A direct CLI merge requires direct-edit permission on both source and target branches. If main is protected, open a merge request and approve it in the Apidog client.

Worked example: rename a schema field safely

Suppose you need to rename amount to amountCents in a Refund schema and change the type to an integer.

Tell the agent:

Rename the amount field on the Refund schema to amountCents and make it an integer.

First, fetch the complete schema from the AI branch:

apidog schema get <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields"

Then update the full jsonSchema, preserving properties that are not changing:

{
  "name": "Refund",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amountCents"],
    "properties": {
      "orderId": { "type": "string" },
      "amountCents": { "type": "integer" },
      "reason": { "type": "string" }
    }
  }
}

Do not send only the changed property. Send the complete schema so orderId and reason remain intact.

Validate and update the AI branch:

# Validate the complete payload
apidog cli-schema validate schema-create --file ./refund-full.json

# Update the schema on the AI branch
apidog schema update <refundSchemaId> --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json

Review the resulting diff, confirm that only the intended field changed, and then merge it.

Require breaking-change detection before merging

Renaming a required field is a breaking change. Clients sending amount will fail validation after the change.

Make the agent classify each change before it opens or completes a merge:

Before merging any spec change, classify it:
- Non-breaking (new optional field, new endpoint, loosened constraint) → summarize and proceed to merge-request.
- Breaking (renamed/removed field, new required field, tightened type) → STOP.
  Report the breaking change and the affected endpoints, and wait for explicit human approval.

The AI branch makes this checkpoint meaningful: the change remains isolated until a human approves it.

Updating from an OpenAPI file

When the change already exists in an OpenAPI file—for example, generated from code or supplied by another team—import it into the AI branch instead of applying individual field updates:

apidog import --project <projectId> --format openapi --file ./openapi.json \
  --branch "ai/20260713-from-main-refund-fields"

import supports OpenAPI 3.x, Swagger 2.0, Postman, and more. Import into an AI branch first so you can inspect the resulting changes before they reach main.

After merging, export the reconciled spec to verify the result:

apidog export --project <projectId> --format openapi \
  --oas-version 3.1 --output ./openapi.json

Use this approach when the source of truth lives outside Apidog and you are syncing it in. Use endpoint update or schema update when Apidog is the source of truth and the change is surgical.

Roll back an unwanted agent change

An AI branch makes rollback simple. If you reject the changes, do not merge them. Archive the branch:

apidog branch archive "ai/20260713-from-main-refund-fields" \
  --project <projectId> --type ai

Because main was never modified, no hand-reversal is required. The branch is your undo button.

Permissions

If an update or import command is blocked, External AI Edit Permissions may be disabled for the project.

The AI branch workflow is designed for this situation: let the agent edit an isolated branch, then approve the merge manually.

To grant direct edits instead, configure the setting in:

Project Settings → Feature Settings → AI Feature Settings

This setting is available in Apidog client 2.8.32+.

When an agent encounters a permission restriction, have it report the issue rather than silently attempting a workaround.

Common snags

Partial update removed fields

update replaces rather than merges. Fetch the full object, modify it, validate it, and write the complete payload back.

The agent cannot find a resource on an AI branch

AI branches start empty. Run pick-to before editing an existing endpoint or schema.

The AI branch was created from the wrong source

The --from branch must be main or a sprint branch, not a general branch.

Validation was skipped

Run apidog cli-schema validate before every write. It catches malformed payloads before the agent makes an API call.

A breaking change was merged without review

Require the agent to classify changes and stop on renamed or removed fields, newly required fields, and tightened types.

FAQ

Can an agent edit `main` directly?

Yes, if you enable External AI Edit Permissions. However, AI branches are safer because changes do not reach main until you approve a merge. Reserve direct edits for low-risk, high-trust automation.

What is the difference between `branch merge` and `merge-request`?

branch merge writes changes immediately and requires direct-edit permission on both branches.

merge-request creates a reviewable request, which is the better option when main is protected.

Does the agent need the Apidog desktop app?

No. The CLI is standalone. The desktop app is only needed to configure External AI Edit Permissions.

How do I prevent hallucinated field names?

Use the schema validation loop:

apidog cli-schema get schema-create
apidog cli-schema validate schema-create --file ./refund-full.json

An invented or malformed field fails local validation before it reaches the project.

Wrap up

Agent-driven API spec updates are safe when you enforce three practices:

Work in an isolated AI branch.
Treat every update as a complete read-modify-write operation.
Require human approval before merging, especially for breaking changes.

That makes spec maintenance an auditable diff instead of a risky direct edit. Download Apidog to get the CLI, then pair this workflow with agent-generated API documentation for a complete authoring and maintenance loop.

Stoplight to Apidog Migration Guide: Managing OpenAPI Specs in Spec-First Mode

Hassann — Tue, 14 Jul 2026 07:28:01 +0000

Migrating from Stoplight to Apidog is more than importing one OpenAPI file. You need to move a file-based API workflow that may include specs in Git, Markdown docs, JSON Schema models, local images, toc.json navigation inputs, and .stoplight.json path settings.

Try Apidog today

A Stoplight project may also depend on Postman request examples, Bruno files, CI test scripts, mocks, and publishing workflows. Importing only an OpenAPI file preserves endpoint definitions, but it does not automatically preserve the workflow around them.

Apidog Spec-first Mode helps teams keep OpenAPI files as the source of truth during a Stoplight migration while connecting those files to docs, mocks, tests, reports, permissions, and collaboration.

This guide shows how to:

Audit a Stoplight-style repository.
Carry over portable project files.
Review Stoplight-specific behavior.
Rebuild workflow-level assets.
Connect the OpenAPI contract to the broader API lifecycle.

For operational setup instructions, see the Spec-first Mode help guide.

Why Stoplight Migration Is More Than an OpenAPI Import

An OpenAPI file defines an API contract. A Stoplight-style project typically includes additional files and conventions around that contract.

Common project assets include:

OpenAPI or Swagger files, often under reference or another configured directory
Markdown documentation, often under docs
JSON Schema model files, often under models
Local images referenced by documentation
.stoplight.json path configuration
toc.json documentation navigation, grouping, and ordering inputs
Stoplight identifiers such as x-stoplight-id or x-stoplight.id

If you import only one spec file, you may keep endpoints but lose important context:

Documentation may need to be rebuilt.
Navigation may not match the existing project.
Models may become disconnected from docs.
Tests, mocks, and request examples may remain in separate tools.

Start from the repository tree—not from a single OpenAPI file.

Migration Model: Carry Over, Review, Rebuild, Connect

Before migration, identify the actual source of truth.

If OpenAPI files in Git define the API contract, start with Spec-first Mode. If Postman or Bruno collections define the real request workflow, resolve that mismatch before moving the project.

Do not try to preserve everything exactly. Some Stoplight-specific behavior does not map one-to-one to another workspace.

Use this four-part model instead:

Category	What belongs here	Migration stance
Carry over	OpenAPI files, supported `.stoplight.json` path settings, supported `toc.json` navigation inputs, Markdown docs, referenced local images, and JSON Schema models where supported	Bring file-based project context into Spec-first Mode
Review	Markdown links, anchors, images, TOC grouping, schema naming, external `$ref`s, Stoplight IDs, generated pages, and rendering differences	Verify the migrated workspace before treating it as production-ready
Rebuild	Postman or Bruno request flows, environments, manual tests, mocks, CI jobs, and publishing rules maintained outside the spec project	Recreate these around the OpenAPI source of truth
Connect	API docs, mock APIs, tests, CI reports, permissions, team collaboration, and partner workflows	Use Apidog to make the contract useful across the API lifecycle

Stoplight migration has two distinct layers:

File layer: OpenAPI specs, Markdown docs, models, images, and project structure files. This is where Spec-first Mode is directly useful.
Workflow layer: API reviews, publishing, tests, mocks, reports, permissions, and collaboration. Treat this as a separate migration concern.

The goal is not only to import data. It is to connect the contract to the workflow your team needs.

How Apidog Spec-first Mode Fits Stoplight Projects

Apidog Spec-first Mode supports file-based API workflows.

With a Git-connected project, your repository and branch remain the source of truth, while Apidog syncs with those files.

With a file-backed project, you can work with spec files directly in Apidog first, then connect Git later.

The Specs workspace gives your team one place to manage source files, inspect parsed API structures, and edit API definitions.

The Specs workspace lets teams manage source files, parsed API structure, and editing workflows in one place.

Map Stoplight assets to Apidog

Stoplight asset	What happens in Apidog	What to review
OpenAPI / Swagger files	Can be imported and synced as API modules, endpoints, schemas, and examples	Bundled references, conversion warnings, module names, and endpoint grouping
`.stoplight.json`	Supported fields can help locate OpenAPI, Markdown, and JSON Schema roots; apply OpenAPI include patterns and global excludes; and resolve `tocPath`	Treat it as path discovery for sync, not full Stoplight project configuration
`toc.json`	Can help create DOCS folders from supported groups and dividers, filter and order Markdown docs, apply titles, link folders to OAS modules or spec items, and import referenced JSON Schema models where supported	Review the final Apidog sidebar because exact Stoplight navigation and arbitrary cross-type ordering may not be preserved
Markdown docs	Documentation can be carried into the project workflow; TOC-listed docs can retain more structure where supported	Internal links, anchors, formatting, missing files, and rendering differences
Local images	Images referenced by Markdown can be imported where supported	Broken references, external images, data URIs, and unreferenced images
JSON Schema models	Explicitly referenced schema files, such as files referenced in `toc.json`, can be carried into Models where supported	Schema format, naming, grouping, references, and whether all models should be imported
Stoplight IDs	Root-level Stoplight IDs may help match imported modules across syncs	Do not assume endpoint-level or page-level identity is fully preserved

Compatibility notes for Stoplight project files

Treat .stoplight.json as a supported path-configuration subset for sync. Apidog can use supported OpenAPI, Markdown, and JSON Schema root directories, OpenAPI include patterns, global exclude patterns, and tocPath.
Treat other Stoplight project settings as ignored unless you verify their behavior after import.
Use toc.json to migrate supported navigation semantics, including DOCS folders, Markdown ordering, OAS/module links, selected spec-item links, and TOC-referenced model imports.
Review the final sidebar in Apidog. It uses the DOCS/OAS/MODELS model, so exact Stoplight layouts and arbitrary cross-type ordering may not be preserved.
Verify images separately. Referenced local images are the most predictable migration case; unreferenced assets, external images, and data URIs need manual review.
Reference JSON Schema files explicitly through supported project structures such as toc.json. Do not assume every file in a models directory becomes a model resource.

The target is not a pixel-perfect Stoplight recreation. The target is a portable, file-based project context connected to a broader API lifecycle.

From File Import to a Connected API Workflow

A traditional import workflow often imports an OpenAPI file once and then continues with visual edits in a new tool. That can create drift between:

The OpenAPI files in Git
Published documentation
The API workspace
Tests and mocks

Spec-first Mode keeps files at the center of the workflow.

In a Git-connected Spec-first project, teams can edit files in the Specs workspace, commit changes, and push them back to the repository.

In a file-backed project, teams can edit and save spec files in Apidog before connecting Git.

Use this responsibility split:

Responsibility	Recommended source
API contract	OpenAPI / Swagger files
Project file structure	Repository or file-backed project tree
Supported Stoplight-style path settings	`.stoplight.json`
Supported documentation navigation inputs	`toc.json` and Markdown docs
Daily API collaboration	Apidog project workspace
Mocks, tests, reports, and team permissions	Broader Apidog platform workflow

This is the main migration benefit: retain a file-first contract model while providing a usable API workspace for backend, frontend, QA, product, platform, and partner teams.

Git-Connected vs. File-Backed Migration Paths

Stoplight teams may start from different levels of Git maturity.

Some teams already review API changes through branches and pull requests. Others store API specs and docs as files but want to validate the workflow before connecting an external Git provider.

Apidog Spec-first Mode supports both paths.

Path	Best for	Typical workflow
Git-connected Spec-first project	Teams already managing OpenAPI specs in Git	Connect the repository, sync a branch, edit files, commit, and push
File-backed Spec-first project	Teams that want file-based API design before connecting Git	Work with spec files in Apidog, save changes, and validate the workflow first

For most Stoplight migrations, a Git-connected project is the clearer long-term approach because the repository remains the contract source of truth.

Use a file-backed project when you need to evaluate the authoring workflow, clean up project files, or stage the migration before adopting a stricter Git process.

What to Review After Migration

Even when files are carried over, run a structured review before using the migrated workspace in production.

Area	What to check
OpenAPI modules	Confirm all intended spec files were imported, module names are correct, and endpoints are grouped as expected
External references	Check whether `$ref` dependencies resolved correctly and whether conversion issues were reported
Lint and validation	Run Apidog Specs validation on imported OpenAPI files
`.stoplight.json`	Confirm supported OpenAPI, Markdown, and JSON Schema roots, include patterns, global excludes, and `tocPath`
`toc.json`	Review groups, dividers, titles, Markdown filtering and ordering, clickable groups, OAS links, selected spec-item links, model imports, and final sidebar output
Markdown docs	Check formatting, headings, relative links, anchors, and links to API files or operations
Images	Confirm referenced local images render correctly; review external images, data URIs, broken references, and unused assets separately
Models	Confirm which `toc.json`-referenced JSON Schema files became model resources and whether names, folders, and references are correct
Stoplight IDs	Confirm module matching behaves correctly across repeated syncs; do not rely on IDs for every resource type
Tests and mocks	Rebuild or reconnect workflows previously maintained in Postman, Bruno, CI, or separate tooling
Permissions and publishing	Recreate team access, documentation visibility, review rules, and release responsibilities

For validation, Apidog can use root-level Spectral configuration files:

.spectral.yaml
.spectral.yml
.spectral.json
.spectral.mjs

It can also fall back to .stoplight/styleguide.json for Spectral-based editor validation.

Treat validation results as review signals. Passing validation does not prove that every Stoplight-specific behavior was preserved.

What About Postman and Bruno Assets?

Many Stoplight teams also use Postman or Bruno. Plan those assets separately from the OpenAPI project migration.

OpenAPI files define the contract. Postman collections and Bruno .bru files usually define request workflows, examples, environments, or tests. These are valuable assets, but they are not the same migration object as a Stoplight-style OpenAPI project.

Answer these questions before migration:

Question	Why it matters
Is OpenAPI the source of truth, or are collections driving actual API behavior?	Spec-first migration should begin from the authoritative contract
Which request examples still matter?	Rebuild important examples around the connected API workspace
Which tests must keep running?	Move or reconnect tests instead of assuming they migrate with documentation
Which environments and secrets are shared?	Plan environment management separately from spec migration
Which CI jobs depend on current tooling?	Reconnect validation, testing, and reporting intentionally

For Bruno users, Git-native workflows are already valuable. Spec-first Mode can keep your API contract file-based, but Bruno assets may need separate migration, rebuilding, or replacement based on how your team uses them.

Recommended Migration Plan

Use a staged plan instead of attempting to migrate every workflow at once.

A staged migration plan: move the OpenAPI contract first, then reconnect the surrounding workflow.

1. Audit the Stoplight-style repository

Inventory:

OpenAPI files
.stoplight.json
toc.json
Markdown docs
JSON Schema models
Local images
Postman collections or Bruno files
CI scripts, tests, and publishing configuration

2. Decide the source of truth

Confirm that OpenAPI files in Git define the API contract.

If a Postman collection or Bruno workflow is effectively the source of truth, resolve that before starting a Spec-first migration.

3. Create the Spec-first project

Choose a Git-connected project when the team is ready to keep Git as the source of truth.

Choose a file-backed project when the team wants to validate the file-based workflow before connecting Git.

4. Review carried-over files

Check:

Imported API modules
Markdown documentation
JSON Schema models
Referenced images
Internal links and anchors
Supported toc.json navigation inputs
Supported .stoplight.json path settings
Specs validation results

Fix source project files where possible instead of manually patching symptoms in the workspace.

5. Rebuild workflow-level assets

Reconnect or recreate:

Mocks
Test scenarios
Request examples
CI jobs
Reports
Permissions
Documentation publishing responsibilities

6. Run one real API change through the new workflow

Use a small, low-risk OpenAPI change to verify the full path:

Update the OpenAPI file.
Review the change.
Sync or commit it.
Update documentation if required.
Validate downstream mocks, tests, and reports.

If your team already maintains OpenAPI files, Markdown docs, and schema models in a Stoplight-style repository, this approach lets you validate the migration path before rebuilding the complete workflow.

When This Migration Path Fits Best

This path is a good fit when:

Your team manages OpenAPI or Swagger specifications as files.
Your Stoplight project includes Markdown docs, models, images, .stoplight.json, or toc.json.
Your API review process depends on Git branches or pull requests.
You want docs, mocks, tests, reports, and collaboration connected to the API contract.
You want to reduce drift between API files and the workspace used by frontend, QA, product, platform, or partner teams.

It may require more planning when:

A Postman or Bruno collection is the real source of truth rather than OpenAPI.
The Stoplight project relies heavily on custom publishing behavior.
Documentation includes many external links, anchors, generated pages, or unreferenced assets.
JSON Schema models use formats or structures that need manual review.
The team expects a pixel-perfect recreation of Stoplight navigation or rendering.

FAQ

Is Apidog Spec-first Mode a Stoplight alternative?

It can be used as a Stoplight alternative for teams that want to keep OpenAPI projects file-based while adding API collaboration, testing, mocking, documentation, reporting, and permission management around those files.

Can I keep OpenAPI specs in Git?

Yes. In a Git-connected Spec-first project, teams can keep Git as the source of truth, sync a branch, edit files, and commit changes back to the repository.

Do I need Git to start?

No. Use a file-backed Spec-first project to work with spec files first, then connect Git later.

Are `.stoplight.json` and `toc.json` fully preserved?

No. Apidog uses supported parts of these files as migration inputs.

.stoplight.json is primarily used for path discovery during sync, including supported OpenAPI, Markdown, and JSON Schema roots, OpenAPI include patterns, global excludes, and tocPath.

toc.json can help organize supported DOCS content, OAS/module links, selected spec-item links, and TOC-referenced model imports.

The final online documentation sidebar is constrained by Apidog's DOCS/OAS/MODELS model, so exact Stoplight navigation and arbitrary cross-type ordering may not be preserved.

What happens to Markdown docs?

Markdown docs can be carried into the Spec-first project workflow. When toc.json is present, TOC-listed docs can retain more structure where supported.

Review internal links, anchors, images, and rendering after migration.

What happens to JSON Schema models?

JSON Schema models can be carried over where supported when they are explicitly referenced through supported project structures, such as toc.json.

Do not assume every JSON file in a models directory automatically becomes a model resource. Review schema formats, names, folders, and references after migration.

What happens to images?

Local images referenced by Markdown can be imported where supported.

Do not treat formats.image.rootDir as a guarantee that every image file in that directory will be imported. Review external images, data URIs, broken references, and unused image files separately.

Should I run lint or validation after migration?

Yes. Run Specs validation on imported OpenAPI files.

Apidog supports Spectral-based editor validation and can read root-level .spectral.yaml, .spectral.yml, .spectral.json, and .spectral.mjs files, or fall back to .stoplight/styleguide.json.

Use the results to review contract and style issues. Do not treat successful validation as proof that every Stoplight-specific behavior was preserved.

What should Bruno or Postman users do?

First identify whether OpenAPI or collections are the source of truth.

Spec-first migration centers on OpenAPI and related project files. Collection-based request workflows, environments, and tests may need separate migration or rebuilding.

Does Apidog support mocks, tests, CI/CD, reports, and collaboration?

Yes. Spec-first Mode connects the file-based API contract to Apidog, while the broader platform can support documentation, mocks, test scenarios, CI/CD execution with Apidog CLI, reports, permissions, and team collaboration.

Conclusion

Stoplight migration does not require giving up file-based API work.

Keep the repository as the source of truth. Preserve portable project files where supported, including OpenAPI specs, Markdown docs, referenced images, TOC-referenced JSON Schema models, and supported project structure files.

Then rebuild and connect the workflow around those files.

Apidog Spec-first Mode provides a practical path: carry over supported file-based assets, review Stoplight-specific structures carefully, and reconnect API docs, mocks, tests, reports, permissions, and collaboration around a shared API contract.

For enterprise migration planning, see Apidog Enterprise.

How to Use the Apidog CLI in Trae

Hassann — Tue, 14 Jul 2026 05:49:21 +0000

Trae’s Builder agent can read your repository, edit files, run terminal commands, and use command output to decide what to do next. API tests should be part of that same loop. With apidog-cli, Builder can run Apidog test scenarios from the terminal, inspect the exit code, and use failures as feedback while it works.

Try Apidog today

The setup is a small project rules file. Once the CLI is installed and authenticated, Builder can run an Apidog scenario just like it runs unit tests: execute the command, read the result, and treat a non-zero exit code as a failure.

Before continuing, confirm that:

apidog --version

prints a version number and that your Apidog account is authenticated. For installation, authentication, and a first run, follow How to install the Apidog CLI with an AI coding agent.

Which Trae this is about

This article covers ByteDance’s desktop Trae IDE: the VS Code-based editor with a chat panel and the Builder agent mode. See Trae’s official site for product details.

It does not cover the standalone trae-agent GitHub research project. If you can open Trae, see the chat panel, and switch the agent to Builder, this workflow applies to you.

Trae can load project rules before Builder starts working. That makes API-test execution persistent instead of relying on a one-off chat prompt. For a Trae-independent overview, see the complete Apidog CLI guide.

Step 1: Add a Trae project rules file

Trae project rules live at:

.trae/rules/project_rules.md

Create that file at the repository root. According to Trae’s rules documentation, Builder loads these rules during initialization and uses them while generating and editing code.

Add a rule that tells Builder:

when API tests are required;
which Apidog command to run;
how to interpret the exit code;
how to handle authentication and unknown flags.

## API testing with the Apidog CLI

When you change code that touches an API endpoint, verify it by running the
Apidog test scenario, not just the unit tests.

Command:
  apidog run -t <scenario_id> -e <env_id> -r cli

Rules:
- `apidog run` exits 0 when every assertion passes and non-zero on any failure.
  Treat a non-zero exit code as a failing test, even if the summary looks fine.
- This machine is already authenticated via `apidog login`. Never add an
  --access-token flag and never put a token in this file.
- If a flag is unknown, run `apidog run --help` and use the exact flag from there.

Commit this file with the repository. Unlike a scenario ID pasted into chat, project rules remain available for every teammate and every future Builder session.

For monorepos, Trae can also read .trae/rules/ folders in subdirectories, allowing each service to keep its own API test command close to its code.

Step 2: Copy the real scenario command from Apidog

Do not manually guess scenario or environment IDs.

Open your test scenario in Apidog.
Open the CI/CD tab.
Copy the generated apidog run command.
Paste its -t scenario ID and -e environment ID into project_rules.md.

For example:

Command:
  apidog run -t your_scenario_id -e your_environment_id -r cli

Using the generated command avoids errors caused by invented or stale IDs. For available options, see the apidog run command reference.

Step 3: Run the scenario with Builder

Switch Trae to Builder mode and open your repository. Builder loads project_rules.md during initialization.

After changing API-related code, ask Builder to run the check:

Run the Apidog test scenario and tell me the exit code.

Builder should use the command from your rules file:

apidog run -t <scenario_id> -e <env_id> -r cli

Trae requires approval before Builder executes shell commands. Review the proposed command and click Run. Once it completes, Builder can read the terminal output and use the result in its next step.

The -r cli reporter is useful for agent workflows because it prints request-by-request results and a summary directly in the terminal.

Step 4: Read failures in the terminal

When a scenario fails, -r cli provides Builder with:

each request that ran;
each assertion;
expected and actual values for failures;
the final exit code.

This gives Builder concrete debugging context. For example, a failed assertion can identify a wrong status code, a missing response field, or an unexpected value.

To also generate a browser-friendly report, add the HTML reporter:

apidog run -t <scenario_id> -e <env_id> -r cli,html

Keep cli enabled so Builder can still read inline terminal output. The html reporter writes a self-contained report to:

./apidog-reports

For JSON, JUnit, and other report formats, see the guide to Apidog CLI test reports.

Put API tests inside Builder’s edit-test-fix loop

The goal is not just running a command manually. The goal is making API validation part of Builder’s normal workflow.

For example, when Builder edits a checkout handler, the loop becomes:

Edit the handler.
Run the Apidog scenario against the configured environment.
Read the exit code and failed assertions.
Fix the implementation if the run fails.
Re-run the scenario.
Continue only after the scenario passes.

A green run lets Builder move on. A red run gives it request and assertion details to investigate. Your API scenario becomes a test gate alongside unit tests.

You still author and maintain scenarios visually in Apidog, while Builder executes them from the repository workflow. For more on this pattern, see how to use AI agents for API testing and the Apidog AI test harness.

Verify that Trae actually ran the CLI

Do not rely only on Builder’s summary. Verify the command and its result.

1. Check that `apidog run` appears in the terminal

Trae shows the commands Builder executed and their output. Look for the literal apidog run command and its resulting output.

If Builder claims it ran tests but no command appears in the terminal, ask it to run the scenario again and show the raw output.

2. Check the exit code

Ask:

What was the exit code of that apidog run command?

apidog run exits with:

0 when every assertion passes;
a non-zero code when any assertion fails.

Treat the exit code as the source of truth. If Builder says “tests passed” but the process exited non-zero, the test failed.

3. Verify the scenario and environment IDs

If the CLI reports that a scenario cannot be found, Builder may be using an incorrect ID.

Compare the command in:

.trae/rules/project_rules.md

with the command generated in Apidog’s CI/CD tab. Verify both:

-t <scenario_id>
-e <environment_id>

The IDs stored in your project rules should match the generated Apidog command.

Optional: Connect the Apidog MCP server

The CLI is enough for running API tests. An MCP server adds specification context while Builder writes code.

Trae agents can act as MCP clients. To connect a server:

Open Trae settings.
Go to the MCP tab.
Choose a marketplace server or select Add Manually.
Provide the server JSON configuration with command, args, and env.

See Trae’s guide to adding MCP servers for the configuration flow.

The Apidog MCP server exposes API specifications over MCP. This creates a useful separation:

Apidog CLI runs test scenarios.
Apidog MCP server gives Builder access to API specifications.

Troubleshooting common setup failures

Builder ignores the rules file

Confirm the path is exactly:

.trae/rules/project_rules.md

The directory must be named rules, not rule, and the file must be under the repository root. Restart the Builder session to force Trae to reload project rules.

Builder adds `--access-token`

If Builder tries to add an access token, it is likely copying a public example instead of following your rules.

Keep this instruction in project_rules.md:

This machine is already authenticated via `apidog login`. Never add an
--access-token flag and never put a token in this file.

Do not store real tokens in the repository. For interactive and CI authentication details, see Apidog CLI authentication.

Builder invents a CLI flag

An “unknown option” error means the installed CLI version does not support the flag Builder used.

Have it run:

apidog run --help

Then update the command or rule using the exact syntax reported by your installed version.

Builder reports success after a failed run

Always check the process exit code. If the terminal summary and exit code appear to disagree, treat the non-zero exit code as a failure.

That is why the exit-code rule belongs in project_rules.md.

From daily agent usage to a tested workflow

The implementation is straightforward:

Install and authenticate apidog-cli using the install guide.
Create .trae/rules/project_rules.md.
Paste the real apidog run scenario command from Apidog.
Require Builder to treat non-zero exit codes as failed tests.
Verify the command and exit code in Trae’s terminal.

Your API scenarios remain visual and maintainable in Apidog, while Builder can execute them during implementation.

Download Apidog, create a scenario, add its apidog run command to your project rules, and use it as part of Builder’s next API change. To run the same scenario in CI, see Apidog CLI in GitHub Actions.

How to Use the Apidog CLI in Windsurf

Hassann — Tue, 14 Jul 2026 05:47:56 +0000

Run Apidog API Tests in Windsurf Cascade

Windsurf’s Cascade agent already follows an edit-test-fix loop: it changes files, runs commands, reads output, and decides what to do next. Add your Apidog API test scenario to that loop so Cascade can run it from the terminal, inspect the exit code, and react to failures instead of leaving tests behind a GUI.

Try Apidog today

Install the apidog-cli npm package, authenticate once, and add a project rule that tells Cascade which scenario to run. Cascade can then execute apidog run alongside your existing unit-test commands.

Before continuing, verify that the CLI is installed and authenticated:

apidog --version

If you need setup instructions, see How to install the Apidog CLI with an AI coding agent.

Which Windsurf setup this applies to

This guide is for Codeium’s Windsurf IDE and its built-in Cascade agent. Cascade runs locally, can read your repository, edit files, and execute shell commands in the integrated terminal. Depending on your auto-execution settings, it may ask for command approval.

If Windsurf is not installed yet, start with how to download and install Windsurf.

Step 1: Add an Apidog rule to `.windsurf/rules`

Cascade loads project rules from Markdown files in .windsurf/rules/ at the repository root. Put one rule per file.

Windsurf also supports the legacy .windsurfrules file at the workspace root and global rules in ~/.codeium/windsurf/memories/global_rules.md. For a repository-specific test command, use .windsurf/rules/.

See the Windsurf rules and memories reference for the current behavior.

Create this file:

.windsurf/rules/apidog.md

Add the following rule:

# Apidog API tests

This project has Apidog test scenarios. Run them with the Apidog CLI:

    apidog run -t <scenario_id> -e <env_id> -r cli

Rules:
- Use the exact command above; do not invent flags. Run `apidog run --help` if unsure.
- `apidog run` exits 0 when every assertion passes, non-zero when any fails.
  Treat exit 0 as pass and non-zero as fail. Report the real exit code.
- The machine is already authenticated via `apidog login`. Never add an
  access token to the command or commit one to this file.
- After you change code that touches the API, run the scenario and act on the result.

A rule file is more reliable than a chat instruction:

It persists across Cascade sessions.
It is shared with teammates through Git.
Cascade loads it automatically when it starts in the repository.

Step 2: Copy the real command from Apidog

Do not guess the <scenario_id> or <env_id> values.

In Apidog:

Open the test scenario.
Open the CI/CD tab.
Copy the generated apidog run command.
Replace the example command in .windsurf/rules/apidog.md.

The generated command includes the correct scenario ID, environment ID, and reporter options for your project.

For available options, see the apidog run command reference.

Step 3: Ask Cascade to run the scenario

Open Cascade in the repository after adding the rule. It should load .windsurf/rules/apidog.md automatically.

You can make an API-related code change, then ask:

Run the Apidog scenario and tell me the exit code.

Cascade should execute the exact apidog run command defined in the rule.

Whether Cascade runs it immediately depends on your auto-execution mode:

Disabled: every command needs approval.
Allowlist Only: only allowlisted commands run automatically.
Auto: execution is based on a premium-model judgment.
Turbo: commands run automatically unless denylisted.

To allow Apidog commands without enabling broader automatic execution, add apidog to the windsurf.cascadeCommandsAllowList setting.

You can open settings through the Command Palette and configure:

{
  "windsurf.cascadeCommandsAllowList": ["apidog"]
}

The matching denylist setting is windsurf.cascadeCommandsDenyList. If a command matches both lists, the denylist takes precedence.

See Windsurf’s terminal documentation for details.

Step 4: Read failures in Cascade’s terminal

Use the CLI reporter so Cascade can inspect test output directly:

apidog run -t <scenario_id> -e <env_id> -r cli

The cli reporter prints each request, assertion result, and summary in the terminal. When a test fails, Cascade can use the failed status code, field, expected value, or actual value to identify the next code change.

To also generate a browser-friendly report, add the HTML reporter:

apidog run -t <scenario_id> -e <env_id> -r cli,html

The html reporter writes a self-contained report to:

./apidog-reports

Keep cli enabled so Cascade still receives inline output.

For all supported report formats, including JUnit output for CI systems, see:

Put API testing inside Cascade’s loop

Once the rule is in place, Cascade can follow the same workflow it uses for unit tests:

Edit an API handler or service.
Run the Apidog scenario against the configured environment.
Read the terminal output and exit code.
Fix the reported failure.
Run the scenario again.

For example, if Cascade changes a checkout response handler, your scenario can detect a missing field, incorrect value, or wrong HTTP status before the agent considers the task complete.

The CLI provides the verification step. You still author and maintain scenarios visually in Apidog, while Cascade executes those scenarios during implementation.

For the broader agent-testing pattern, see:

Verify that Cascade actually ran the CLI

Do not rely only on Cascade’s summary. Verify the command and result.

1. Confirm the command was executed

Look for the literal command and its output in Cascade’s terminal:

apidog run ...

If Cascade says tests ran but there is no command output, ask it to rerun the scenario and show the raw terminal result.

2. Confirm the exit code

Ask Cascade directly:

What was the exit code of that apidog run command?

apidog run returns:

0 when all assertions pass
A non-zero exit code when an assertion fails

Treat the exit code as the source of truth. If Cascade says “tests passed” but the command exited with a non-zero status, the test failed.

3. Confirm the scenario and environment IDs

If the CLI reports that a scenario cannot be found, Cascade may be using an incorrect ID.

Compare the -t and -e values in:

.windsurf/rules/apidog.md
The command generated in Apidog’s CI/CD tab

Use the generated command as the canonical source.

Optional: Connect the Apidog MCP server

The rule-based CLI workflow is enough to run tests. If you also want Cascade to access API specifications while writing code, connect an MCP server.

Windsurf supports Model Context Protocol servers through:

~/.codeium/windsurf/mcp_config.json

You can edit that file directly or configure servers through Cascade’s MCP panel. See the Windsurf MCP reference and how to set up MCP servers in Windsurf.

The Apidog MCP server exposes API specifications to MCP-compatible agents.

Use the two integrations for different jobs:

Apidog CLI: run API test scenarios and return pass/fail results.
Apidog MCP server: provide API schemas and specifications as context while Cascade writes code.

Troubleshooting common setup issues

Cascade ignores the rule

Check that the file:

Is located at .windsurf/rules/apidog.md
Is inside the repository root
Uses the .md extension

Each rule file is capped at 12,000 characters, so keep the rule focused. Restart Cascade to force it to reload project rules.

Cascade adds an access token

Do not put tokens in a committed rules file.

Your rule should explicitly state that the machine is already authenticated with:

apidog login

If Cascade still tries to add a token, reinforce that instruction and have it use the existing authenticated CLI session.

See the Apidog CLI authentication guide.

Cascade invents a CLI flag

If the command fails with an “unknown option” error, tell Cascade to inspect the installed CLI version:

apidog run --help

Then update the rule with the supported command syntax.

Cascade reports success after a failed run

Use the exit code, not the summary text.

If the command exits non-zero, the scenario failed and should be treated as a failed gate.

From agent assistance to a tested loop

The setup is small:

Install apidog-cli.
Authenticate with apidog login.
Add the generated apidog run command to .windsurf/rules/apidog.md.
Tell Cascade to run the scenario after API changes.
Validate the terminal output and exit code.

Your API tests no longer depend on someone opening a GUI and clicking Run. You continue building scenarios visually in Apidog, while Cascade can execute the same scenarios as part of its local development loop.

When the command works locally, use it in CI as well. See Apidog CLI in GitHub Actions for secrets, reporters, and exit-code gating.

Download Apidog, create a scenario, add its generated command to a Windsurf rule, and let Cascade run it on the next API change.

How to Use the Apidog CLI in Antigravity

Hassann — Tue, 14 Jul 2026 05:47:26 +0000

Antigravity is a loop: its agent edits files, runs terminal commands, reads output, and decides what to do next. Your API tests should be part of that loop too. Instead of leaving scenarios in the Apidog GUI until someone manually clicks Run, expose them through the apidog-cli package and let the agent execute them like any other test command.

Try Apidog today

The setup is one rules-file block. Once apidog-cli is installed and Antigravity knows the command, it can run an Apidog scenario, inspect its exit code, and iterate on failing code.

Before continuing, make sure the CLI is installed and authenticated:

apidog --version

If you still need setup help, follow How to install the Apidog CLI with an AI coding agent. This guide assumes apidog --version prints a version number and apidog login has already authenticated the machine.

Which Antigravity this is about

Antigravity is Google’s agentic development platform, built on Gemini 3, that launched in late 2025. Its Agent Manager can plan work, edit repository files, execute shell commands, and use a browser.

If you have started an Antigravity task and watched the agent run commands in its terminal, this workflow applies to you. For a broader introduction, see what Google Antigravity is and how to use it.

The key detail is that Antigravity can load project rules. Put your API test command in those rules, and the agent can use it consistently instead of relying on a one-off chat instruction.

Step 1: Add an Antigravity rules file

Antigravity recognizes a .agents/ directory at the workspace root. Google’s codelab on building autonomous developer pipelines in Antigravity shows workspace rules placed in .agents/rules/.

Create this file:

.agents/rules/apidog.md

Alternatively, Antigravity can read an AGENTS.md file at the workspace root. This is also the file Codex reads for the Apidog CLI. If your repository already uses AGENTS.md, keep the instruction there instead of duplicating it.

Add a short, explicit rule block:

## API testing with the Apidog CLI

- To test the API, run the Apidog scenario. Do not click through the GUI.
- Command: apidog run -t <scenario_id> -e <env_id> -r cli
- Exit code 0 means every assertion passed.
- A non-zero exit code means a failure: inspect the report and fix the code.
- This machine is already authenticated via `apidog login`.
- Never add an `--access-token` flag or put a token in this file.

Keep this instruction in the repository rather than in chat. Antigravity does not retain ad hoc coaching across sessions, but workspace rules are available to every new task and teammate.

Step 2: Copy the generated command from Apidog

Do not guess scenario or environment IDs.

Open the test scenario in Apidog.
Open the CI/CD tab.
Copy the generated CLI command.

It should look similar to this:

apidog run -t 123456 -e 789012 -r cli

The flags are:

-t: test scenario ID
-e: environment ID
-r cli: print results directly in the terminal

Paste the real command into .agents/rules/apidog.md or AGENTS.md. This gives Antigravity a stable, exact command to run.

For the available options, see the apidog run command reference.

Step 3: Ask Antigravity to run the scenario

Start an Antigravity task after adding the rules file. The agent loads the project rules when it begins.

You can explicitly request the check:

Run the Apidog test scenario and tell me the exit code.

The agent should execute the apidog run command from your rules file in its terminal.

Whether Antigravity asks for approval depends on its Security Preset. Google describes these terminal and file-access controls in its getting started with Antigravity codelab.

If Antigravity requests approval, review the command before allowing it to run. A read-only test scenario against staging is usually an appropriate in-workspace command to approve.

The important outcome is not a summary such as “tests passed.” You want to see:

the literal apidog run ... command;
the CLI output;
the final exit code.

Step 4: Read failures from the terminal report

With -r cli, Apidog prints a readable test result directly in the terminal. Antigravity can inspect:

requests that ran;
assertions that passed or failed;
expected and actual values;
failing status codes or fields.

That output gives the agent enough context to locate the affected handler, request mapping, or response field and attempt a fix.

For a browser-readable artifact, add the HTML reporter:

apidog run -t 123456 -e 789012 -r cli,html

The html reporter writes a self-contained report to:

./apidog-reports

Keep cli in the reporter list. Antigravity needs inline terminal output to evaluate the result and decide its next step.

For more report formats, including JUnit for CI systems, see the complete Apidog CLI guide and how to read Apidog CLI test reports.

Put API tests inside the agent loop

Once the command is in the rules file, API testing becomes part of the agent’s normal edit-test-fix cycle.

For example, an agent updates a checkout response handler:

It edits the handler.
It runs the Apidog scenario against staging.
It reads the exit code.
If the run is green, it continues.
If the run is red, it reads the failed assertion.
It fixes the response, status code, or missing field.
It runs the scenario again.

The API scenario now behaves like a unit-test gate, but it validates the real API behavior defined in Apidog.

This follows a delegate-then-verify workflow: Antigravity executes the command and interprets the result, while you continue authoring and maintaining scenarios visually in Apidog. For related patterns, see how to use AI agents for API testing and the Apidog AI test harness.

Verify Antigravity actually ran the CLI

Do not rely only on the agent’s prose summary. Verify the run in three steps.

1. Confirm the command was executed

Open Antigravity’s terminal output and look for the actual command:

apidog run ...

Then confirm that CLI output appears below it.

If the agent claims it ran tests but there is no command or output, ask it to rerun the scenario and show the raw terminal result.

2. Confirm the exit code

Ask directly:

What was the exit code of that apidog run command?

apidog run exits with:

0 when every assertion passes;
a non-zero value when an assertion fails.

Treat the exit code as the source of truth. If the agent says “tests passed” but the command returned a non-zero exit code, the test run failed.

3. Confirm it used the correct scenario

If the CLI reports “scenario not found,” verify the IDs:

Compare the -t scenario ID with the command generated in Apidog.
Compare the -e environment ID with the selected Apidog environment.
Confirm the same IDs are stored in your rules file.

The generated command from Apidog is the authoritative source.

Optional: Connect the Apidog MCP server

The CLI is enough to run scenarios. Add MCP when you also want the agent to access API specifications while it writes code.

Antigravity supports the Model Context Protocol. According to Google’s getting started codelab, configure MCP servers in:

$HOME/.gemini/config/mcp_config.json

Add your server under the mcpServers object with its command, args, and env, then refresh MCP from Antigravity settings.

The Apidog MCP server exposes API specifications through MCP. Use the two integrations for different purposes:

Apidog CLI: run scenarios and enforce pass/fail results.
Apidog MCP server: provide API schema context while the agent writes code.

Troubleshooting common setup failures

Antigravity ignores the rules file

If the agent uses a generic command or does not run a test:

Confirm the file name and location.
Use .agents/rules/apidog.md at the workspace root, or use root-level AGENTS.md.
Start a fresh task so Antigravity reloads project rules.

The agent adds `--access-token`

The agent may infer this from public examples. Your rules should explicitly state that the machine is authenticated through:

apidog login

Do not store a token in AGENTS.md or .agents/rules/apidog.md.

For authentication details, see Apidog CLI authentication.

The agent invents a CLI flag

If the CLI returns an “unknown option” error, have the agent check the locally installed version:

apidog run --help

Use the flags printed by that command rather than a guessed flag.

The agent reports success after a failed run

When the summary conflicts with the command result, the exit code wins. Keep the exit-code rule in your workspace instructions and require the agent to report it after every run.

From a daily agent to a tested loop

Install apidog-cli once using the installation guide, then add the generated apidog run command to your Antigravity rules file.

From that point, Antigravity has a repeatable API test command it can run while changing code:

apidog run -t <scenario_id> -e <env_id> -r cli

A test behind a GUI runs only when a person remembers to click it. A CLI command in the agent’s rules can run whenever Antigravity needs to verify an API change.

Build scenarios visually in Apidog, add the generated command to your rules file, and let the agent use it on the next API change. To run the same command in CI without an agent, see Apidog CLI in GitHub Actions.