The state of a held MCP tool call

GET /api/v1/mcp/decisions/{decisionId} · operationId getMcpDecision

For developers: your server sends this request with a server key; it is not a button in the dashboard. To see the same information without code, open Control › Approvals › Waiting in the dashboard.

Poll this while a call is held (decision review). review.status is pending while waiting, then approved (the next decide with approvedDecisionId is allowed once, within 15 minutes; redeemed turns true when it is used) or rejected. decision stays the original answer (review); approval shows in review, not in decision. An unknown, expired or other Site’s decisionId is 404.

#Authentication

Send Authorization: Bearer YOUR_SERVER_KEY (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

#Parameters

• decisionId (path, string, required)

#Responses

• 200: Success · body ChannelDecisionState
• 400: bad_request: the request is invalid; message says what to fix and field names the request field · body Error
• 401: unauthorized (missing or invalid server key, missing Bearer scheme) · body Error
• 403: forbidden: the call came from a browser page or another Site; call from your server with this Site’s server key · body Error
• 404: not_found: nothing with this ID on this Site (or it is past retention), or an unknown path · body Error
• 429: rate_limited: wait for Retry-After · body Error · headers Retry-After
• 500: internal_error: fail the protected action; do not retry automatically · body Error
• 503: service_unavailable: temporarily unavailable; only verify retries · body Error

#Success body fields

• decisionId (string, required)
• actionId (string, required): The tool name (MCP) or METHOD /route (API) the decision is for.
• decision ("allow" | "review" | "deny", required): The answer decide gave; a hold is review.
• review (object | null, required): null when the decision was not a hold.
• review.status ("pending" | "approved" | "rejected" | "cancelled", required): pending while waiting for the dashboard or your step-up; approved or rejected once settled.
• review.expiresAt (integer | null, required): Unix epoch ms: the hold, or an approval, lapses after this.
• review.redeemed (boolean, required): true once an approval was used by a decide call with approvedDecisionId.

Failures are not verdicts. Error bodies follow the Error schema: code is one of bad_request, unauthorized, session_reinit_required, forbidden, not_found, conflict, identity_required, payload_too_large, rate_limited, internal_error, service_unavailable, request_failed, approval_invalid, approval_used, approval_expired, approval_mismatch, step_up_not_held, step_up_mismatch, step_up_settled, step_up_expired, step_up_superseded, agent_tokens_disabled, tool_not_approved, tool_not_read_only. Errors and retries explains each code and what to do.

#Example

curl -sS -X GET 'https://app.trytelltale.dev/api/v1/mcp/decisions/decision_PASTE_DECISION_ID' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY"

const response = await fetch("https://app.trytelltale.dev/api/v1/mcp/decisions/decision_PASTE_DECISION_ID", {
  method: "GET",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY
  },
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();

Machine-readable contract: openapi.json. Request builder: the API explorer shows every operation as curl; it sends requests only on a local dashboard.