{ "openapi": "3.1.0", "info": { "title": "Latch Proxy API", "version": "0.2.0", "description": "Latch is a policy proxy for credentials.\n\nA **Secret** is a raw credential, stored server-side and never returned to you.\nA **Latch** is a scoped access token (`lat_...`) derived from a Secret, with its\nown upstream URL and an ordered **filter pipeline**.\n\nYou call `/proxy/` with the Latch token. The pipeline evaluates (the first\nfilter to deny short-circuits), and only then does Latch inject the real\ncredential and forward your request upstream. The credential never reaches you,\nand a denied request never reaches the upstream.\n\nThis document covers the entire public API. Secrets and latches are created and\nmanaged in the Latch dashboard; there is no public management API, and the\n`/admin/*` routes you may see in network traces are the dashboard's own backend,\nnot a supported interface.", "contact": { "name": "Latch", "url": "https://onlatch.com" } }, "servers": [ { "url": "https://onlatch.com", "description": "Production" } ], "tags": [ { "name": "Proxy", "description": "The data plane: forward a request with a scoped credential." }, { "name": "Discovery", "description": "What can this token do? Endpoints an agent can call about itself." } ], "components": { "securitySchemes": { "latchToken": { "type": "http", "scheme": "bearer", "bearerFormat": "lat_...", "description": "Every call carries a Latch access token:\n\n Authorization: Bearer lat_...\n\nThe token identifies the latch, which in turn binds the upstream, the credential,\nand the policy pipeline. It is the only credential you ever hold." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } }, "Denial": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Request denied by policy" }, "requestId": { "type": "string", "example": "req_4a1f2c" }, "latchId": { "type": "string", "example": "lnk_9f3c1a2b" }, "mount": { "type": "string", "description": "The mount that matched, when the latch has more than one." }, "deniedBy": { "type": "string", "description": "Name of the first filter to deny. The pipeline short-circuits there.", "example": "Completions Only" }, "reason": { "type": "string", "description": "Why that filter denied.", "example": "/v1/embeddings not in allowlist" } } } } }, "security": [ { "latchToken": [] } ], "paths": { "/proxy/{path}": { "get": { "tags": [ "Proxy" ], "operationId": "forwardRequestGet", "summary": "Forward a request upstream through the policy pipeline", "description": "Evaluates the latch's filter pipeline against this request. If every filter allows it, Latch\ninjects the real credential and forwards the request to the latch's upstream, then returns the\nupstream's response to you verbatim (status, headers, and body, including streamed responses).\n\nThe path after `/proxy/` is passed through to the upstream, so `/proxy/v1/chat/completions`\nreaches `/v1/chat/completions`. Query strings are forwarded. Non-JSON bodies are\nforwarded byte-for-byte.\n\nAll HTTP methods are accepted, not only the ones enumerated here; the pipeline decides which\nthe latch actually permits (see the `method` filter).", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } }, { "name": "path", "in": "path", "required": true, "description": "Upstream path, forwarded as-is.", "schema": { "type": "string" }, "example": "v1/chat/completions" } ], "responses": { "200": { "description": "The upstream's response, returned verbatim.", "headers": { "x-latch-request-id": { "description": "Request correlation id. Matches the `requestId` in error bodies and the Activity log.", "schema": { "type": "string" } }, "x-latch-link-id": { "description": "The latch id. NOTE the legacy `link` spelling: the product noun was renamed Link -> Latch, and this header kept its old name for compatibility. It is the latch id.", "schema": { "type": "string" } }, "x-latch-mount": { "description": "The mount that served the request, when the latch has more than one.", "schema": { "type": "string" } } }, "content": { "*/*": { "schema": {} } } }, "400": { "description": "Malformed request (for example, the evaluation-depth ceiling was exceeded).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "403": { "description": "Denied by policy. The pipeline evaluated and a filter said no; the request never reached the upstream and the credential was never used. `deniedBy` names the filter.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Request denied by policy" }, "requestId": { "type": "string", "example": "req_4a1f2c" }, "latchId": { "type": "string", "example": "lnk_9f3c1a2b" }, "mount": { "type": "string", "description": "The mount that matched, when the latch has more than one." }, "deniedBy": { "type": "string", "description": "Name of the first filter to deny. The pipeline short-circuits there.", "example": "Completions Only" }, "reason": { "type": "string", "description": "Why that filter denied.", "example": "/v1/embeddings not in allowlist" } } } } } }, "404": { "description": "No mount on this latch matches the request path.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "429": { "description": "Rate limited. Sent when a `rate_limit` filter trips, or when the per-latch global ceiling does. `Retry-After` gives the wait in seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "502": { "description": "The upstream, or the policy enclave, could not be reached or returned garbage.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } }, "post": { "tags": [ "Proxy" ], "operationId": "forwardRequestPost", "summary": "Forward a request upstream through the policy pipeline", "description": "Evaluates the latch's filter pipeline against this request. If every filter allows it, Latch\ninjects the real credential and forwards the request to the latch's upstream, then returns the\nupstream's response to you verbatim (status, headers, and body, including streamed responses).\n\nThe path after `/proxy/` is passed through to the upstream, so `/proxy/v1/chat/completions`\nreaches `/v1/chat/completions`. Query strings are forwarded. Non-JSON bodies are\nforwarded byte-for-byte.\n\nAll HTTP methods are accepted, not only the ones enumerated here; the pipeline decides which\nthe latch actually permits (see the `method` filter).", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } }, { "name": "path", "in": "path", "required": true, "description": "Upstream path, forwarded as-is.", "schema": { "type": "string" }, "example": "v1/chat/completions" } ], "requestBody": { "required": false, "description": "Forwarded to the upstream unchanged. Any content type.", "content": { "application/json": { "schema": { "type": "object" } }, "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "The upstream's response, returned verbatim.", "headers": { "x-latch-request-id": { "description": "Request correlation id. Matches the `requestId` in error bodies and the Activity log.", "schema": { "type": "string" } }, "x-latch-link-id": { "description": "The latch id. NOTE the legacy `link` spelling: the product noun was renamed Link -> Latch, and this header kept its old name for compatibility. It is the latch id.", "schema": { "type": "string" } }, "x-latch-mount": { "description": "The mount that served the request, when the latch has more than one.", "schema": { "type": "string" } } }, "content": { "*/*": { "schema": {} } } }, "400": { "description": "Malformed request (for example, the evaluation-depth ceiling was exceeded).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "403": { "description": "Denied by policy. The pipeline evaluated and a filter said no; the request never reached the upstream and the credential was never used. `deniedBy` names the filter.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Request denied by policy" }, "requestId": { "type": "string", "example": "req_4a1f2c" }, "latchId": { "type": "string", "example": "lnk_9f3c1a2b" }, "mount": { "type": "string", "description": "The mount that matched, when the latch has more than one." }, "deniedBy": { "type": "string", "description": "Name of the first filter to deny. The pipeline short-circuits there.", "example": "Completions Only" }, "reason": { "type": "string", "description": "Why that filter denied.", "example": "/v1/embeddings not in allowlist" } } } } } }, "404": { "description": "No mount on this latch matches the request path.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "429": { "description": "Rate limited. Sent when a `rate_limit` filter trips, or when the per-latch global ceiling does. `Retry-After` gives the wait in seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "502": { "description": "The upstream, or the policy enclave, could not be reached or returned garbage.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } }, "put": { "tags": [ "Proxy" ], "operationId": "forwardRequestPut", "summary": "Forward a request upstream through the policy pipeline", "description": "Evaluates the latch's filter pipeline against this request. If every filter allows it, Latch\ninjects the real credential and forwards the request to the latch's upstream, then returns the\nupstream's response to you verbatim (status, headers, and body, including streamed responses).\n\nThe path after `/proxy/` is passed through to the upstream, so `/proxy/v1/chat/completions`\nreaches `/v1/chat/completions`. Query strings are forwarded. Non-JSON bodies are\nforwarded byte-for-byte.\n\nAll HTTP methods are accepted, not only the ones enumerated here; the pipeline decides which\nthe latch actually permits (see the `method` filter).", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } }, { "name": "path", "in": "path", "required": true, "description": "Upstream path, forwarded as-is.", "schema": { "type": "string" }, "example": "v1/chat/completions" } ], "requestBody": { "required": false, "description": "Forwarded to the upstream unchanged. Any content type.", "content": { "application/json": { "schema": { "type": "object" } }, "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "The upstream's response, returned verbatim.", "headers": { "x-latch-request-id": { "description": "Request correlation id. Matches the `requestId` in error bodies and the Activity log.", "schema": { "type": "string" } }, "x-latch-link-id": { "description": "The latch id. NOTE the legacy `link` spelling: the product noun was renamed Link -> Latch, and this header kept its old name for compatibility. It is the latch id.", "schema": { "type": "string" } }, "x-latch-mount": { "description": "The mount that served the request, when the latch has more than one.", "schema": { "type": "string" } } }, "content": { "*/*": { "schema": {} } } }, "400": { "description": "Malformed request (for example, the evaluation-depth ceiling was exceeded).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "403": { "description": "Denied by policy. The pipeline evaluated and a filter said no; the request never reached the upstream and the credential was never used. `deniedBy` names the filter.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Request denied by policy" }, "requestId": { "type": "string", "example": "req_4a1f2c" }, "latchId": { "type": "string", "example": "lnk_9f3c1a2b" }, "mount": { "type": "string", "description": "The mount that matched, when the latch has more than one." }, "deniedBy": { "type": "string", "description": "Name of the first filter to deny. The pipeline short-circuits there.", "example": "Completions Only" }, "reason": { "type": "string", "description": "Why that filter denied.", "example": "/v1/embeddings not in allowlist" } } } } } }, "404": { "description": "No mount on this latch matches the request path.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "429": { "description": "Rate limited. Sent when a `rate_limit` filter trips, or when the per-latch global ceiling does. `Retry-After` gives the wait in seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "502": { "description": "The upstream, or the policy enclave, could not be reached or returned garbage.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } }, "patch": { "tags": [ "Proxy" ], "operationId": "forwardRequestPatch", "summary": "Forward a request upstream through the policy pipeline", "description": "Evaluates the latch's filter pipeline against this request. If every filter allows it, Latch\ninjects the real credential and forwards the request to the latch's upstream, then returns the\nupstream's response to you verbatim (status, headers, and body, including streamed responses).\n\nThe path after `/proxy/` is passed through to the upstream, so `/proxy/v1/chat/completions`\nreaches `/v1/chat/completions`. Query strings are forwarded. Non-JSON bodies are\nforwarded byte-for-byte.\n\nAll HTTP methods are accepted, not only the ones enumerated here; the pipeline decides which\nthe latch actually permits (see the `method` filter).", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } }, { "name": "path", "in": "path", "required": true, "description": "Upstream path, forwarded as-is.", "schema": { "type": "string" }, "example": "v1/chat/completions" } ], "requestBody": { "required": false, "description": "Forwarded to the upstream unchanged. Any content type.", "content": { "application/json": { "schema": { "type": "object" } }, "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "The upstream's response, returned verbatim.", "headers": { "x-latch-request-id": { "description": "Request correlation id. Matches the `requestId` in error bodies and the Activity log.", "schema": { "type": "string" } }, "x-latch-link-id": { "description": "The latch id. NOTE the legacy `link` spelling: the product noun was renamed Link -> Latch, and this header kept its old name for compatibility. It is the latch id.", "schema": { "type": "string" } }, "x-latch-mount": { "description": "The mount that served the request, when the latch has more than one.", "schema": { "type": "string" } } }, "content": { "*/*": { "schema": {} } } }, "400": { "description": "Malformed request (for example, the evaluation-depth ceiling was exceeded).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "403": { "description": "Denied by policy. The pipeline evaluated and a filter said no; the request never reached the upstream and the credential was never used. `deniedBy` names the filter.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Request denied by policy" }, "requestId": { "type": "string", "example": "req_4a1f2c" }, "latchId": { "type": "string", "example": "lnk_9f3c1a2b" }, "mount": { "type": "string", "description": "The mount that matched, when the latch has more than one." }, "deniedBy": { "type": "string", "description": "Name of the first filter to deny. The pipeline short-circuits there.", "example": "Completions Only" }, "reason": { "type": "string", "description": "Why that filter denied.", "example": "/v1/embeddings not in allowlist" } } } } } }, "404": { "description": "No mount on this latch matches the request path.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "429": { "description": "Rate limited. Sent when a `rate_limit` filter trips, or when the per-latch global ceiling does. `Retry-After` gives the wait in seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "502": { "description": "The upstream, or the policy enclave, could not be reached or returned garbage.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } }, "delete": { "tags": [ "Proxy" ], "operationId": "forwardRequestDelete", "summary": "Forward a request upstream through the policy pipeline", "description": "Evaluates the latch's filter pipeline against this request. If every filter allows it, Latch\ninjects the real credential and forwards the request to the latch's upstream, then returns the\nupstream's response to you verbatim (status, headers, and body, including streamed responses).\n\nThe path after `/proxy/` is passed through to the upstream, so `/proxy/v1/chat/completions`\nreaches `/v1/chat/completions`. Query strings are forwarded. Non-JSON bodies are\nforwarded byte-for-byte.\n\nAll HTTP methods are accepted, not only the ones enumerated here; the pipeline decides which\nthe latch actually permits (see the `method` filter).", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } }, { "name": "path", "in": "path", "required": true, "description": "Upstream path, forwarded as-is.", "schema": { "type": "string" }, "example": "v1/chat/completions" } ], "responses": { "200": { "description": "The upstream's response, returned verbatim.", "headers": { "x-latch-request-id": { "description": "Request correlation id. Matches the `requestId` in error bodies and the Activity log.", "schema": { "type": "string" } }, "x-latch-link-id": { "description": "The latch id. NOTE the legacy `link` spelling: the product noun was renamed Link -> Latch, and this header kept its old name for compatibility. It is the latch id.", "schema": { "type": "string" } }, "x-latch-mount": { "description": "The mount that served the request, when the latch has more than one.", "schema": { "type": "string" } } }, "content": { "*/*": { "schema": {} } } }, "400": { "description": "Malformed request (for example, the evaluation-depth ceiling was exceeded).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "403": { "description": "Denied by policy. The pipeline evaluated and a filter said no; the request never reached the upstream and the credential was never used. `deniedBy` names the filter.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Request denied by policy" }, "requestId": { "type": "string", "example": "req_4a1f2c" }, "latchId": { "type": "string", "example": "lnk_9f3c1a2b" }, "mount": { "type": "string", "description": "The mount that matched, when the latch has more than one." }, "deniedBy": { "type": "string", "description": "Name of the first filter to deny. The pipeline short-circuits there.", "example": "Completions Only" }, "reason": { "type": "string", "description": "Why that filter denied.", "example": "/v1/embeddings not in allowlist" } } } } } }, "404": { "description": "No mount on this latch matches the request path.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "429": { "description": "Rate limited. Sent when a `rate_limit` filter trips, or when the per-latch global ceiling does. `Retry-After` gives the wait in seconds.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "502": { "description": "The upstream, or the policy enclave, could not be reached or returned garbage.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } } }, "/proxy/.well-known/latch-capabilities": { "get": { "tags": [ "Discovery" ], "operationId": "getCapabilities", "summary": "What is this latch allowed to do?", "description": "Returns the latch's effective capabilities: its mounts, their upstreams, and the filters that\nwill be applied. An agent can call this to discover its own scope instead of probing the\nupstream and collecting denials.\n\nReflects the *effective* pipeline, so inherited filters from a parent latch are included.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } } ], "responses": { "200": { "description": "The latch's capabilities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "latchId": { "type": "string", "example": "lnk_9f3c1a2b" }, "name": { "type": "string", "example": "Support bot, read only" }, "mounts": { "type": "array", "description": "Path prefixes this latch serves, each with its own upstream and filters.", "items": { "type": "object" } }, "chainDepth": { "type": "integer", "description": "How many parent latches this one inherits from." } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } } }, "/proxy/.well-known/latch-self/whoami": { "get": { "tags": [ "Discovery" ], "operationId": "selfWhoami", "summary": "Who am I, and what do I front?", "description": "The calling latch's own id and its mount table: each mount's name and, for proxy mounts, its upstream. The first call an agent should make.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } } ], "responses": { "200": { "description": "Who am I, and what do I front?", "content": { "application/json": { "schema": { "type": "object", "properties": { "latchId": { "type": "string", "example": "lnk_9f3c1a2b" }, "mounts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "upstream": { "type": "string", "description": "Absent on non-proxy mounts." } } } } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } } }, "/proxy/.well-known/latch-self/capabilities": { "get": { "tags": [ "Discovery" ], "operationId": "selfCapabilities", "summary": "What am I allowed to do?", "description": "The latch's effective capabilities, including filters inherited from a parent. Same body as `/proxy/.well-known/latch-capabilities`, which is kept for backward compatibility.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } } ], "responses": { "200": { "description": "What am I allowed to do?", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } } }, "/proxy/.well-known/latch-self/budget": { "get": { "tags": [ "Discovery" ], "operationId": "selfBudget", "summary": "How much of my daily spend is left?", "description": "The latch's spend cap and its live daily spend. Returns `{ \"message\": \"No cost budget configured\" }` when the latch has no `spend_limit` filter and no legacy cost budget.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } } ], "responses": { "200": { "description": "How much of my daily spend is left?", "content": { "application/json": { "schema": { "type": "object", "properties": { "maxDailyCents": { "type": "integer" }, "currentDailySpendCents": { "type": "integer", "description": "Live, including today's usage." }, "remaining": { "type": "integer", "description": "maxDailyCents minus current spend, floored at 0." }, "message": { "type": "string", "description": "Present only when no budget is configured." } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } } }, "/proxy/.well-known/latch-self/metering": { "get": { "tags": [ "Discovery" ], "operationId": "selfMetering", "summary": "Per-mount request metrics for this latch", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } } ], "responses": { "200": { "description": "Per-mount request metrics for this latch", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } } }, "/proxy/.well-known/latch-self/audit": { "get": { "tags": [ "Discovery" ], "operationId": "selfAudit", "summary": "My own recent requests", "description": "The latch's last 20 audit entries: what it asked for, and what was decided.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } } ], "responses": { "200": { "description": "My own recent requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } } }, "/proxy/.well-known/latch-self/sla": { "get": { "tags": [ "Discovery" ], "operationId": "selfSla", "summary": "My bilateral agreement, and whether the policy satisfies it", "description": "Returns `{ \"status\": \"none\" }` when the latch carries no SLA. Otherwise the SLA terms and the validation result against the effective pipeline.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } } ], "responses": { "200": { "description": "My bilateral agreement, and whether the policy satisfies it", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "\"none\" when no SLA is configured." }, "sla": { "type": "object" }, "validation": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } } }, "/proxy/.well-known/latch-self/authorize": { "post": { "tags": [ "Discovery" ], "operationId": "authorize", "summary": "Ask for a policy decision without executing the request", "description": "Runs the pipeline against a hypothetical request and returns the decision, without calling the\nupstream and without using the credential. Use it to check a request before committing to it, or\nto drive UI that only offers actions the latch actually permits.\n\nThe method and path are canonicalized exactly as `/proxy` canonicalizes them, so a decision here\nmatches what `/proxy` would do. (They diverged once; that was an auth bypass, and it is now a\nshared code path.)", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "`Bearer lat_...`", "schema": { "type": "string", "pattern": "^Bearer lat_" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "method", "path" ], "properties": { "method": { "type": "string", "example": "POST" }, "path": { "type": "string", "example": "/v1/chat/completions" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "description": "The body the real request would carry." } } } } } }, "responses": { "200": { "description": "The decision. Note this is 200 even when the decision is `deny`: the endpoint answers the question successfully. A denial only becomes a 403 when you actually call `/proxy`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "allow", "deny" ] }, "requestId": { "type": "string" }, "latchId": { "type": "string" }, "deniedBy": { "type": "string", "description": "Filter that denied, when `decision` is deny." }, "deniedReason": { "type": "string" }, "filterResults": { "type": "array", "description": "Per-filter trace, in pipeline order.", "items": { "type": "object" } }, "receipt": { "type": "string", "description": "Short-lived signed receipt, issued only when the decision is allow." } } } } } }, "401": { "description": "Missing or invalid access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } }, "403": { "description": "The latch itself is disabled or expired (as opposed to the request being denied).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable failure reason." }, "requestId": { "type": "string", "description": "Correlates with the Activity log and the `x-latch-request-id` response header.", "example": "req_4a1f2c" } } } } } } } } } } }