Skip to main content

Health and version API

Documentation for Tutela v3.9.0.

Use these three read-only endpoints to check your gateway before investigating a failed request. They do not require an access credential. AI requests and administrative operations have separate authentication requirements.

Before you start​

Run the examples from a terminal with access to your deployment. Replace the example hostname with the HTTPS address you use to open Tutela; do not use the documentation website's address.

TUTELA_URL='https://your-tutela.example.com'

The examples print the HTTP status and response body. If the connection times out, check your network, DNS and load balancer. If certificate validation fails, have the operator correct the certificate or trust chain; keep TLS verification enabled.

GET /.well-known/oauth-protected-resource​

MCP sign-in discovery

Returns a public JSON document that tells an MCP client where to sign in to Tutela for the plain MCP address. A client reads it after its first call is refused for missing sign-in. It contains no tenant or user data.

curl --connect-timeout 10 --max-time 20 --include \
"$TUTELA_URL/.well-known/oauth-protected-resource"

GET /.well-known/oauth-protected-resource/v1/mcp​

MCP sign-in discovery

Returns a public JSON document that tells an MCP client where to sign in to Tutela for the plain MCP address. A client reads it after its first call is refused for missing sign-in. It contains no tenant or user data.

curl --connect-timeout 10 --max-time 20 --include \
"$TUTELA_URL/.well-known/oauth-protected-resource/v1/mcp"

GET /.well-known/oauth-protected-resource/v1/mcp/connections/{connectionId}​

MCP sign-in discovery for one server

Returns a public JSON document that tells an MCP client where to sign in to Tutela for one registered server's MCP address. It names only that address and Tutela's sign-in server, and contains no tenant or user data.

curl --connect-timeout 10 --max-time 20 --include \
"$TUTELA_URL/.well-known/oauth-protected-resource/v1/mcp/connections/{connectionId}"

GET /.well-known/oauth-protected-resource/v1/mcp/workspace​

MCP sign-in discovery for the combined address

Returns a public JSON document that tells an MCP client where to sign in to Tutela for the combined MCP address, which offers the tools of all your organization's MCP servers. It contains no tenant or user data.

curl --connect-timeout 10 --max-time 20 --include \
"$TUTELA_URL/.well-known/oauth-protected-resource/v1/mcp/workspace"

GET /.well-known/oauth-authorization-server​

Sign-in server details for MCP clients

Returns a public JSON document describing Tutela's sign-in server for MCP clients: where a client signs a person in and which sign-in methods are supported. It contains no tenant or user data.

curl --connect-timeout 10 --max-time 20 --include \
"$TUTELA_URL/.well-known/oauth-authorization-server"

GET /oauth/authorize​

Start an MCP client's sign-in

An MCP client sends the person's browser here to sign in to Tutela with your organization's usual sign-in and approve the client. The client must use PKCE with S256 and name the MCP address it wants to use. If the person allows it, the browser returns to the client with a one-time code; if they cancel, the client is told access was denied.

curl --connect-timeout 10 --max-time 20 --include \
"$TUTELA_URL/oauth/authorize"

POST /oauth/token​

Get or refresh an MCP client's tokens

A registered MCP client exchanges its one-time code for a short-lived access token and a refresh token, and later swaps the refresh token for new ones. Each refresh token works once. The tokens stop working when the person is disabled, signs out of every session, has their password changed or reset, or removes the assistant.

curl --connect-timeout 10 --max-time 20 --include \
--request POST \
"$TUTELA_URL/oauth/token"

POST /oauth/revoke​

Revoke an MCP client's token

An MCP client ends its own access by revoking its access or refresh token. Its later calls and refreshes are refused. Revoking an unknown token changes nothing.

curl --connect-timeout 10 --max-time 20 --include \
--request POST \
"$TUTELA_URL/oauth/revoke"

POST /oauth/register​

Register an MCP client

An MCP client, such as an AI assistant, registers itself here before it signs a person in to Tutela. It receives a client ID and no secret. Registering grants no access to anything; a person must sign in and approve the client first.

curl --connect-timeout 10 --max-time 20 --include \
--request POST \
--header 'Content-Type: application/json' \
--data '{"client_name":"My assistant","redirect_uris":["http://127.0.0.1:33418/callback"],"token_endpoint_auth_method":"none"}' \
"$TUTELA_URL/oauth/register"

GET /healthz​

Liveness check

Returns HTTP 200 with a JSON body such as {"status":"ok","version":"3.9.0"} when the gateway process is running. The version shown here is illustrative; compare the actual value with your installation record.

Liveness does not check the AI provider or demonstrate inspection. Continue with readiness and a synthetic request through your configured client. A timeout or connection failure requires checking the network, DNS and service availability.

curl --connect-timeout 10 --max-time 20 --include \
"$TUTELA_URL/healthz"

GET /readyz​

Readiness check

Returns HTTP 200 with {"status":"ready"} when the gateway's configured dependency checks succeed. The response may include additional operational metadata. This check covers configured database connectivity and cache network connectivity; it is not a full test of every product workflow.

HTTP 503 with {"status":"not_ready","reason":"database unavailable"} or {"status":"not_ready","reason":"redis unavailable"} identifies a failed dependency check. Open Settings > Support & diagnostics > Service health, record the reason and have the deployment operator repair that dependency before retrying.

curl --connect-timeout 10 --max-time 20 --include \
"$TUTELA_URL/readyz"

GET /v1/version​

Deployed version

Returns HTTP 200 with gateway build information inside the JSON data object: app_version identifies the release, build_hash identifies the build, build_date records its build date, and go_version identifies its runtime. The meta object contains request context such as request_id and timestamp.

Record data.app_version and the observation time when reporting a problem. A dev or unknown build value does not establish which supported release is installed; ask the operator to check the installed artifact. Different clients can have different versions, so record the affected extension or SDK version separately.

curl --connect-timeout 10 --max-time 20 --include \
"$TUTELA_URL/v1/version"

Interpret the results​

ResultWhat to do
Liveness and readiness return HTTP 200The gateway is available. Test the affected customer workflow separately.
Liveness succeeds but readiness failsOpen Settings > Support & diagnostics > Service health and inspect the failed dependency.
Both checks fail or time outFollow Service unavailable.
Checks pass but names or money amounts are not detectedA detector can fail to load while readiness passes. An administrator can call the authenticated GET /v1/classify/health: ner_status: load_failed means name and amount detection is unavailable. The in-app Platform guardrails article explains the effect.
Version differs from your installation recordAsk the operator to compare the installed release with the intended update before changing clients.

A successful health check does not demonstrate that a policy blocked a request or that an AI provider responded. Use Verify your installation for those checks. When reporting a problem, include the endpoint, status, observation time and version; omit credentials and customer content.