Run a sandbox evaluation for one submitted OAS definition.

Synchronously evaluate one OpenAPI/Tyk OAS API definition submitted as content — either the raw file as the request body (--data-binary @openapi.yaml) or a {"content": "..."} JSON envelope. The definition is treated as a transient inline API: no import, no persistence. Used by CI/CD pipelines (API token) and the UI draft-OAS flow (session + CSRF).

Shape detection is deterministic: a JSON body whose top-level object has a content key is an envelope (no valid OpenAPI document has one); everything else is a raw document. The envelope’s content string is parsed as JSON first, then YAML.

Ruleset selection is explicit and bounded: ruleset_ids, else categories, else 400. Categories are never derived from the submitted file — OAS documents carry no category linkage (for OAS APIs, categories live on the Dashboard-stored API envelope, not in the definition). There is no “run all active rulesets” fallback — CI behavior must not change because an unrelated ruleset became active.

POST /api/evaluations/sandbox/oas

Run a sandbox evaluation for one submitted OAS definition.

cURL

curl --request POST \
  --url https://{tenant}/api/evaluations/sandbox/oas \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "<string>"
}
'

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

Query Parameters

ruleset_ids · string[]

Saved ruleset IDs, comma-separated (repeated params also accepted by the handler). When set, overrides category-based resolution. Inactive rulesets are accepted when selected explicitly. Mutually exclusive with categories.

Maximum array length: 20

categories · string[]

Governance categories, comma-separated (repeated params also accepted by the handler). Resolves to active oas-api rulesets. The only category source for this endpoint — the submitted file carries none. Mutually exclusive with ruleset_ids.

Maximum array length: 10

api_id · string

Optional transient API ID echoed on response rows and used in issue IDs. Recommended for CI: if omitted, the fallback is x-tyk-api-gateway.info.id, then a deterministic hash of the canonicalized parsed document — which changes on every spec edit, churning issue IDs between commits.

api_name · string

Optional display name for the submitted document (engine-internal identity; response rows identify the API by api_id only). Defaults to x-tyk-api-gateway.info.name, then info.title, then api_id.

Body

application/jsonapplication/yamlapplication/x-yaml

Option 1

Option 2

Envelope transport for POST /api/evaluations/sandbox/oas. Carries the API definition as a string and nothing else — evaluation metadata (ruleset_ids, categories, api_id, api_name) stays in query params. Extra fields are rejected with 400.

content · string · required

The OpenAPI/Tyk OAS definition as a string — JSON or YAML, auto-detected (JSON parse attempted first, then YAML). Same accepted document shape as raw-body mode.

Response

200

application/json

Evaluation completed. evaluated_apis is always 1 on this endpoint. The response may include a non-empty error string for partial engine failures. CI gates must inspect the body — truncated == true, a present error, or blocking-severity issues all arrive with HTTP 200.

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.