@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api WINSMS
@base https://api.winsms.co.za/api/rest/v1
@version 1.0.0
@auth ApiKey AUTHORIZATION in header
@endpoints 11
@toc credits(2), sms(7), shortcode(1), subaccounts(1)

@group credits
@endpoint GET /credits/balance
@desc Get your current WinSMS credit balance
@returns(200) OK
@errors {401: Unauthorized, 404: Not found, 405: Method Not Allowed, 500: Internal Server Error}

@endpoint POST /credits/transfer
@desc Transfer credits between main and sub accounts.
@required {creditTransferDetails: map # The details of the credit transfer. Sender account number, recipient account number, and number of credits to transfer.}
@returns(200) OK
@errors {400: Bad Request, 401: Unauthorized, 404: Not found, 405: Method Not Allowed, 413: Payload Too Large, 415: Unsupported Media Type, 422: Unprocessable Entity, 500: Internal Server Error}

@endgroup

@group sms
@endpoint POST /sms/outgoing/send
@desc Send SMS messages
@required {newMessageDetails: map # The message, recipients and delivery options of an SMS message to be sent.}
@returns(200) OK
@errors {400: Bad Request, 401: Unauthorized, 404: Not found, 405: Method Not Allowed, 413: Payload Too Large, 415: Unsupported Media Type, 422: Unprocessable Entity, 500: Internal Server Error}

@endpoint POST /sms/outgoing/sendmulti
@desc Send multiple different SMS messages
@required {multiMessageDetails: map # The messages, recipients and delivery options of multiple SMS messages to be sent.}
@returns(200) OK
@errors {400: Bad Request, 401: Unauthorized, 404: Not found, 405: Method Not Allowed, 413: Payload Too Large, 415: Unsupported Media Type, 422: Unprocessable Entity, 500: Internal Server Error}

@endpoint POST /sms/outgoing/status
@desc Get SMS delivery statuses
@required {messageStatusRequest: [int] # An array of WinSMS API Ids received after submitting messages to the ***/sms/outgoing/send*** endpoint.  A maximum of 1000 API Ids can be supplied in a single request.}
@returns(200) OK
@errors {400: Bad Request, 401: Unauthorized, 404: Not found, 405: Method Not Allowed, 413: Payload Too Large, 415: Unsupported Media Type, 422: Unprocessable Entity, 500: Internal Server Error}

@endpoint GET /sms/scheduled
@desc Get a list of scheduled SMS messages
@optional {offset: any # ***Optional*** - The number of items to skip before starting to return results. Default 0. Minimum 0., limit: any # ***Optional*** - The number of items to return. Default 100. Minimum 1. Maximum 1000.}
@returns(200) OK
@errors {401: Unauthorized, 404: Not found, 405: Method Not Allowed, 422: Unprocessable Entity, 500: Internal Server Error}

@endpoint POST /sms/scheduled/delete
@desc Delete scheduled SMS messages and refund credits
@required {messageDeleteRequest: [int] # An array of WinSMS API Ids received after submitting scheduled messages to the ***/sms/outgoing/send*** endpoint. A maximum of 1000 API Ids can be supplied in a single request.}
@returns(200) OK
@errors {400: Bad Request, 401: Unauthorized, 404: Not found, 405: Method Not Allowed, 413: Payload Too Large, 415: Unsupported Media Type, 422: Unprocessable Entity, 500: Internal Server Error}

@endpoint GET /sms/incoming
@desc Get a list of incoming SMS messages
@optional {offset: any # ***Optional*** - The number of items to skip before starting to return results. Default 0. Minimum 0., limit: any # ***Optional*** - The number of items to return. Default 100. Minimum 1. Maximum 1000.}
@returns(200) OK
@errors {401: Unauthorized, 404: Not found, 405: Method Not Allowed, 422: Unprocessable Entity, 500: Internal Server Error}

@endpoint GET /sms/incoming/optout
@desc Get a list of incoming opt-out SMS messages
@returns(200) OK
@errors {401: Unauthorized, 404: Not found, 405: Method Not Allowed, 500: Internal Server Error}

@endgroup

@group shortcode
@endpoint GET /shortcode/incoming
@desc Get a list of incoming short/long code messages
@optional {offset: any # ***Optional*** - The number of items to skip before starting to return results. Default 0. Minimum 0., limit: any # ***Optional*** - The number of items to return. Default 100. Minimum 1. Maximum 1000.}
@returns(200) OK
@errors {401: Unauthorized, 404: Not found, 405: Method Not Allowed, 422: Unprocessable Entity, 500: Internal Server Error}

@endgroup

@group subaccounts
@endpoint GET /subaccounts
@desc Get a list of all Sub Accounts.
@returns(200) OK
@errors {401: Unauthorized, 404: Not found, 405: Method Not Allowed, 500: Internal Server Error}

@endgroup

@end