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
| Result | What to do |
|---|---|
| Liveness and readiness return HTTP 200 | The gateway is available. Test the affected customer workflow separately. |
| Liveness succeeds but readiness fails | Open Settings > Support & diagnostics > Service health and inspect the failed dependency. |
| Both checks fail or time out | Follow Service unavailable. |
| Checks pass but names or money amounts are not detected | A 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 record | Ask 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.