@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Sunshine Conversations API
@base https://{subdomain}.zendesk.com/sc
@version 17.9.0
@auth Bearer bearer | Bearer basic
@endpoints 68
@hint download_for_search
@toc apps(64), tokenInfo(1), oauth(3)

@group apps
@endpoint POST /v2/apps
@required {displayName: any}
@optional {settings: map{conversationRetentionSeconds: int, maskCreditCardNumbers: bool, useAnimalNames: bool, echoPostback: bool, ignoreAutoConversationStart: bool, multiConvoEnabled: bool, appLocalizationEnabled: bool, endSessionEnabled: bool, disableConversationReopen: bool}, metadata: map}
@returns(201) {app: any}
@errors {400, 402}

@endpoint GET /v2/apps
@optional {page: map, filter: map}
@returns(200) {apps: [map], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}}
@errors {400, 403}

@endpoint GET /v2/apps/{appId}
@returns(200) {app: any}
@errors {404}

@endpoint PATCH /v2/apps/{appId}
@optional {displayName: any, settings: map{conversationRetentionSeconds: int, maskCreditCardNumbers: bool, useAnimalNames: bool, echoPostback: bool, ignoreAutoConversationStart: bool, multiConvoEnabled: bool, appLocalizationEnabled: bool, endSessionEnabled: bool, disableConversationReopen: bool}, metadata: map}
@returns(200) {app: any}
@errors {400, 404}

@endpoint DELETE /v2/apps/{appId}
@returns(200)
@errors {404}

@endpoint POST /v2/apps/{appId}/keys
@required {displayName: any}
@returns(201) {key: any}

@endpoint GET /v2/apps/{appId}/keys
@returns(200) {keys: [map]}

@endpoint GET /v2/apps/{appId}/keys/{keyId}
@returns(200) {key: any}
@errors {404}

@endpoint DELETE /v2/apps/{appId}/keys/{keyId}
@returns(200)
@errors {404}

@endpoint POST /v2/apps/{appId}/attachments
@returns(201) {attachment: any}
@errors {400}

@endpoint POST /v2/apps/{appId}/attachments/remove
@required {mediaUrl: str}
@returns(200)
@errors {400, 404}

@endpoint POST /v2/apps/{appId}/conversations
@required {type: str(personal/sdkGroup)}
@optional {participants: [any], displayName: any, description: str, iconUrl: str(uri), metadata: map}
@returns(201) {conversation: any}
@errors {404}

@endpoint GET /v2/apps/{appId}/conversations
@required {filter: map}
@optional {page: map}
@returns(200) {conversations: [any], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}}
@errors {400, 404}

@endpoint GET /v2/apps/{appId}/conversations/{conversationId}
@returns(200) {conversation: any}
@errors {404}

@endpoint PATCH /v2/apps/{appId}/conversations/{conversationId}
@optional {displayName: any, description: str, iconUrl: str(uri), metadata: map}
@returns(200) {conversation: any}
@errors {404}

@endpoint DELETE /v2/apps/{appId}/conversations/{conversationId}
@returns(200)
@errors {400, 404}

@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/join
@returns(201) {participant: map{id: str, userId: str, unreadCount: int, clientAssociations: [map], userExternalId: str?, lastRead: str?}}
@errors {400, 404}

@endpoint GET /v2/apps/{appId}/conversations/{conversationId}/participants
@optional {page: map}
@returns(200) {participants: [map], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}}
@errors {400, 404}

@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/leave
@returns(200)
@errors {404}

@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/messages
@required {author: any, content: any}
@optional {destination: any, metadata: map, override: any, schema: str}
@returns(201) {messages: [map]}
@errors {423}

@endpoint GET /v2/apps/{appId}/conversations/{conversationId}/messages
@optional {page: map}
@returns(200) {messages: [map], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}}
@errors {404}

@endpoint DELETE /v2/apps/{appId}/conversations/{conversationId}/messages
@returns(200)
@errors {404}

@endpoint DELETE /v2/apps/{appId}/conversations/{conversationId}/messages/{messageId}
@returns(200)
@errors {404}

@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/activity
@returns(200)

@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/acceptControl
@optional {metadata: any}
@returns(200)
@errors {403, 404}

@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/offerControl
@required {switchboardIntegration: str}
@optional {metadata: any}
@returns(200)
@errors {404}

@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/passControl
@required {switchboardIntegration: str}
@optional {metadata: any}
@returns(200)
@errors {404}

@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/releaseControl
@optional {metadata: any}
@returns(200)
@errors {403, 404}

@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/download
@returns(200)

@endpoint POST /v2/apps/{appId}/conversations/{conversationId}/conversionEvents
@returns(200) {conversionEvents: map{datasetId: str, eventsReceived: int}}

@endpoint POST /v2/apps/{appId}/integrations
@required {type: str}
@optional {id: str, status: str(inactive/active/error), displayName: str}
@returns(201)
@errors {400}

@endpoint GET /v2/apps/{appId}/integrations
@optional {page: map, filter: map}
@returns(200) {integrations: [map], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}}
@errors {400}

@endpoint GET /v2/apps/{appId}/integrations/{integrationId}
@returns(200)
@errors {404}

@endpoint PATCH /v2/apps/{appId}/integrations/{integrationId}
@returns(200)
@errors {404}

@endpoint DELETE /v2/apps/{appId}/integrations/{integrationId}
@returns(200)
@errors {400, 404}

