> ## Documentation Index > Fetch the complete documentation index at: https://tyk-update-tt-17927-release-main-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /swagger/dashboard-swagger.yml post /api/evaluations/sandbox openapi: 3.0.3 info: contact: email: support@tyk.io name: Tyk Technologies url: https://tyk.io/contact description: > ## Introduction The Tyk Dashboard API offers granular, programmatic access to a centralised database of resources that your Tyk nodes can pull from. This API has a dynamic user administrative structure which means the secret key that is used to communicate with your Tyk nodes can be kept secret and access to the wider management functions can be handled on a user-by-user and organisation-by-organisation basis. A common question around using a database-backed configuration is how to programmatically add API definitions to your Tyk nodes, the Dashboard API allows much more fine-grained, secure and multi-user access to your Tyk cluster, and should be used to manage a database-backed Tyk node. The Tyk Dashboard API works seamlessly with the Tyk Dashboard (and the two come bundled together). ## Security Hierarchy The Dashboard API provides a more structured security layer to managing Tyk nodes. ### Organisations, APIs and Users With the Dashboard API and a database-backed Tyk setup, (and to an extent with file-based API setups - if diligence is used in naming and creating definitions), the following security model is applied to the management of Upstream APIs: * **Organisations**: All APIs are *owned* by an organisation, this is designated by the 'OrgID' parameter in the API Definition. * **Users**: All users created in the Dashboard belong to an organisation (unless an exception is made for super-administrative access). * **APIs**: All APIs belong to an Organisation and only Users that belong to that organisation can see the analytics for those APIs and manage their configurations. * **API Keys**: API Keys are designated by organisation, this means an API key that has full access rights will not be allowed to access the APIs of another organisation on the same system, but can have full access to all APIs within the organisation. * **Access Rights**: Access rights are stored with the key, this enables a key to give access to multiple APIs, this is defined by the session object in the core Tyk API. In order to use the Dashboard API, you'll need to get the 'Tyk Dashboard API Access Credentials' secret from your user profile on the Dashboard UI. The secret you set should then be sent along as a header with each Dashboard API Request in order for it to be successful: authorization: license: name: Mozilla Public License Version 2.0 url: https://github.com/TykTechnologies/tyk/blob/master/LICENSE.md title: Tyk Dashboard API version: 5.14.0 servers: - url: https://{tenant} variables: tenant: default: localhost:3000 description: Your dashboard host security: - bearerAuth: [] tags: - description: >- Use the endpoints under this tag to manage your certificates. You can add, delete and list certificates using these endpoints. name: Certificates - description: >- The Tyk Dashboard provides a full set of analytics functions and graphs that you can use to segment and view your API traffic and activity. externalDocs: description: Traffic Analytics. url: https://tyk.io/docs/tyk-dashboard-analytics/ name: Analytics - description: Use the endpoints in this tag to manage OAuth flow. externalDocs: description: OAuth Documentation url: >- https://tyk.io/docs/basic-config-and-security/security/authentication-authorization/oauth-2-0/ name: Oauth - description: > An API template is an asset managed by Tyk Dashboard that is used as the starting point - a blueprint - from which you can create a new Tyk OAS API definition.
Templates are used only during the creation of an API, they cannot be applied later. [Read more about API template assets here](https://tyk.io/docs/product-stack/tyk-dashboard/advanced-configurations/templates/template-overview/) externalDocs: description: API Templates full documentation. url: >- https://tyk.io/docs/product-stack/tyk-dashboard/advanced-configurations/templates/template-overview/ name: Assets - description: > The Tyk Dashboard permission system can be extended by writing custom rules using an Open Policy Agent (OPA). The rules engine works on top of your Dashboard API, which means you can control not only access rules, but also behaviour of all Dashboard APIs (except your public developer portal)
By default the Dashboard OPA engine is turned off, and you need to explicitly enable it via your Dashboard tyk_analytics.conf file.
You can use OPA rule to accomplish tasks like:
1. Prevent users from creating keyless APIs. 2. Assign specific categories to APIs created to certain user groups or users. 3. Control access for individual fields. For example, do not allow changing the API “active” status (e.g. deploy), unless you have a specific permission set. 4. And many more
[Read more about Tyk Open Policy Agent here](https://tyk.io/docs/tyk-dashboard/open-policy-agent/) externalDocs: description: Tyk Open Policy Agent Full Documentation. url: https://tyk.io/docs/tyk-dashboard/open-policy-agent/ name: Open Policy Agent - description: > These APIs helps you get,add and delete (CRUD) a list of additional (custom) permissions for your Dashboard users. You can use the created additional permissions with Open Policy Agent (OPA).
Once created, a custom permission will be added to standard list of user permissions.
You can also configure these custom permissions in the security.additional_permissions map in the Tyk Dashboard configuration file. You can check the [full documentation here](https://tyk.io/docs/tyk-dashboard-api/org/permissions/). externalDocs: description: Additional Permissions full documentation. url: https://tyk.io/docs/tyk-dashboard-api/org/permissions/ name: Additional Permissions - description: Get schemas. name: Schemas - description: > Manage MCP (Model Context Protocol) Proxies from Tyk Dashboard. MCP Proxies are Tyk OAS definitions with MCP-specific configuration in the `x-tyk-api-gateway` extension. Create/update requests are validated against the MCP JSON schema and a limited set of middleware is supported — restricted middleware (request/response transforms, URL rewrite, cache, mocks, request validation, internal) are rejected. name: MCP Proxies - description: > Webhooks are a great way to let external applications know about the status of a user, an API or an event that has occurred in the Tyk gateway
You can create webhooks that you can then re-use in your API definitions and assign to different Tyk Events such as quota violations or rate-limiting violations.
Each webhook require a target_path (which is an absolute URL that should be targeted by the webhook e.g https://httpbin.org/expired-keys) and a method which can be any of GET, PUT, POST, PATCH or DELETE.
Request types that do not support an encoded body will not have the event metadata encoded as part of the request. We would advise using POST where possible. name: Webhooks - description: >- Policies are a template that enable you to create access rules, usage quota and rate limits that can be applied to multiple keys. They are a useful way to manage large groups of users, and to enforce quota changes on a global scale across any number of keys that are using a policy. When used in conjunction with the portal, developers that enroll for API access will be given a key that is attached to a specific policy. The policy settings are refreshed every time a key attempts access, meaning that updating a policy will have an effect across any keys that are attached to it. externalDocs: description: Security Policies Documentation. url: >- https://tyk.io/docs/basic-config-and-security/security/security-policies/ name: Policies - description: >- When you have a large number of users and teams with different access requirements, instead of setting permissions per user, you can create a user group and configure the permissions for all users in the group. Note that a user can only belong to one group. externalDocs: description: Manage Tyk Dashboard User Groups. url: >- https://tyk.io/docs/basic-config-and-security/security/dashboard/create-user-groups/ name: UserGroup - description: >- Users have twofold access to the dashboard: they can access both the Dashboard API and the Dashboard itself, it is possible to generate users that have read-only access to certain sections of the dashboard and the underlying API. Use the endpoints in this tag to manage users. externalDocs: description: Manage Tyk Dashboard Users. url: >- https://tyk.io/docs/basic-config-and-security/security/dashboard/create-users/ name: Users - description: >- All keys that are used to access services via Tyk correspond to a session object that informs Tyk about the context of this particular token, like access rules and rate/quota allowance. externalDocs: description: API Key Management. url: https://tyk.io/docs/tyk-apis/tyk-dashboard-api/api-keys/ name: Keys - description: >- An API request made using Basic Authentication will have an Authorization header that contains the API key. The value of the Authorization header will be in the form:
`Basic base64Encode(username:password)`. externalDocs: description: Basic Authentication. url: >- https://tyk.io/docs/basic-config-and-security/security/authentication-authorization/basic-auth/ name: Basic Authentication - description: >- Tyk allows you to work with APIs that you’ve designed with the OpenAPI Specification version 3.0.x, making it even easier to get your API up and running. Use the endpoints in this tag to create,delete,import and update OAS APIs. externalDocs: description: Tyk OAS Documentation. url: https://tyk.io/docs/getting-started/key-concepts/high-level-concepts/ name: OAS APIs - description: >- Use the endpoints under this tags to update,add ,delete and fetch the classic APIs. name: APIs - description: >- The Dashboard SSO API allows you to implement custom authentication schemes for the Dashboard and Portal. Our Tyk Identity Broker (TIB) internally also uses this API. The Dashboard exposes the /api/sso Dashboard API which allows you to generate a temporary authentication token, valid for 60 seconds. externalDocs: description: Dashboard API Single Sign On. url: https://tyk.io/docs/tyk-apis/tyk-dashboard-api/sso/ name: Single Sign On - description: System API. name: System - description: Notifications for an organisation name: Organisation Notifications - description: Manage client Identity Providers (IdPs) for API-level JWT authentication. name: Client IdPs paths: /api/evaluations/sandbox: post: tags: - Evaluations summary: Run a sandbox evaluation against saved rulesets and saved APIs. description: > 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. operationId: sandboxEvaluation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SandboxEvaluationRequest' examples: saved-ruleset-saved-api: summary: >- UI sandbox — saved ruleset, saved API (Governance Tab "Test ruleset") value: ruleset_ids: - rs-payments-v1 api_ids: - petstore by-category-saved-api: summary: UI sandbox — run all rulesets in a category against this API value: categories: - payments - internal api_ids: - petstore responses: '200': description: > 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). content: application/json: schema: $ref: '#/components/schemas/SandboxEvaluationResponse' '400': description: > Validation failed: both or neither of `ruleset_ids` / `categories` set, `api_ids` missing or empty, removed `apis` field present (use `/api/evaluations/sandbox/oas`), classic API in set, batch over caps (`MaxSandboxAPIs`, `MaxSandboxRulesets`, `MaxSandboxCategories`), or invalid ruleset definition (whole-call engine transform error). content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '403': description: >- Forbidden — governance is disabled at deployment level (license / config feature flag), the user lacks the APIs permission, or (with API ownership enabled) a requested api_id is not owned by the caller. Sandbox evaluations are read-only previews, so `apis:read` is sufficient; `apis:deny` or a permissions map without an `apis` entry is rejected. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '404': description: Any `ruleset_ids` or `api_ids` entry not found within the org. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' components: schemas: SandboxEvaluationRequest: type: object required: - api_ids description: > 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. properties: ruleset_ids: type: array minItems: 1 maxItems: 20 items: type: string description: > 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. categories: type: array minItems: 1 maxItems: 10 items: type: string description: > 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. api_ids: type: array minItems: 1 maxItems: 10 items: type: string description: >- APIIDs of saved APIs in the caller's org. Classic (non-OAS) APIs are rejected. example: ruleset_ids: - rs-payments-v1 api_ids: - petstore SandboxEvaluationResponse: type: object required: - rulesets - issues - total - truncated - evaluated_apis - elapsed_ms - error_count - warn_count - info_count - hint_count properties: rulesets: type: array items: $ref: '#/components/schemas/SandboxRulesetSummary' description: > 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). issues: type: array items: $ref: '#/components/schemas/LintViolation' description: > 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`. total: type: integer description: Un-truncated issue count produced by the engine. truncated: type: boolean description: > 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: type: integer description: > 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: type: integer description: Run-wide severity-1 (warn) issue count, pre-truncation. info_count: type: integer description: Run-wide severity-2 (info) issue count, pre-truncation. hint_count: type: integer description: Run-wide severity-3 (hint) issue count, pre-truncation. evaluated_apis: type: integer description: > Number of APIs the engine actually applied rules against. Always 1 for `/sandbox/oas`. elapsed_ms: type: integer format: int64 description: Wall-clock duration of `engine.Evaluate`, in milliseconds. error: type: string description: > 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. ApiResponse: properties: ID: type: string Message: type: string Meta: {} Status: type: string type: object SandboxRulesetSummary: type: object required: - id - name - resource_type - active - action - error_count - warn_count - info_count - hint_count description: > Echo + rollup of one ruleset actually used in the run. Counts are computed pre-truncation from this ruleset's issues across all successfully evaluated pairs — trustworthy even when `issues` is capped. A ruleset whose evaluation errored shows zero counts alongside a non-null response `error`; gates must check `error` first. properties: id: type: string description: Stable RulesetID. name: type: string resource_type: type: string enum: - oas-api - mcp-api active: type: boolean description: >- Whether the ruleset is currently active. FE shows an 'inactive' hint when `false`. action: type: string enum: - none - warn description: > Verbatim echo of the ruleset's configured action (ruleset CRUD enum — new values appear here without a sandbox schema change). Lets clients gate on "did a ruleset whose action matters produce violations" without scanning `issues`. error_count: type: integer description: Error-severity issues from this ruleset, pre-truncation. warn_count: type: integer description: Warn-severity issues from this ruleset, pre-truncation. info_count: type: integer description: Info-severity issues from this ruleset, pre-truncation. hint_count: type: integer description: Hint-severity issues from this ruleset, pre-truncation. LintViolation: type: object description: A single rule violation produced by one governance evaluation run. properties: _id: type: string description: > Row identifier. Persisted violations carry a MongoDB ObjectId hex; sandbox evaluations persist nothing, so their rows carry a deterministic 16-hex content hash instead (stable across re-runs of identical inputs). org_id: type: string api_id: type: string ruleset_id: type: string ruleset_name: type: string description: >- Human-readable ruleset name resolved from tyk_rulesets. Omitted when the referenced ruleset no longer exists (e.g. it was deleted while an evaluation was in flight); sandbox evaluation responses always include it. rule_id: type: string description: Spectral rule name that fired. rule_summary: type: string description: Short human-readable description of the rule. how_to_fix: type: string description: Remediation guidance for this rule. message: type: string description: Violation message produced by the rule engine. severity: type: string enum: - error - warn - info - hint severity_order: type: integer description: Numeric sort key (1=error, 2=warn, 3=info, 4=hint). path: type: string description: Dot-joined JSON path to the violating node (e.g. `paths./pets.get`). location: $ref: '#/components/schemas/LintViolationLocation' created_at: format: date-time type: string LintViolationLocation: type: object description: Source position of the violation in the OAS document. properties: start_line: type: integer start_char: type: integer end_line: type: integer end_char: type: integer securitySchemes: bearerAuth: description: The Tyk Dashboard API Access Credentials scheme: bearer type: http ````