Custom REST Integrations

If your internal tool exposes a REST API with an OpenAPI specification, a Custom REST Integration is the fastest way to let the SRI Agent call it. Each endpoint becomes a typed tool with scoped authentication and optional approval gates. Use this path when the integration is read-heavy, the tool already has an OpenAPI spec, and you do not need streaming or rich bidirectional behaviour.

When to choose REST over MCP

REST is best for

Tools with existing OpenAPI specs, simple request-response flows, single endpoints per operation.

MCP is best for

Streaming responses, coordinated multi-call workflows, richer tool schemas. See Custom MCP Servers.

What RubixKube reads from your spec

OpenAPI field	How it maps
`paths` and `operationId`	One tool per endpoint
`summary` and `description`	Tool description, used for intent matching
`parameters` and `requestBody`	Argument schema, passed to the planner
`responses`	Return schema, used when interpreting results
`security` schemes	Auth requirement for the endpoint

RubixKube validates against OpenAPI 3.0 and 3.1.

Register the integration

Upload the spec

Open Integrations → Custom REST and upload the OpenAPI document (YAML or JSON). The console parses it and lists every endpoint.

Pick endpoints to enable

Select the endpoints you want exposed as tools. Start narrow: usually read endpoints first, mutating ones once you have tested.

Choose an auth type

API key
OAuth 2.0
mTLS
Custom header or signed request

Simplest option. The console stores the key in the workspace secret vault and injects it on each call.

See OAuth and Auth Types for the full reference.

Approval rules

For mutating endpoints (POST, PUT, PATCH, DELETE), require approval via the Guardian. Reads can run freely.

Test

Use the test pane in the console to call each enabled endpoint. Confirm auth, request shape, and response parsing before going live.

Scope to skills

Add the endpoints you enabled to the allowed_tools list of the skills that need them. Do not enable mutating endpoints globally.

Design guidelines

Describe endpoints well

Good OpenAPI descriptions make the difference between an agent calling the right endpoint and guessing. Spend five minutes polishing summaries.

Use enums and ranges

Narrow argument types mean higher planning accuracy. Free-form strings are the enemy.

Paginate

Long lists should paginate. The agent respects cursor-based or offset-based schemes out of the box.

Structured errors

Return well-typed error payloads. The planner uses error shapes when deciding whether to retry, adjust arguments, or surface to the user.

Safety and Guardian

Every mutating endpoint passes through the Guardian approval flow. Read endpoints can be called without approval, but can still be scoped by environment or by time window. Nothing becomes callable before you have tested it in the console.

Troubleshooting

Upload fails with 'invalid OpenAPI'

Validate your spec against the 3.x spec first (e.g. swagger-cli validate). RubixKube is strict about required fields.

Endpoint returns auth errors

Verify the secret in the vault and the scheme in the OpenAPI security block. For OAuth flows, make sure the token scope matches what the endpoint requires.

Agent keeps calling the wrong endpoint

Sharpen the summary and description on the endpoint it should prefer. Intent matching depends heavily on good text.

Custom MCP Servers

When REST is not enough.

OAuth and Auth Types

Reference for every supported authentication method.

How to add custom integrations

Walkthrough of the full custom integration flow.

Documentation

​When to choose REST over MCP