@endpoint POST /v2/apps/{appId}/integrations/{integrationId}/keys
@required {displayName: str}
@returns(201) {key: map{id: str, displayName: any, secret: str}}

@endpoint GET /v2/apps/{appId}/integrations/{integrationId}/keys
@returns(200) {keys: [map]}
@errors {400}

@endpoint GET /v2/apps/{appId}/integrations/{integrationId}/keys/{keyId}
@returns(200) {key: map{id: str, displayName: any, secret: str}}

@endpoint DELETE /v2/apps/{appId}/integrations/{integrationId}/keys/{keyId}
@returns(200)

@endpoint POST /v2/apps/{appId}/integrations/{integrationId}/webhooks
@returns(201) {webhook: any}
@errors {400, 403, 404}

@endpoint GET /v2/apps/{appId}/integrations/{integrationId}/webhooks
@returns(200) {webhooks: [map]}
@errors {403, 404}

@endpoint GET /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}
@returns(200) {webhook: any}
@errors {404}

@endpoint PATCH /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}
@optional {target: str, triggers: [str], includeFullUser: bool=false, includeFullSource: bool=false}
@returns(200) {webhook: any}
@errors {400, 404}

@endpoint DELETE /v2/apps/{appId}/integrations/{integrationId}/webhooks/{webhookId}
@returns(200)
@errors {404}

@endpoint POST /v2/apps/{appId}/switchboards
@returns(201) {switchboard: any}
@errors {400, 404}

@endpoint GET /v2/apps/{appId}/switchboards
@returns(200) {switchboards: [map]}
@errors {404}

@endpoint PATCH /v2/apps/{appId}/switchboards/{switchboardId}
@optional {enabled: bool, defaultSwitchboardIntegrationId: str}
@returns(200) {switchboard: any}
@errors {404}

@endpoint DELETE /v2/apps/{appId}/switchboards/{switchboardId}
@returns(200)
@errors {404}

@endpoint POST /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations
@required {name: str}
@optional {integrationId: any, integrationType: any, deliverStandbyEvents: any=true, nextSwitchboardIntegrationId: str, messageHistoryCount: int}
@returns(201) {switchboardIntegration: any}
@errors {400, 404}

@endpoint GET /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations
@returns(200) {switchboardIntegrations: [map]}
@errors {404}

@endpoint PATCH /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId}
@optional {name: str, integrationId: any, integrationType: any, deliverStandbyEvents: bool, nextSwitchboardIntegrationId: str, messageHistoryCount: int}
@returns(200) {switchboardIntegration: any}
@errors {404}

@endpoint DELETE /v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations/{switchboardIntegrationId}
@returns(200)
@errors {404}

@endpoint POST /v2/apps/{appId}/users
@required {externalId: str}
@optional {signedUpAt: str, toBeRetained: bool, profile: map{givenName: str, surname: str, email: str(email), avatarUrl: str(uri), locale: str}, metadata: map}
@returns(201) {user: any}
@errors {409}

@endpoint GET /v2/apps/{appId}/users
@required {filter: map}
@returns(200) {users: [any]}

@endpoint GET /v2/apps/{appId}/users/{userIdOrExternalId}
@returns(200) {user: any}
@errors {404}

@endpoint PATCH /v2/apps/{appId}/users/{userIdOrExternalId}
@optional {signedUpAt: any, toBeRetained: any, profile: any, metadata: map}
@returns(200) {user: any}
@errors {404}

@endpoint DELETE /v2/apps/{appId}/users/{userIdOrExternalId}
@returns(200)
@errors {404}

@endpoint POST /v2/apps/{appId}/users/{userIdOrExternalId}/clients
@required {matchCriteria: any, confirmation: map{type!: str, message: any}, target: map{conversationId!: str}}
@returns(201) {client: map{id: str, type: str, status: str, integrationId: str?, externalId: str?, lastSeen: str?, linkedAt: str?, displayName: str?, avatarUrl: str(uri)?, info: map?, raw: map?}}

@endpoint GET /v2/apps/{appId}/users/{userIdOrExternalId}/clients
@optional {page: map}
@returns(200) {clients: [map], meta: map{hasMore: bool, afterCursor: str, beforeCursor: str}, links: map{prev: str, next: str}}
@errors {400}

@endpoint DELETE /v2/apps/{appId}/users/{userIdOrExternalId}/clients/{clientId}
@returns(200)
@errors {400, 404}

@endpoint GET /v2/apps/{appId}/users/{userIdOrExternalId}/devices
@returns(200) {devices: [map]}

@endpoint GET /v2/apps/{appId}/users/{userIdOrExternalId}/devices/{deviceId}
@returns(200) {device: any}
@errors {404}

@endpoint DELETE /v2/apps/{appId}/users/{userIdOrExternalId}/personalinformation
@returns(200) {user: any}
@errors {404}

@endpoint POST /v2/apps/{appId}/users/{zendeskId}/sync
@optional {survivingZendeskId: str}
@returns(200) {user: any}

@endgroup

@group tokenInfo
@endpoint GET /v2/tokenInfo
@returns(200) {app: any}

@endgroup

@group oauth
@endpoint GET /oauth/authorize
@required {client_id: str, response_type: str}
@optional {state: str, redirect_uri: str}
@errors {302}

@endpoint POST /oauth/token
@required {code: str, grant_type: str, client_id: str, client_secret: str}
@returns(200) {access_token: str, token_type: str}

@endpoint DELETE /oauth/authorization
@returns(200)

@endgroup

@end