request_route #
Generated automatically from the published contract sources.
Build metadata: Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.
A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/request_route, with a bearer credential and the action's payload as the JSON body.
Contract description #
Make one HTTP request to a route of your own deployed application and read its status, headers, and body. After a deploy, call it for each changed route that reads, where your shell cannot make the request. Pass the application, the method, `GET` or `POST`, and the path, such as `/health`; `environment` is `production` where you give none. A `POST` reaches your running code and can change its data. The platform builds the address from the environment's hostname and takes no host from you. The rest: `read_documentation` page /cloud/reference/actions/request-route/.
More about this action #
The address is the environment's own hostname under the platform's serving suffix, built by the platform. The path cannot change the host, and a path opening with `//` is refused `invalid_request`. The hostname is resolved, and the connection is made only to a public address that check read, so an address outside public unicast is refused `route_unreachable` before any connection.
A redirect is followed only to the same hostname over https on port 443, at most five hops, each checked again. A redirect to another host, port, or scheme comes back as the result, its status and `location` intact. A 301, 302, or 303 after a `POST` is followed with a `GET` and no body.
The request carries your headers and body, the HTTP client's defaults where you set none, and no header or credential of the platform's. `accept-encoding` is always `identity`, and a body the application encodes anyway comes back decoded. You may set at most 16 headers. `accept-encoding`, the hop headers, and the platform's own header families are refused `invalid_request`, the detail giving the header.
The body comes back as text where it is UTF-8, else in base64, as `body_encoding` says, up to 64 KiB, counted after any decoding. Past that the connection ends and `truncated` is true. The call ends within 20 seconds, else it is refused `route_unreachable` with the reason `timeout`. One account makes at most 60 calls a minute, past which the call is refused `rate_capped`.
The call refuses nothing on production's data. After a deploy, the deploy skill requests each changed route that reads and none that writes; the release skill's check requests a route that writes only where the account's owner calls it safe for production's data. An environment that serves no version is refused `never_deployed`. The platform's record of the call keeps the method and the path without its query, never the headers or the body.
Access and action metadata #
{
"name": "request_route",
"resource": "environment",
"tier": "reversible",
"product": "cloud",
"summary": "Make one HTTP request to a route of your own deployed application and read what it returns: the status, the headers, and the body. Call it after a deploy, from a tool with no shell, for each changed route that reads. Pass the application, the method, `GET` or `POST`, and the path, opening with one `/`. `environment` is `production` where you give none, so give `development` to request the development copy. The platform builds the address from the environment's own hostname and takes no host from you. A `POST` reaches your running code and can change its data, production's included. A redirect is followed only on the same hostname over https, at most five; any other redirect comes back as the result. The body comes back up to 64 KiB, `truncated` true past it, and the call ends within 20 seconds. One account makes at most 60 calls a minute.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": true
}
}
MCP catalog entry #
{
"name": "request_route",
"title": "Request a route",
"tier": "reversible",
"scenario": "API-L0-26",
"summary": "Make one HTTP request to a route of your own deployed application and read its status, headers, and body. After a deploy, call it for each changed route that reads, where your shell cannot make the request. Pass the application, the method, `GET` or `POST`, and the path, such as `/health`; `environment` is `production` where you give none. A `POST` reaches your running code and can change its data. The platform builds the address from the environment's hostname and takes no host from you. The rest: `read_documentation` page /cloud/reference/actions/request-route/.",
"owners": [
"API-L0-26",
"MAPI-28",
"SVC-L0-07",
"EGW-L0-01",
"PLD-L0-67",
"PLD-L0-59"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["application","method","path"] |
| / |
The application id, from `list_applications`: an application of your own account. Type: string |
| / |
The environment whose route you request: `production` where you give none, whatever the deploy target. One the application does not have is refused `environment_not_created`, and one serving no version `never_deployed`. Type: string Allowed values: ["development","production"] |
| / |
`GET` or `POST`. A `POST` reaches your running code and can change its data. Type: string Allowed values: ["GET","POST"] |
| / |
The route on the application, opening with one `/`, such as `/health` or `/orders?limit=5`, at most 2,048 characters with its query. Percent-encode a space. A path opening with `//`, or holding a space or a control character, is refused `invalid_request`. Type: string Maximum length: 2048 |
| / |
Optional: request headers, at most 16, each value a string with no line break. `accept-encoding`, `host`, `content-length`, the other hop headers, and the platform's header families, such as `x-forwarded-`, are refused `invalid_request`. Type: object maxProperties: 16 |
| / |
Type: string |
| / |
Optional: the request body as text, sent with `POST` alone, at most 64 KiB as UTF-8. Set its `content-type` in `headers`. Type: string |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","application","environment","method","url","status","headers","body","body_encoding","body_bytes","truncated","redirects","elapsed_ms"] |
| / |
Required value: 1 |
| / |
The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
The application id. Type: string |
| / |
The environment requested: `production` where the call gave none. Type: string Allowed values: ["development","production"] |
| / |
The call's own method, kept where a redirect was followed with `GET` after a `POST`. Type: string Allowed values: ["GET","POST"] |
| / |
The last address requested: the environment's hostname and the path, or the same-host address the last redirect followed gave. Type: string |
| / |
The HTTP status of the last response, a redirect the call did not follow included. Type: integer |
| / |
The last response's headers, each name in lower case with one string value, repeated `set-cookie` values joined by a line break. Type: object |
| / |
Type: string |
| / |
The response body, up to 64 KiB, counted after any decoding: the text where the bytes are UTF-8, else base64. Type: string |
| / |
`utf-8` where `body` is the text itself, `base64` where the bytes are not UTF-8. Type: string Allowed values: ["utf-8","base64"] |
| / |
The size of `body` in bytes: of its UTF-8 text, or of the bytes the base64 carries. Type: integer Minimum: 0 |
| / |
True where the body passed 64 KiB, counted after any decoding, so the connection was ended and `body` holds the first 64 KiB, a cut last character left out of UTF-8 text. Type: boolean |
| / |
How many same-host redirects the call followed, at most five. Type: integer Minimum: 0 Maximum: 5 |
| / |
The call's time from its first address check to the end of the body's read, in milliseconds. Type: integer Minimum: 0 |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"application",
"method",
"path"
],
"properties": {
"application": {
"type": "string",
"description": "The application id, from `list_applications`: an application of your own account."
},
"environment": {
"type": "string",
"enum": [
"development",
"production"
],
"description": "The environment whose route you request: `production` where you give none, whatever the deploy target. One the application does not have is refused `environment_not_created`, and one serving no version `never_deployed`."
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
],
"description": "`GET` or `POST`. A `POST` reaches your running code and can change its data."
},
"path": {
"type": "string",
"maxLength": 2048,
"description": "The route on the application, opening with one `/`, such as `/health` or `/orders?limit=5`, at most 2,048 characters with its query. Percent-encode a space. A path opening with `//`, or holding a space or a control character, is refused `invalid_request`."
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"maxProperties": 16,
"description": "Optional: request headers, at most 16, each value a string with no line break. `accept-encoding`, `host`, `content-length`, the other hop headers, and the platform's header families, such as `x-forwarded-`, are refused `invalid_request`."
},
"body": {
"type": "string",
"description": "Optional: the request body as text, sent with `POST` alone, at most 64 KiB as UTF-8. Set its `content-type` in `headers`."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"application",
"environment",
"method",
"url",
"status",
"headers",
"body",
"body_encoding",
"body_bytes",
"truncated",
"redirects",
"elapsed_ms"
],
"properties": {
"contract_version": {
"const": 1
},
"reference": {
"type": "string",
"pattern": "^[0-9a-f]{10}$",
"description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
},
"application": {
"type": "string",
"description": "The application id."
},
"environment": {
"type": "string",
"enum": [
"development",
"production"
],
"description": "The environment requested: `production` where the call gave none."
},
"method": {
"type": "string",
"enum": [
"GET",
"POST"
],
"description": "The call's own method, kept where a redirect was followed with `GET` after a `POST`."
},
"url": {
"type": "string",
"description": "The last address requested: the environment's hostname and the path, or the same-host address the last redirect followed gave."
},
"status": {
"type": "integer",
"description": "The HTTP status of the last response, a redirect the call did not follow included."
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "The last response's headers, each name in lower case with one string value, repeated `set-cookie` values joined by a line break."
},
"body": {
"type": "string",
"description": "The response body, up to 64 KiB, counted after any decoding: the text where the bytes are UTF-8, else base64."
},
"body_encoding": {
"type": "string",
"enum": [
"utf-8",
"base64"
],
"description": "`utf-8` where `body` is the text itself, `base64` where the bytes are not UTF-8."
},
"body_bytes": {
"type": "integer",
"minimum": 0,
"description": "The size of `body` in bytes: of its UTF-8 text, or of the bytes the base64 carries."
},
"truncated": {
"type": "boolean",
"description": "True where the body passed 64 KiB, counted after any decoding, so the connection was ended and `body` holds the first 64 KiB, a cut last character left out of UTF-8 text."
},
"redirects": {
"type": "integer",
"minimum": 0,
"maximum": 5,
"description": "How many same-host redirects the call followed, at most five."
},
"elapsed_ms": {
"type": "integer",
"minimum": 0,
"description": "The call's time from its first address check to the end of the body's read, in milliseconds."
}
}
}
}
Shared contracts #
- Refusals: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md