openapi: 3.2.0 info: title: 'GTM API public contract: gtm.service.id Support Requests API' description: 'Identity, access and money: users, teams and members, API keys, OAuth clients and authorizations, billing products, subscriptions, transactions and payment methods, notifications, TLS certificates and support requests.' version: '1.0' contact: name: GTM API url: https://gtm-api.com email: support@gtm-api.com license: name: Proprietary url: https://gtm-api.com/license servers: - url: https://app.gtm-api.com/id/v4 description: Production, through the app.gtm-api.com gateway security: - BearerJwt: [] TeamSid: [] tags: - name: support_requests description: Registry package `mcp.id/support_requests`, served on MCP mount `id.platform`. paths: /api/support-requests: post: operationId: escalate_to_human summary: Escalate to a human description: 'Hand the current issue to the human support team. Records a durable support request and opens a ticket in the support inbox; the team replies to the user''s account email. Use when the user explicitly asks for a human, or when you are confident you cannot resolve the issue (missing capability, repeated failed attempts), and only AFTER giving your best available answer. The response item''s status says what happened: handed_off (in the support inbox), received (recorded; delivery pending configuration), handoff_failed (recorded; delivery will be re-driven by ops; do not tell the user it failed, the record exists either way). Compose `body` so the team can act WITHOUT the chat transcript: the user''s ask in their own words, the concrete entities involved (sids/names), and what was already checked or tried. Retry-safe: the same subject from the same copilot session within 15 minutes returns the existing request (already_exists:true). Contract: - MCP tool `escalate_to_human`, registry package `mcp.id/support_requests`, mount `id.platform`. - Operation `create`, response envelope `create`. - Flags: none.' tags: - support_requests requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EscalateToHumanRequest' responses: '200': description: '`create` success envelope.' content: application/json: schema: $ref: '#/components/schemas/EscalateToHumanResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: escalate_to_human x-gtm-mcp-mount: id.platform x-gtm-entity: support_requests x-gtm-operation: create x-gtm-envelope: create x-gtm-availability: ga x-gtm-dangerous: false x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/support-requests/search: post: operationId: search_support_requests summary: Search support requests description: 'List the team''s support escalations with filtering, sorting and cursor pagination: the ops view ("what escalations are open?", "did this session already escalate?"). Returns a counts block of predicate tallies (by status / reason). Bodies are omitted from list rows; call get_support_request for the full text. No full-text search. Contract: - MCP tool `search_support_requests`, registry package `mcp.id/support_requests`, mount `id.platform`. - Operation `search`, response envelope `search`. - Flags: read only.' tags: - support_requests requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/SearchSupportRequestsRequest' responses: '200': description: '`search` success envelope.' content: application/json: schema: $ref: '#/components/schemas/SearchSupportRequestsResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: search_support_requests x-gtm-mcp-mount: id.platform x-gtm-entity: support_requests x-gtm-operation: search x-gtm-envelope: search x-gtm-availability: ga x-gtm-dangerous: false x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: typical /api/support-requests/{sid}: get: operationId: get_support_request summary: Get support request description: 'Fetch a single support escalation by sid: the full body the team received, handoff state (intercom_ticket_id, handed_off_at) and the redacted delivery error if the handoff failed. Contract: - MCP tool `get_support_request`, registry package `mcp.id/support_requests`, mount `id.platform`. - Operation `get`, response envelope `get`. - Flags: read only.' tags: - support_requests parameters: - name: sid in: path required: true description: Path segment `{sid}`. schema: type: string minLength: 18 maxLength: 18 pattern: ^id_sr_ - name: include[] in: query required: false description: Query parameter `include`. style: form explode: true schema: type: array items: type: string responses: '200': description: '`get` success envelope.' content: application/json: schema: $ref: '#/components/schemas/GetSupportRequestResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' x-gtm-mcp-tool: get_support_request x-gtm-mcp-mount: id.platform x-gtm-entity: support_requests x-gtm-operation: get x-gtm-envelope: get x-gtm-availability: ga x-gtm-dangerous: false x-gtm-mass-action: false x-gtm-step-eligible: false x-gtm-schedule-required: false x-gtm-tool-class: trivial components: schemas: McpError: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string enum: - validation_failed - nothing_to_update - not_found - relation_not_found - invalid_transition - limit_exceeded - payment_required - duplicate_rejected - conflict - delete_blocked - unauthorized - forbidden - rate_limited - internal_error - service_unavailable - not_implemented message: type: string recoverable: type: boolean suggestion: type: string field_errors: type: object additionalProperties: type: array items: type: object properties: rule: type: string message: type: string required: - rule - message blockers: type: array items: type: object properties: type: type: string description: Machine-readable blocker type (active_flow, pending_tasks, …). severity: type: string enum: - hard - soft description: hard = external action required; soft = acknowledge is enough. description: type: string entity_sid: type: - string - 'null' count: type: integer resolution: type: string description: 'Hard: tool name to call. Soft: code for acknowledge[].' resolution_hint: type: string required: - type - severity - description - entity_sid - resolution - resolution_hint context: type: object additionalProperties: {} required: - code - message - recoverable meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - error EscalateToHumanResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - create item: type: object properties: sid: type: string team_sid: type: string user_sid: type: string contact_email: type: string source: type: string enum: - copilot - app reason: type: string enum: - user_requested - copilot_unable - other subject: type: string body: type: string copilot_session_sid: type: - string - 'null' status: type: string enum: - received - handed_off - handoff_failed intercom_ticket_id: type: - string - 'null' handed_off_at: type: - string - 'null' last_error: type: - string - 'null' created_by: type: object properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string required: - sid - team_sid - user_sid - contact_email - source - reason - subject - copilot_session_sid - status - intercom_ticket_id - handed_off_at - last_error - created_by - created_at - updated_at already_exists: type: boolean meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - item - already_exists - meta GetSupportRequestResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - get item: type: object properties: sid: type: string team_sid: type: string user_sid: type: string contact_email: type: string source: type: string enum: - copilot - app reason: type: string enum: - user_requested - copilot_unable - other subject: type: string body: type: string copilot_session_sid: type: - string - 'null' status: type: string enum: - received - handed_off - handoff_failed intercom_ticket_id: type: - string - 'null' handed_off_at: type: - string - 'null' last_error: type: - string - 'null' created_by: type: object properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string required: - sid - team_sid - user_sid - contact_email - source - reason - subject - copilot_session_sid - status - intercom_ticket_id - handed_off_at - last_error - created_by - created_at - updated_at included: type: object additionalProperties: {} includes: type: array items: type: string meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - item - included - includes - meta EscalateToHumanRequest: type: object description: Request body of `escalate_to_human`. properties: subject: type: string minLength: 3 maxLength: 255 description: One-line issue title, in the user's language. body: type: string minLength: 10 maxLength: 16000 description: 'The escalation the team will read: user''s ask in their words + entities involved + what was tried. User''s language for their words; English for the context block.' reason: type: string enum: - user_requested - copilot_unable - other description: Default user_requested. Use copilot_unable when escalating on your own judgment. copilot_session_sid: type: string minLength: 18 maxLength: 18 pattern: ^cp_ss_ description: The current copilot session sid; pass it when escalating from a session (enables retry-dedup). required: - subject - body SearchSupportRequestsRequest: type: object description: Request body of `search_support_requests`. properties: filter: type: object properties: sid: type: object properties: eq: type: string in: type: array items: type: string additionalProperties: false team_sid: type: object properties: eq: type: string in: type: array items: type: string additionalProperties: false description: Scoped by JWT; explicit override only for internal-support. user_sid: type: object properties: eq: type: string in: type: array items: type: string additionalProperties: false description: 'The requester: "what did Jane escalate?".' source: type: object properties: eq: type: string enum: - copilot - app in: type: array items: type: string enum: - copilot - app additionalProperties: false reason: type: object properties: eq: type: string enum: - user_requested - copilot_unable - other in: type: array items: type: string enum: - user_requested - copilot_unable - other additionalProperties: false status: type: object properties: eq: type: string enum: - received - handed_off - handoff_failed in: type: array items: type: string enum: - received - handed_off - handoff_failed additionalProperties: false description: received / handoff_failed = not yet in the support inbox. copilot_session_sid: type: object properties: eq: type: string in: type: array items: type: string is_null: type: boolean additionalProperties: false description: The copilot session an escalation came from. created_at: type: object properties: eq: type: string gte: type: string lte: type: string gt: type: string lt: type: string additionalProperties: false handed_off_at: type: object properties: eq: type: string gte: type: string lte: type: string gt: type: string lt: type: string is_null: type: boolean additionalProperties: false sort: type: object properties: field: type: string enum: - created_at - handed_off_at - status direction: type: string enum: - asc - desc description: Default desc. required: - field page_size: type: integer minimum: 0 maximum: 500 description: 0..500, default 50. page_size=0 = count-only, page_size=1 = getFirst. cursor: type: - string - 'null' description: Opaque forward cursor from a previous response pagination.next_cursor. SearchSupportRequestsResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - search items: type: array items: type: object properties: item: type: object properties: sid: type: string team_sid: type: string user_sid: type: string contact_email: type: string source: type: string enum: - copilot - app reason: type: string enum: - user_requested - copilot_unable - other subject: type: string body: type: string copilot_session_sid: type: - string - 'null' status: type: string enum: - received - handed_off - handoff_failed intercom_ticket_id: type: - string - 'null' handed_off_at: type: - string - 'null' last_error: type: - string - 'null' created_by: type: object properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string team_sid: type: string permissions: type: object additionalProperties: {} reason: type: - string - 'null' required: - actor_type - actor_sid - team_sid - permissions - reason created_at: type: string updated_at: type: string required: - sid - team_sid - user_sid - contact_email - source - reason - subject - copilot_session_sid - status - intercom_ticket_id - handed_off_at - last_error - created_by - created_at - updated_at included: type: object additionalProperties: {} required: - item - included pagination: type: object properties: next_cursor: type: - string - 'null' has_more: type: boolean total_count: type: - integer - 'null' required: - next_cursor - has_more - total_count applied_filters: type: object additionalProperties: {} includes: type: array items: type: string meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: - string - 'null' description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: - string - 'null' description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms counts: type: object properties: {} required: - success - operation - items - pagination - applied_filters - includes - meta responses: McpServerError: description: MCP error envelope with `error.code` internal_error or service_unavailable. content: application/json: schema: $ref: '#/components/schemas/McpError' McpClientError: description: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented. content: application/json: schema: $ref: '#/components/schemas/McpError' securitySchemes: BearerJwt: type: http scheme: bearer bearerFormat: JWT description: Access token issued by gtm.service.id. Its `access_identity` claim carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is authoritative. TeamSid: type: apiKey in: header name: Team-SID description: Team scope for tokens that do not carry one. Ignored when the token already names a team.