{"openapi":"3.1.0","info":{"title":"Agentic Commerce Testbench — Capability API (Layer 1)","version":"0.1.0","description":"Canonical capability contract. Every agent-facing capability is an operation here; MCP tools (L2) and protocol adapters (L3) are derived from this document. Agent policy is declared per operation via x-agent-trust / x-agent-confirm / x-agent-allowed and may be overridden by the active policy profile (values below are the `balanced` profile). All data is synthetic.\n"},"servers":[{"url":"https://{host}","variables":{"host":{"default":"testbench.up.railway.app"}}}],"tags":[{"name":"catalog"},{"name":"service-status"},{"name":"account"},{"name":"billing"},{"name":"scheduling"},{"name":"retention"},{"name":"orders"},{"name":"support"},{"name":"operator"}],"components":{"securitySchemes":{"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/oauth/authorize","tokenUrl":"/oauth/token","scopes":{"account.read":"Read account (READ)","account.write":"Act on account (WRITE)"}}}},"agentKey":{"type":"apiKey","in":"header","name":"X-Agent-Key"},"adminKey":{"type":"apiKey","in":"header","name":"X-Admin-Key"},"deskCookie":{"type":"apiKey","in":"cookie","name":"tb_desk","description":"The desk sign-in cookie, issued by POST /admin/desk/sign-in (HttpOnly, SameSite=Strict, Path=/admin/desk, Max-Age=3600, Secure over HTTPS), with the same rules as the observer sign-in."}},"parameters":{"ConfirmationToken":{"name":"Confirmation-Token","in":"header","required":false,"schema":{"type":"string"}},"AgentDisclosure":{"name":"X-Agent-Disclosure","in":"header","required":false,"description":"Agent self-identification, e.g. \"ai-agent; principal=customer\". Required when the profile demands disclosure.","schema":{"type":"string"}}},"schemas":{"Problem":{"type":"object","description":"RFC 7807 problem details","required":["type","title","status"],"properties":{"type":{"type":"string","enum":["needs-auth","forbidden-for-agents","disclosure-required","needs-confirmation","invalid-request","not-found","ticket-closed","ticket-full","too-many-open-tickets"]},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"required_scope":{"type":"string","enum":["GUEST","READ","WRITE"]},"confirmation_token":{"type":"string"},"confirmation_url":{"type":"string","description":"Relative URL where the customer approves the pending action"},"preview":{"type":"object","description":"What will happen if confirmed (e.g. monthly_delta, retention_offer)"}},"example":{"type":"needs-confirmation","title":"Customer must confirm cancel_service","status":428,"confirmation_token":"9f2c1a7e","preview":{"retention_offer":{"offer_id":"ret-1g-12","monthly":60.0}}}},"Plan":{"type":"object","required":["plan_id","name","monthly","category"],"properties":{"plan_id":{"type":"string","example":"internet-1g"},"name":{"type":"string","example":"Gigabit Internet"},"monthly":{"type":"number","example":80.0},"category":{"type":"string","enum":["internet","mobile","tv"]}}},"Outage":{"type":"object","required":["zip","outage"],"properties":{"zip":{"type":"string","example":"80202"},"outage":{"type":"boolean"},"detail":{"type":["string","null"]}}},"Account":{"type":"object","properties":{"customer_id":{"type":"string","example":"C100"},"status":{"type":"string","enum":["active","cancelled"]},"services":{"type":"array","items":{"type":"string"},"example":["internet-1g","tv-popular"]},"appointments":{"type":"array","items":{"type":"string"}}}},"Bill":{"type":"object","properties":{"balance":{"type":"number","example":150.0},"monthly_total":{"type":"number","example":150.0},"lines":{"type":"array","items":{"type":"object","properties":{"plan_id":{"type":"string"},"amount":{"type":"number"}}}}}},"RetentionOffer":{"type":["object","null"],"properties":{"offer_id":{"type":"string","example":"ret-1g-12"},"replaces":{"type":"string"},"monthly":{"type":"number"},"term_months":{"type":"integer"}}},"Order":{"type":"object","properties":{"order_id":{"type":"string","example":"O1"},"items":{"type":"array","items":{"type":"string"}},"zip":{"type":"string"},"monthly_total":{"type":"number"},"status":{"type":"string","enum":["pending","confirmed"]}}},"TicketTopic":{"type":"string","enum":["outage","billing","account","other"]},"TicketStatus":{"type":"string","enum":["open","in_progress","answered","closed"]},"Message":{"type":"object","required":["seq","author","text","at"],"properties":{"seq":{"type":"integer","minimum":0},"author":{"type":"string","enum":["customer","desk-bot","human"]},"text":{"type":"string"},"at":{"type":"string","format":"date-time"}}},"Ticket":{"type":"object","required":["ticket_id","customer_id","topic","status","handled_by","created_at","updated_at","messages"],"properties":{"ticket_id":{"type":"string","example":"T7"},"customer_id":{"type":"string","example":"C200-grokbot"},"topic":{"$ref":"#/components/schemas/TicketTopic"},"status":{"$ref":"#/components/schemas/TicketStatus"},"handled_by":{"type":"string","enum":["desk-bot","operator"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"messages":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/Message"}}}},"TicketSummary":{"type":"object","required":["ticket_id","topic","status","handled_by","updated_at","last_author"],"properties":{"ticket_id":{"type":"string"},"topic":{"$ref":"#/components/schemas/TicketTopic"},"status":{"$ref":"#/components/schemas/TicketStatus"},"handled_by":{"type":"string","enum":["desk-bot","operator"]},"updated_at":{"type":"string","format":"date-time"},"last_author":{"type":"string","enum":["customer","desk-bot","human"]}}},"DeskTicket":{"allOf":[{"$ref":"#/components/schemas/TicketSummary"},{"type":"object","required":["customer_id","template_id"],"properties":{"customer_id":{"type":"string"},"template_id":{"type":"string"},"agent_id":{"type":["string","null"]}}}]},"DeskTicketDetail":{"allOf":[{"$ref":"#/components/schemas/DeskTicket"},{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/Message"}}}}]}},"responses":{"Problem":{"description":"Policy or request error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/v1/plans":{"get":{"operationId":"list_plans","tags":["catalog"],"summary":"List available plans","x-agent-trust":"GUEST","x-agent-changes":"none","x-agent-confirm":false,"x-agent-allowed":true,"parameters":[{"name":"category","in":"query","schema":{"type":"string","enum":["internet","mobile","tv"]}}],"responses":{"200":{"description":"Plans","content":{"application/json":{"schema":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}}}}}}}}}},"/v1/outages/{zip}":{"get":{"operationId":"check_outage","tags":["service-status"],"summary":"Outage status for a ZIP code","x-agent-trust":"GUEST","x-agent-changes":"none","x-agent-confirm":false,"x-agent-allowed":true,"parameters":[{"name":"zip","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{5}$"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Outage"}}}},"400":{"$ref":"#/components/responses/Problem"}}}},"/v1/account":{"get":{"operationId":"get_account","tags":["account"],"summary":"Account summary","security":[{"oauth":["account.read"]}],"x-agent-trust":"READ","x-agent-changes":"none","x-agent-confirm":false,"x-agent-allowed":true,"responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"$ref":"#/components/responses/Problem"}}}},"/v1/account/plan-change":{"post":{"operationId":"change_plan","tags":["account"],"summary":"Switch one service to another plan","security":[{"oauth":["account.write"]}],"x-agent-trust":"WRITE","x-agent-changes":"reversible","x-agent-confirm":{"when":"price_increase_over","amount":10.0},"x-agent-allowed":true,"parameters":[{"$ref":"#/components/parameters/ConfirmationToken"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from_plan","to_plan"],"properties":{"from_plan":{"type":"string"},"to_plan":{"type":"string"}}},"example":{"from_plan":"internet-1g","to_plan":"internet-2g"}}}},"responses":{"200":{"description":"Changed","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"string"}},"monthly_delta":{"type":"number"}}}}}},"401":{"$ref":"#/components/responses/Problem"},"428":{"$ref":"#/components/responses/Problem"}}}},"/v1/billing/bill":{"get":{"operationId":"get_bill","tags":["billing"],"summary":"Current bill","security":[{"oauth":["account.read"]}],"x-agent-trust":"READ","x-agent-changes":"none","x-agent-confirm":false,"x-agent-allowed":true,"responses":{"200":{"description":"Bill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}}},"401":{"$ref":"#/components/responses/Problem"}}}},"/v1/billing/payments":{"post":{"operationId":"pay_balance","tags":["billing"],"summary":"Pay toward the balance with the stored payment method","security":[{"oauth":["account.write"]}],"x-agent-trust":"WRITE","x-agent-changes":"irreversible","x-agent-confirm":true,"x-agent-allowed":true,"parameters":[{"$ref":"#/components/parameters/ConfirmationToken"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","exclusiveMinimum":0}}}}}},"responses":{"200":{"description":"Paid","content":{"application/json":{"schema":{"type":"object","properties":{"paid":{"type":"number"},"balance":{"type":"number"}}}}}},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"428":{"$ref":"#/components/responses/Problem"}}}},"/v1/scheduling/slots":{"get":{"operationId":"list_appointment_slots","tags":["scheduling"],"summary":"Available technician slots","security":[{"oauth":["account.read"]}],"x-agent-trust":"READ","x-agent-changes":"none","x-agent-confirm":false,"x-agent-allowed":true,"responses":{"200":{"description":"Slots","content":{"application/json":{"schema":{"type":"object","properties":{"slots":{"type":"array","items":{"type":"string","example":"2026-10-27T08:00"}}}}}}},"401":{"$ref":"#/components/responses/Problem"}}}},"/v1/scheduling/appointments":{"post":{"operationId":"schedule_appointment","tags":["scheduling"],"summary":"Book a technician visit","security":[{"oauth":["account.write"]}],"x-agent-trust":"WRITE","x-agent-changes":"reversible","x-agent-confirm":false,"x-agent-allowed":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slot"],"properties":{"slot":{"type":"string"}}}}}},"responses":{"200":{"description":"Booked","content":{"application/json":{"schema":{"type":"object","properties":{"scheduled":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"}}}},"/v1/retention/offer":{"get":{"operationId":"get_retention_offer","tags":["retention"],"summary":"Save offer available to this customer, if any","security":[{"oauth":["account.read"]}],"x-agent-trust":"READ","x-agent-changes":"none","x-agent-confirm":false,"x-agent-allowed":true,"responses":{"200":{"description":"Offer","content":{"application/json":{"schema":{"type":"object","properties":{"offer":{"$ref":"#/components/schemas/RetentionOffer"}}}}}},"401":{"$ref":"#/components/responses/Problem"}}}},"/v1/retention/offer/accept":{"post":{"operationId":"accept_retention_offer","tags":["retention"],"summary":"Accept a save offer (a fixed-term commitment, so the customer confirms it)","security":[{"oauth":["account.write"]}],"x-agent-trust":"WRITE","x-agent-changes":"reversible","x-agent-confirm":true,"x-agent-allowed":true,"parameters":[{"$ref":"#/components/parameters/ConfirmationToken"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["offer_id"],"properties":{"offer_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"string"},"new_monthly":{"type":"number"},"term_months":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"428":{"$ref":"#/components/responses/Problem"}}}},"/v1/retention/cancellations":{"post":{"operationId":"cancel_service","tags":["retention"],"summary":"Cancel a service (a retention offer is previewed before confirmation when the profile requires it)","security":[{"oauth":["account.write"]}],"x-agent-trust":"WRITE","x-agent-changes":"irreversible","x-agent-confirm":true,"x-agent-allowed":true,"parameters":[{"$ref":"#/components/parameters/ConfirmationToken"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan_id"],"properties":{"plan_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"cancelled":{"type":"string"},"remaining":{"type":"array","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"428":{"$ref":"#/components/responses/Problem"}}}},"/v1/orders":{"post":{"operationId":"create_order","tags":["orders"],"summary":"Start a new-customer order (checkout session)","x-agent-trust":"GUEST","x-agent-changes":"reversible","x-agent-confirm":false,"x-agent-allowed":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items","zip"],"properties":{"items":{"type":"array","minItems":1,"items":{"type":"string"}},"zip":{"type":"string"}}},"example":{"items":["internet-300"],"zip":"19103"}}}},"responses":{"200":{"description":"Pending order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"$ref":"#/components/responses/Problem"}}}},"/v1/orders/{order_id}/complete":{"post":{"operationId":"complete_order","tags":["orders"],"summary":"Complete an order with a delegated payment token (test tokens only)","x-agent-trust":"GUEST","x-agent-changes":"reversible","x-agent-confirm":true,"x-agent-allowed":true,"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/ConfirmationToken"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_token"],"properties":{"payment_token":{"type":"string","example":"tok_test_visa"}}}}}},"responses":{"200":{"description":"Confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"404":{"$ref":"#/components/responses/Problem"},"428":{"$ref":"#/components/responses/Problem"}}}},"/v1/support/tickets":{"post":{"operationId":"open_support_ticket","tags":["support"],"summary":"Open a support ticket (a person or the scripted desk answers it)","security":[{"oauth":["account.read"]}],"x-agent-trust":"READ","x-agent-changes":"reversible","x-agent-confirm":false,"x-agent-allowed":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["topic","message"],"properties":{"topic":{"type":"string","enum":["outage","billing","account","other"]},"message":{"type":"string","minLength":1,"maxLength":2000}}},"example":{"topic":"outage","message":"The posted restore time has passed. Is there an update?"}}}},"responses":{"201":{"description":"Opened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticket"},"example":{"ticket_id":"T1","customer_id":"C200","topic":"outage","status":"open","handled_by":"desk-bot","created_at":"2026-10-22T09:00:00Z","updated_at":"2026-10-22T09:00:00Z","messages":[{"seq":0,"author":"customer","text":"The posted restore time has passed. Is there an update?","at":"2026-10-22T09:00:00Z"}]}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"}}},"get":{"operationId":"list_support_tickets","tags":["support"],"summary":"This customer's support tickets, newest first","security":[{"oauth":["account.read"]}],"x-agent-trust":"READ","x-agent-changes":"none","x-agent-confirm":false,"x-agent-allowed":true,"responses":{"200":{"description":"Tickets","content":{"application/json":{"schema":{"type":"object","required":["tickets"],"properties":{"tickets":{"type":"array","items":{"$ref":"#/components/schemas/TicketSummary"}}}},"example":{"tickets":[{"ticket_id":"T1","topic":"outage","status":"answered","handled_by":"desk-bot","updated_at":"2026-10-22T09:00:00Z","last_author":"desk-bot"}]}}}},"401":{"$ref":"#/components/responses/Problem"}}}},"/v1/support/tickets/{ticket_id}":{"get":{"operationId":"get_support_ticket","tags":["support"],"summary":"One support ticket with its message thread","security":[{"oauth":["account.read"]}],"x-agent-trust":"READ","x-agent-changes":"none","x-agent-confirm":false,"x-agent-allowed":true,"parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string","pattern":"^T[0-9]{1,6}$","example":"T1"}}],"responses":{"200":{"description":"Ticket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticket"},"example":{"ticket_id":"T1","customer_id":"C200","topic":"outage","status":"answered","handled_by":"desk-bot","created_at":"2026-10-22T09:00:00Z","updated_at":"2026-10-22T09:00:00Z","messages":[{"seq":0,"author":"customer","text":"The posted restore time has passed. Is there an update?","at":"2026-10-22T09:00:00Z"},{"seq":1,"author":"desk-bot","text":"We're aware of the fiber cut affecting 80202. The current estimated restore time is 2026-10-23T18:00. We'll update this ticket if it changes.","at":"2026-10-22T09:00:00Z"}]}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"}}}},"/v1/support/tickets/{ticket_id}/messages":{"post":{"operationId":"add_support_message","tags":["support"],"summary":"Add a follow-up message to a support ticket (reopens it)","security":[{"oauth":["account.read"]}],"x-agent-trust":"READ","x-agent-changes":"none","x-agent-confirm":false,"x-agent-allowed":true,"parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string","pattern":"^T[0-9]{1,6}$","example":"T1"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":2000}}},"example":{"message":"Thanks. Will I get a credit for the downtime?"}}}},"responses":{"200":{"description":"Ticket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticket"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"}}}},"/healthz":{"get":{"operationId":"healthz","tags":["operator"],"x-agent-trust":"GUEST","x-agent-changes":"none","x-agent-allowed":false,"x-agent-internal":true,"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"type":"string"},"version":{"type":"string"}}}}}}}}},"/admin/test-agents":{"post":{"operationId":"register_test_agent","tags":["operator"],"security":[{"adminKey":[]}],"x-agent-trust":"GUEST","x-agent-changes":"none","x-agent-allowed":false,"x-agent-internal":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_id"],"properties":{"agent_id":{"type":"string","example":"dots"},"rate_limit_per_min":{"type":"integer","default":60},"personas":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created; returns api_key and synthetic persona credentials","content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string"},"api_key":{"type":"string"},"persona_credentials":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Problem"}}}},"/admin/traces":{"get":{"operationId":"export_traces","tags":["operator"],"security":[{"adminKey":[]}],"x-agent-trust":"GUEST","x-agent-changes":"none","x-agent-allowed":false,"x-agent-internal":true,"parameters":[{"name":"agent_id","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"JSONL traces","content":{"application/x-ndjson":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Problem"}}}},"/admin/desk/tickets":{"get":{"operationId":"desk_list_tickets","tags":["operator"],"summary":"Tickets across all customers and test agents (operator desk)","security":[{"adminKey":[]},{"deskCookie":[]}],"x-agent-trust":"GUEST","x-agent-changes":"none","x-agent-allowed":false,"x-agent-internal":true,"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","in_progress","answered","closed"]}},{"name":"agent_id","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"}}],"responses":{"200":{"description":"Desk tickets","content":{"application/json":{"schema":{"type":"object","required":["tickets"],"properties":{"tickets":{"type":"array","items":{"$ref":"#/components/schemas/DeskTicket"}}}},"example":{"tickets":[{"ticket_id":"T7","customer_id":"C200-grokbot","template_id":"C200","agent_id":"grokbot","topic":"outage","status":"open","handled_by":"desk-bot","updated_at":"2026-10-28T16:30:00Z","last_author":"customer"}]}}}},"401":{"$ref":"#/components/responses/Problem"}}}},"/admin/desk/tickets/{ticket_id}/take":{"post":{"operationId":"desk_take_ticket","tags":["operator"],"summary":"Take a ticket over from the scripted desk (a closed ticket is refused)","security":[{"adminKey":[]},{"deskCookie":[]}],"x-agent-trust":"GUEST","x-agent-changes":"none","x-agent-allowed":false,"x-agent-internal":true,"parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string","pattern":"^T[0-9]{1,6}$"}},{"name":"X-Desk-CSRF","in":"header","required":false,"description":"Required with the cookie (or as the `csrf` form field); not with X-Admin-Key.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"csrf":{"type":"string"}}}}}},"responses":{"200":{"description":"The ticket after the action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeskTicketDetail"}}}},"303":{"description":"Form post redirected back to the ticket view"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"}}}},"/admin/desk/tickets/{ticket_id}/release":{"post":{"operationId":"desk_release_ticket","tags":["operator"],"summary":"Hand a ticket back to the scripted desk (a closed ticket is refused)","security":[{"adminKey":[]},{"deskCookie":[]}],"x-agent-trust":"GUEST","x-agent-changes":"none","x-agent-allowed":false,"x-agent-internal":true,"parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string","pattern":"^T[0-9]{1,6}$"}},{"name":"X-Desk-CSRF","in":"header","required":false,"description":"Required with the cookie (or as the `csrf` form field); not with X-Admin-Key.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"csrf":{"type":"string"}}}}}},"responses":{"200":{"description":"The ticket after the action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeskTicketDetail"}}}},"303":{"description":"Form post redirected back to the ticket view"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"}}}},"/admin/desk/tickets/{ticket_id}/reply":{"post":{"operationId":"desk_reply_ticket","tags":["operator"],"summary":"Reply to a ticket as a human (takes it over if needed)","security":[{"adminKey":[]},{"deskCookie":[]}],"x-agent-trust":"GUEST","x-agent-changes":"none","x-agent-allowed":false,"x-agent-internal":true,"parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string","pattern":"^T[0-9]{1,6}$"}},{"name":"X-Desk-CSRF","in":"header","required":false,"description":"Required with the cookie (or as the `csrf` form field); not with X-Admin-Key.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":2000}}},"example":{"text":"Crews expect to finish splicing by 9 PM tonight. We'll credit two days."}},"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":2000},"csrf":{"type":"string"}}}}}},"responses":{"200":{"description":"The ticket after the action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeskTicketDetail"}}}},"303":{"description":"Form post redirected back to the ticket view"},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"}}}},"/admin/desk/tickets/{ticket_id}/close":{"post":{"operationId":"desk_close_ticket","tags":["operator"],"summary":"Close a ticket","security":[{"adminKey":[]},{"deskCookie":[]}],"x-agent-trust":"GUEST","x-agent-changes":"none","x-agent-allowed":false,"x-agent-internal":true,"parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"string","pattern":"^T[0-9]{1,6}$"}},{"name":"X-Desk-CSRF","in":"header","required":false,"description":"Required with the cookie (or as the `csrf` form field); not with X-Admin-Key.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"csrf":{"type":"string"}}}}}},"responses":{"200":{"description":"The ticket after the action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeskTicketDetail"}}}},"303":{"description":"Form post redirected back to the ticket view"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"}}}},"/admin/test-agents/{agent_id}/reset":{"post":{"operationId":"reset_test_agent","tags":["operator"],"summary":"Reset every customer instance of a test agent to its template's seed","security":[{"adminKey":[]}],"x-agent-trust":"GUEST","x-agent-changes":"irreversible","x-agent-allowed":false,"x-agent-internal":true,"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"}}],"responses":{"200":{"description":"Reset","content":{"application/json":{"schema":{"type":"object","required":["agent_id","reset"],"properties":{"agent_id":{"type":"string"},"reset":{"type":"array","items":{"type":"string"}}}},"example":{"agent_id":"grokbot","reset":["C100-grokbot","C200-grokbot"]}}}},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"}}}}}}