{ "openapi": "3.0.3", "info": { "title": "Wrangle API Documentation", "description": "A modern ticketing and workflow system built into Slack.", "version": "0.1.5" }, "servers": [ { "url": "https://slack.wrangle.io/api/v1" } ], "paths": { "/inboxes": { "parameters": [ { "name": "slackUserId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "slackWorkspaceId", "in": "query", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get Inboxes", "operationId": "getInboxes", "responses": { "200": { "description": "Get Inboxes Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_GetInboxes" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxes/{inboxId}": { "parameters": [ { "name": "slackUserId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "slackWorkspaceId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get Inbox", "operationId": "getInbox", "description": "Get an inbox by id.", "responses": { "200": { "description": "Get Inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_GetInbox" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Update Inbox", "operationId": "updateInbox", "description": "Update an inbox.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request_UpdateInbox" } } }, "required": true }, "responses": { "200": { "description": "Update Inbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_PutInbox" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inboxes/{inboxId}/tickets": { "parameters": [ { "name": "slackUserId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "slackWorkspaceId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "inboxId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "get": { "summary": "Get Tickets", "operationId": "getTickets", "description": "Get tickets for an inbox. Query parameters are documented as an object in the Request_GetTickets schema.", "responses": { "200": { "description": "Get Tickets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_GetTickets" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tickets": { "parameters": [ { "name": "slackUserId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "slackWorkspaceId", "in": "query", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Create Ticket", "operationId": "createTicket", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request_CreateTicket" } } }, "required": true }, "responses": { "200": { "description": "Create Ticket Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_CreateTicket" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tickets/{ticketId}": { "parameters": [ { "name": "slackUserId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "slackWorkspaceId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get Ticket", "operationId": "getTicket", "responses": { "200": { "description": "Get Ticket Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_GetTicket" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "includeReplies", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When 'true', include the ticket's replies in the response." } ] }, "put": { "summary": "Update Ticket", "operationId": "updateTicket", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request_UpdateTicket" } } }, "required": true }, "responses": { "200": { "description": "Update Ticket Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_UpdateTicket" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete Ticket", "operationId": "deleteTicket", "responses": { "200": { "description": "Delete Ticket Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "string", "enum": [ "true" ] } } } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows": { "parameters": [ { "name": "slackUserId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "slackWorkspaceId", "in": "query", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get Workflows", "operationId": "getWorkflows", "description": "Get active workflows for a workspace.", "responses": { "200": { "description": "Get Workflows Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_GetWorkflows" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflowId}": { "parameters": [ { "name": "slackUserId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "slackWorkspaceId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get Workflow", "operationId": "getWorkflow", "responses": { "200": { "description": "Get Workflow Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_GetWorkflow" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/workflows/{workflowId}/instances": { "parameters": [ { "name": "slackUserId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "slackWorkspaceId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Start Workflow", "operationId": "startWorkflow", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request_StartWorkflow" } } }, "required": true }, "responses": { "200": { "description": "Start a Workflow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_StartWorkflow" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tickets/{ticketId}/reply": { "parameters": [ { "name": "slackUserId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "slackWorkspaceId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "ticketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Create Reply", "operationId": "createReply", "description": "Create a reply on a ticket. Anyone who can view the ticket may reply as themselves; attributing the reply to another user (via slackUserId or email) requires admin access, and posting a private reply requires agent or admin access.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request_CreateReply" } } }, "required": true }, "responses": { "200": { "description": "Create Reply Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response_CreateReply" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "externalDocs": { "description": "Find out more about Wranglesoft", "url": "https://wrangle.io" }, "components": { "schemas": { "Response_CreateTicket": { "type": "object", "required": [ "success", "ticket" ], "properties": { "success": { "type": "string", "enum": [ "true" ] }, "ticket": { "$ref": "#/components/schemas/Ticket" } } }, "Response_UpdateTicket": { "type": "object", "required": [ "success", "ticket" ], "properties": { "success": { "type": "string", "enum": [ "true" ] }, "ticket": { "$ref": "#/components/schemas/Ticket" } } }, "Request_CreateTicket": { "type": "object", "required": [ "name", "inboxId", "requesterId" ], "properties": { "description": { "type": "string" }, "formFieldValues": { "type": "array", "items": { "$ref": "#/components/schemas/TicketFormFieldValues" } }, "inboxId": { "type": "string" }, "name": { "type": "string", "description": "The name of the ticket." }, "requesterId": { "type": "string", "description": "The Slack user ID of the ticket requester. Can be different than the creatorId, for example when an agent creates a ticket on behalf of another user." }, "priority": { "type": "string", "enum": [ "CRITICAL", "HIGH", "NORMAL", "LOW" ] }, "tags": { "type": "array", "items": { "type": "string" } } } }, "Request_UpdateTicket": { "type": "object", "properties": { "assigneeId": { "type": "string", "nullable": true, "description": "The Slack user ID of the ticket assignee. They must be an agent for this ticket's inbox. To unassign a ticket, set this to null. If a ticket is assigned, it's status will automatically be set to IN_PROGRESS. If a ticket is unassigned, it's status will automatically be set to NEW." }, "csatScore": { "type": "string", "description": "The customer satisfaction score for the ticket. Must be a value between 1 and 5. Satisfaction surveys must be enabled for the ticket's inbox.", "enum": [ "1", "2", "3", "4", "5" ] }, "description": { "type": "string" }, "followers": { "type": "array", "items": { "$ref": "#/components/schemas/Followers" } }, "formFieldValues": { "type": "array", "items": { "$ref": "#/components/schemas/TicketFormFieldValues" } }, "inboxId": { "type": "string", "description": "Move this ticket to a new inbox. Will clear the assignee, status, tags, and other inbox-specific settings." }, "name": { "type": "string" }, "priority": { "type": "string", "enum": [ "CRITICAL", "HIGH", "NORMAL", "LOW" ] }, "status": { "type": "string", "enum": [ "CLOSED", "IN_PROGRESS", "NEW", "ON_HOLD", "RESOLVED" ] }, "tags": { "type": "array", "items": { "type": "string" } } } }, "Request_UpdateInbox": { "type": "object", "description": "Update an inbox.", "properties": { "userRoles": { "description": "Allows updating the list of users with the No Access, Observer, and Requester roles for this inbox. Admin and Agent user roles need to be managed via the Wrangle web app.", "type": "object", "properties": { "NO_ACCESS": { "description": "Slack user IDs to assign the No Access role for this inbox. This will replace all users with the No Access role that exist already.", "type": "array", "items": { "type": "string" } }, "REQUESTER": { "description": "Slack user IDs to assign the Requester role for this inbox. This will replace all users with the Requester role that exist already.", "type": "array", "items": { "type": "string" } }, "OBSERVER": { "description": "Slack user IDs to assign the Observer role for this inbox. This will replace all users with the Observer role that exist already.", "type": "array", "items": { "type": "string" } } } } } }, "Response_GetInboxes": { "type": "object", "required": [ "success", "inboxes" ], "properties": { "success": { "type": "string", "enum": [ "true" ] }, "inboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Inbox" } } } }, "Response_GetInbox": { "type": "object", "required": [ "success", "inbox" ], "properties": { "success": { "type": "string", "enum": [ "true" ] }, "inbox": { "$ref": "#/components/schemas/Inbox" } } }, "Response_PutInbox": { "type": "object", "required": [ "success", "inbox" ], "properties": { "success": { "type": "string", "enum": [ "true" ] }, "inbox": { "$ref": "#/components/schemas/Inbox" } } }, "Request_GetTickets": { "type": "object", "description": "Query parameters for getting tickets for an inbox.", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number for pagination (1-based)." }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200, "description": "Number of tickets per page." } } }, "Response_GetTickets": { "type": "object", "required": [ "success", "tickets", "pagination" ], "properties": { "success": { "type": "string", "enum": [ "true" ] }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/LimitedTicket" } }, "pagination": { "type": "object", "required": [ "page", "pageSize", "totalCount", "totalPages" ], "properties": { "page": { "type": "integer", "description": "Current page number" }, "pageSize": { "type": "integer", "description": "Number of items per page" }, "totalCount": { "type": "integer", "description": "Total number of items available" }, "totalPages": { "type": "integer", "description": "Total number of pages" } } } } }, "Response_GetWorkflows": { "type": "object", "required": [ "success", "workflows" ], "properties": { "success": { "type": "string", "enum": [ "true" ] }, "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/LimitedWorkflow" } } } }, "Response_GetWorkflow": { "type": "object", "required": [ "success", "ticket" ], "properties": { "success": { "type": "string", "enum": [ "true" ] }, "workflow": { "$ref": "#/components/schemas/Workflow" } } }, "Request_StartWorkflow": { "type": "object", "required": [ "requesterId", "formFieldValues" ], "properties": { "requesterId": { "type": "string", "description": "The Slack user ID of the user starting this workflow instance." }, "formFieldValues": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowFormFieldValues" } } } }, "Response_StartWorkflow": { "type": "object", "required": [ "success", "workflowInstanceId" ], "properties": { "success": { "type": "string", "enum": [ "true" ] }, "workflowInstanceId": { "type": "string", "format": "uuid" } } }, "Inbox": { "type": "object", "properties": { "createdAt": { "type": "string" }, "creatorId": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "formFields": { "$ref": "#/components/schemas/FormFields" }, "name": { "type": "string" }, "description": { "type": "string" }, "defaultUserRole": { "type": "string", "enum": [ "REQUESTER", "NO_ACCESS", "OBSERVER" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "userRoles": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "NO_ACCESS", "REQUESTER", "OBSERVER", "AGENT", "ADMIN" ] }, "userId": { "type": "string" } } } }, "updatedAt": { "type": "string" } } }, "Ticket": { "allOf": [ { "$ref": "#/components/schemas/Request_CreateTicket" }, { "type": "object", "required": [ "id", "status" ], "properties": { "assigneeId": { "type": "string", "nullable": true, "description": "The Slack user ID of the ticket assignee. They must be an agent for this ticket's inbox." }, "createdAt": { "type": "string" }, "creatorId": { "type": "string" }, "csatScore": { "type": "string", "description": "The customer satisfaction score for the ticket if one exists.", "enum": [ "1", "2", "3", "4", "5" ] }, "csatReason": { "type": "string", "description": "The reason for the customer satisfaction score if one exists." }, "description": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "requesterId": { "type": "string" }, "slackMessageChannel": { "type": "string" }, "slackMessageTs": { "type": "string" }, "slackOriginalMessage": { "type": "object", "description": "If the ticket was created from a Slack message, this will contain the original message details.", "nullable": true, "properties": { "channel": { "type": "string" }, "ts": { "type": "string" }, "parentMessageTs": { "type": "string", "nullable": true }, "permalinkUrl": { "type": "string", "description": "Link to the original message that created the ticket in Slack." } } }, "slackParentMessageTs": { "type": "string" }, "slackPermalinkUrl": { "type": "string", "description": "Link to the ticket in Slack." }, "status": { "type": "string", "enum": [ "CLOSED", "IN_PROGRESS", "NEW", "ON_HOLD", "RESOLVED" ] }, "workspaceId": { "type": "string" }, "workspaceTicketNumber": { "type": "number" } } } ] }, "LimitedTicket": { "type": "object", "required": [ "id", "name", "status" ], "properties": { "assigneeId": { "type": "string", "nullable": true, "description": "The Slack user ID of the ticket assignee. They must be an agent for this ticket's inbox." }, "createdAt": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "requesterId": { "type": "string" }, "status": { "type": "string", "enum": [ "CLOSED", "IN_PROGRESS", "NEW", "ON_HOLD", "RESOLVED" ] }, "updatedAt": { "type": "string" } } }, "Workflow": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "intakeFormFields": { "$ref": "#/components/schemas/FormFields" } } }, "LimitedWorkflow": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "Followers": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "string" } } }, "TicketFormFieldValues": { "type": "object", "required": [ "fieldId" ], "properties": { "fieldId": { "type": "string" }, "value": { "oneOf": [ { "type": "string", "description": "For date form fields, use the YYYY-MM-DD format." }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "WorkflowFormFieldValues": { "type": "object", "required": [ "fieldId" ], "properties": { "fieldId": { "type": "string" }, "value": { "oneOf": [ { "type": "string", "description": "For date form fields, use the YYYY-MM-DD format." }, { "type": "number" }, { "type": "array", "description": "For multiple list or user inputs, use an array of strings.", "items": { "type": "string" } } ] } } }, "FormFields": { "type": "object", "required": [ "fieldId", "fieldLabel", "isRequired", "fieldType" ], "properties": { "fieldId": { "type": "string" }, "fieldLabel": { "type": "string" }, "isRequired": { "type": "boolean" }, "fieldType": { "type": "string", "enum": [ "Date Picker", "File Input", "List Input", "Multiline", "Multiple List Inputs", "Multiple Slack Users", "Number", "Plain Text Input", "Slack Channel", "Slack User" ] }, "fieldOptions": { "type": "array", "description": "For List Inputs, these are the options available to the user.", "items": { "type": "string" } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "formFieldErrors": { "type": "array", "items": { "$ref": "#/components/schemas/FormFieldError" } } } }, "FormFieldError": { "type": "object", "required": [ "fieldId", "error" ], "properties": { "fieldId": { "type": "string" }, "message": { "type": "string" }, "fieldName": { "type": "string" }, "type": { "type": "string" } } }, "Reply": { "type": "object", "required": [ "authorSlackUserId", "authorSlackWorkspaceId", "channelId", "isPrivate", "markdownText", "slackTs" ], "properties": { "authorSlackUserId": { "type": "string", "description": "The Slack user ID the reply is attributed to." }, "authorSlackWorkspaceId": { "type": "string", "description": "The Slack workspace ID of the reply author." }, "channelId": { "type": "string", "description": "The Slack channel ID the reply was posted to." }, "createdAt": { "type": "string" }, "isPrivate": { "type": "boolean", "description": "Whether the reply is private (visible only to agents/observers)." }, "markdownText": { "type": "string" }, "slackParentTs": { "type": "string", "nullable": true, "description": "The Slack timestamp of the thread parent, if this is a threaded reply." }, "slackTs": { "type": "string", "description": "The Slack message timestamp of the reply." }, "updatedAt": { "type": "string" } } }, "Request_CreateReply": { "type": "object", "required": [ "markdownText" ], "properties": { "markdownText": { "type": "string", "description": "The reply body in Slack formatted markdown. Required." }, "authorSlackUserId": { "type": "string", "description": "The Slack user ID to attribute the reply to. You must provide either an authorSlackUserId or an authorEmail, not both." }, "authorEmail": { "type": "string", "format": "email", "description": "The email address of the user to attribute the reply to. This user must exist in your Slack workspace. You must provide either an authorSlackUserId or an authorEmail, not both." }, "isPrivate": { "type": "boolean", "description": "Post the reply as private (visible only to agents/observers). Requires agent or admin access." } } }, "Response_CreateReply": { "type": "object", "required": [ "success", "reply" ], "properties": { "success": { "type": "boolean" }, "reply": { "$ref": "#/components/schemas/Reply" } } }, "Response_GetTicket": { "allOf": [ { "$ref": "#/components/schemas/Ticket" }, { "type": "object", "properties": { "replies": { "type": "array", "description": "Present only when includeReplies=true.", "items": { "$ref": "#/components/schemas/Reply" } } } } ] } }, "parameters": { "Page": { "name": "page", "in": "query", "description": "Page number for pagination (1-based). Defaults to 1.", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PageSize": { "name": "pageSize", "in": "query", "description": "Number of tickets per page. Maximum 200. Defaults to 200.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200 } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "bearerAuth": [] } ] }