API Runtime

API runtime lets Certyn test HTTP APIs without launching a browser. An API project stores its target as an environment base URL, starts an API-focused agent session, and gives the agent request tools inside its Linux container.

Use API runtime when the target is an HTTP service, REST API, backend workflow, webhook receiver, or service endpoint rather than a browser or Appium-controlled app.

What you need

API projects require a reachable API base URL. Certyn passes the selected environment URL to the agent container as:

TARGET_BASE_URL=https://api.example.com

API sessions do not set STARTUP_URL, because there is no browser page to open.

Authentication can be supplied through environment variables, API keys, bearer tokens, or explicit instructions in the test case. Keep secrets out of screenshots and issue text when possible; API tools redact common token, password, key, and authorization values from output.

How Hurl works

The stored test case remains the source of truth. In the MVP, a test case is still natural-language instructions such as:

Create a customer, fetch it by id, verify the response is 200, then delete it.

During execution, the API Tester agent loads the test case and generates a temporary Hurl flow. The generated .hurl file is written inside the agent container, executed, and discarded after the tool call.

If the test case already contains a fenced Hurl block, the agent should prefer that exact flow:

```hurl
GET {{baseUrl}}/health
HTTP 200
[Asserts]
jsonpath "$.status" == "ok"
```

The agent fills variables such as baseUrl from TARGET_BASE_URL or supplied environment variables.

What agents can do

API runtime agents can:

• read execution context, environment variables, and the selected test case
• make controlled HTTP calls with api_request
• generate and run Hurl flows with run_hurl
• use bash as an escape hatch for debugging
• report outcomes, observations, issues, and execution evidence

API sessions do not receive browser, computer-use, mobile, or desktop action tools.

Evidence

API runs produce request and response evidence instead of UI screenshots. Useful evidence includes:

• request method and URL
• response status and timing
• selected response headers
• redacted response body excerpts
• Hurl exit code and concise stdout/stderr
• agent summary, outcome, and linked issues

MVP limitations

The first API runtime does not include a structured API test editor, persisted apiRuntime object, Schemathesis, k6, Bruno, Newman, or ZAP. Those can become specialized process types later.

For now, write API tests as natural-language test cases, optionally with fenced Hurl when you need exact request syntax.