basics.md

API Testing Basics

Explorbot tests REST APIs the same way it tests web apps: it plans scenarios, runs them, and reports results — no test scripts. Two AI agents do the work.

Chief reads your endpoint, its OpenAPI spec, and any knowledge you've written, then plans test scenarios: what to send, and what a correct response looks like.

Curler takes each scenario and executes it as real HTTP requests, checking the responses with assertions.

The plans Chief writes are ordinary Explorbot test plans — plain markdown you can read, edit, and commit. The web and API sides share the same plan format and the same reporting.

Configure

Point Explorbot at your API by adding an api key to your explorbot.config.js:

export default {
  ai: {
    model: openrouter('openai/gpt-oss-20b:nitro'),
    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
  },
  api: {
    baseEndpoint: 'http://localhost:3000/api/v1',
    spec: ['http://localhost:3000/api/openapi.json'],
    headers: {
      Authorization: 'Bearer <token>',
    },
  },
};

• baseEndpoint (required) — the base URL prepended to every request. Test steps use relative paths like /users; Curler adds the base for you.
• spec (required) — one or more OpenAPI specs, given as HTTP(S) URLs or local file paths, in YAML or JSON. Chief uses the spec to plan; Curler uses it to look up schemas. Both agents refuse to run without one.
• headers — sent with every request. This is where API keys and auth tokens go.

See the full configuration reference for every option and providers for choosing an AI model.

Authenticating

If a static token in headers is enough, you're done. If you need to log in and fetch a token first, use the bootstrap hook — it runs once before any tests, and whatever headers it returns merge into every later request:

api: {
  baseEndpoint: 'http://localhost:3000/api/v1',
  spec: ['http://localhost:3000/api/openapi.json'],
  bootstrap: async ({ baseEndpoint }) => {
    const res = await fetch(`${baseEndpoint}/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'admin@test.com', password: 'secret' }),
    });
    const { token } = await res.json();
    return { Authorization: `Bearer ${token}` };
  },
},

A matching teardown hook runs after all tests finish — use it to clean up data.

Without a config file

Chief and Curler need three things: where the API is, what its spec says, and how to authenticate. Pass all three on the command line and no config file is needed:

npx explorbot api plan /users \
  --endpoint https://api.example.com/v1 \
  --spec ./openapi.yaml \
  --knowledge 'Send X-Api-Key: ${env.API_KEY} on every request'

--endpoint and --spec each have an environment twin — EXPLORBOT_URL and EXPLORBOT_API_SPEC — and the flag wins when both are set. --knowledge adds to the facts EXPLORBOT_KNOWLEDGE and EXPLORBOT_KNOWLEDGE_FILE bring in rather than replacing them. Configure your models once with npx explorbot init --global and every run stores its plans and requests per host under ~/.explorbot/sites/<host>/, so a later api test against the same API picks up where the last one left off. Knowledge given on the command line lasts for the run; api know is what writes it down.

--endpoint keeps its path prefix: given https://api.example.com/v1, steps stay relative (/users) and Curler sends them to https://api.example.com/v1/users. api test, which takes a plan file rather than an endpoint, reads it from the flag or the variable.

A dedicated API project

If you don't have a web explorbot.config.js, run npx explorbot api init. It asks for your base endpoint, spec, and a one-line description of the API, then writes a standalone apibot.config.ts (with an ai and api section) plus output/ and knowledge/ directories. When both files exist, apibot.config.* takes precedence over explorbot.config.*.

Your first run

The minimal loop is plan, then test. Point Chief at an endpoint:

npx explorbot api plan /users

On startup Explorbot does a health check — a GET / against your base endpoint — so a bad URL or token fails immediately. Then Chief fetches sample data, reads the spec, and writes scenarios to output/plans/users.md. Hand that file to Curler:

npx explorbot api test output/plans/users.md

Curler runs the scenarios and prints how many passed and failed.

Output files

Output	Location	What it is
Test plans	output/plans/*.md	Chief's scenarios — priorities, steps, expected outcomes
Request logs	output/requests/*.request.yaml	Every HTTP request and response, for debugging
Reports	via the shared reporter	Pass/fail results, optionally sent to Testomat.io

Next steps

• Planning API tests — give Chief context and steer what it tests.
• Running API tests — execute plans, read request logs, and run the full autonomous cycle.