Run a sandbox evaluation against saved rulesets and saved APIs.

Synchronously evaluate one or more saved APIs against a selected set of rulesets and return the violations inline. No persistence. Used by the Ruleset Test Sandbox UI (“Test ruleset” on the ruleset detail screen and the API Governance Tab).

Rulesets are selected via either ruleset_ids (explicit) or categories (executes every active ruleset whose categories intersect the input) — exactly one of the two. APIs are selected via api_ids (required). This endpoint takes references only — to evaluate an API definition submitted in the request (CI/CD file, UI draft), use POST /api/evaluations/sandbox/oas. Caps: 10 APIs, 20 resolved rulesets, 20 input categories, 1,000 issues per response.

POST /api/evaluations/sandbox

cURL

saved-ruleset-saved-api

curl --request POST \
  --url https://{tenant}/api/evaluations/sandbox \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ruleset_ids": [
    "rs-payments-v1"
  ],
  "api_ids": [
    "petstore"
  ]
}
'

200

{
  "rulesets": [
    {
      "id": "<string>",
      "name": "<string>",
      "resource_type": "oas-api",
      "active": true,
      "action": "none",
      "error_count": 123,
      "warn_count": 123,
      "info_count": 123,
      "hint_count": 123
    }
  ],
  "issues": [
    {
      "_id": "<string>",
      "org_id": "<string>",
      "api_id": "<string>",
      "ruleset_id": "<string>",
      "ruleset_name": "<string>",
      "rule_id": "<string>",
      "rule_summary": "<string>",
      "how_to_fix": "<string>",
      "message": "<string>",
      "severity": "error",
      "severity_order": 123,
      "path": "<string>",
      "location": {
        "start_line": 123,
        "start_char": 123,
        "end_line": 123,
        "end_char": 123
      },
      "created_at": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 123,
  "truncated": true,
  "error_count": 123,
  "warn_count": 123,
  "info_count": 123,
  "hint_count": 123,
  "evaluated_apis": 123,
  "elapsed_ms": 123,
  "error": "<string>"
}

Authorizations

Authorization · string · header · required

The Tyk Dashboard API Access Credentials

Body

application/json

Sandbox evaluation request — saved resources only. Exactly one of ruleset_ids / categories must be provided (non-empty). To evaluate an API definition submitted in the request body, use POST /api/evaluations/sandbox/oas instead.

api_ids · string[] · required

APIIDs of saved APIs in the caller's org. Classic (non-OAS) APIs are rejected.

Required array length: 1 - 10 elements

ruleset_ids · string[]

Stable RulesetIDs of saved rulesets in the caller's org. Soft-deleted rulesets are rejected. Inactive rulesets are accepted — sandbox semantics are "test this ruleset", regardless of whether it's currently driving the async dispatcher.

Required array length: 1 - 20 elements

categories · string[]

Category names. Server resolves to every active, non-deleted ruleset whose categories intersect this list, scoped to the resource_type of each resolved API. Use this for the "run an entire compliance category against this API" workflow.

Required array length: 1 - 10 elements

Response

200

application/json

Evaluation completed. The response may include a non-empty error string when the engine returned failures for some (ruleset, api) pairs while others succeeded; successful pairs' issues are still present in issues. An empty rulesets[] indicates no rulesets matched (category resolution returned none, or all matching rulesets had a different resource_type than the APIs).

rulesets · object[] · required

Rulesets actually executed in this run. Single-ruleset callers see one entry; category-based callers see the resolved set. Each entry carries the ruleset's configured action and its per-ruleset severity counts. Empty array means no rulesets matched the request (category input with no intersection, or the only matches had a different resource_type than the APIs).

Show child attributes

issues · object[] · required

Per-rule violations across all evaluated APIs, sorted by severity then location. Capped at MaxSandboxIssues (1000) — see truncated. Shared row schema with /api/governance/issues.

Show child attributes

total · integer · required

Un-truncated issue count produced by the engine.

truncated · boolean · required

True when total > MaxSandboxIssues and issues was capped. FE renders a banner; CI/CD pipelines should treat this as a failure since the build is being gated against partial data.

error_count · integer · required

Run-wide count of severity-0 (error) issues, computed pre-truncation — trustworthy even when issues is capped. Count field names and severity mapping match the persisted ApiGovernanceResult summaries (tyk_governance_api_summaries).

warn_count · integer · required

Run-wide severity-1 (warn) issue count, pre-truncation.

info_count · integer · required

Run-wide severity-2 (info) issue count, pre-truncation.

hint_count · integer · required

Run-wide severity-3 (hint) issue count, pre-truncation.

evaluated_apis · integer · required

Number of APIs the engine actually applied rules against. Always 1 for /sandbox/oas.

elapsed_ms · integer<int64> · required

Wall-clock duration of engine.Evaluate, in milliseconds.

error · string

Joined error string when the engine returned failures for some (ruleset, api) pairs (per errors.Join from the mechanism story). Absent on full success. Per-pair attribution is deferred — see ticket.