ASCOM ALPACA

API Reference - Version 7

Abstract
This document is the technical reference for the ASCOM Alpaca APIs and describes how to
use the API. It also describes the Alpaca Discovery protocol and some of the fundamental
behavioural principles that underly the APIs and their effective exploitation.

Peter Simpson, Bob Denny, Daniel Van Noord

Contents
1. Introduction ......................................................................................................................................... 3
1.1 Language ...................................................................................................................................... 3
1.2 Alpaca Devices ............................................................................................................................. 3
1.3 Consolidation ............................................................................................................................... 4
1.4 Supported ASCOM Device Types ................................................................................................ 4
1.5 ASCOM Alpaca API Documentation ............................................................................................ 4
1.6 Discovery ...................................................................................................................................... 4
1.7 Robustness Principle (Postel’s Law) ........................................................................................... 4
2. Alpaca Device API Contract ................................................................................................................. 5
2.1 Alpaca Device API Format ........................................................................................................... 5
2.1.1 Basic format ......................................................................................................................... 5
2.1.2 Alpaca API Path .................................................................................................................... 5
2.1.3 Device number ..................................................................................................................... 5
2.1.4 Parameters ........................................................................................................................... 5
2.2 Case Sensitivity............................................................................................................................. 6
2.2.1 URL Path Elements .............................................................................................................. 6
2.2.2 Query Parameters (HTTP GET methods) ............................................................................ 6
2.2.3 Form Parameters (HTTP PUT Methods) ............................................................................. 6
2.2.4 REST Response Key Names ................................................................................................. 6
2.3 Locale and Culture ....................................................................................................................... 7
2.3.1 Encoding Parameter Values That Have Decimal Points ..................................................... 7
2.3.2 JSON Responses .................................................................................................................. 7
2.4 Http Verbs .................................................................................................................................... 7
2.5 HTTP Status Codes ....................................................................................................................... 7
2.5.1 Status Code Examples - Transactions with Valid Paths ...................................................... 9
2.5.2 Status Code Examples - Transactions with Bad Paths ....................................................... 9
2.6 ID Fields ........................................................................................................................................ 9
2.7 JSON Responses ........................................................................................................................ 10
2.8 Reporting Device Errors Through the Alpaca API .................................................................... 10
2.8.1 Historic COM Approach ..................................................................................................... 10
2.8.2 New Alpaca Approach ........................................................................................................ 11
2.8.3 ASCOM Reserved Error Numbers ...................................................................................... 11
2.8.4 Driver Specific Error Numbers ............................................................................................ 11
2.8.5 Error Number Backwards Compatibility ............................................................................ 11
2.8.6 Driver Error Example........................................................................................................... 11
2.9 Alpaca API Version versus ASCOM Device InterfaceVersion .................................................... 11
3. Alpaca Device Management............................................................................................................... 13

API Reference - Version 7 1 16th June 2022

 3.1 HTML Interfaces.......................................................................................................................... 13
3.1.1 Main Alpaca Setup URL ...................................................................................................... 13
3.1.2 ASCOM Device Specific Setup URLs .................................................................................. 13
3.2 JSON Management API ............................................................................................................. 14
3.2.1 Supported API Versions ..................................................................................................... 14
3.2.2 Description and Configured Devices ................................................................................. 14
3.2.3 Globally Unique IDs (UIDs) ................................................................................................. 15
4. Alpaca Discovery ................................................................................................................................ 16
4.1 Introduction ............................................................................................................................... 16
4.2 Definitions .................................................................................................................................. 16
4.3 Alpaca Discovery Protocol - IPv4............................................................................................... 16
4.3.1 Clients ................................................................................................................................. 16
4.3.2 Devices................................................................................................................................ 16
4.4 Alpaca Discovery Protocol - IPv6............................................................................................... 18
4.4.1 Clients ................................................................................................................................. 18
4.4.2 Devices................................................................................................................................ 18
4.5 Discovery Message Format ....................................................................................................... 18
4.6 Discovery Response Format ...................................................................................................... 19
4.7 Unique IDs (UID) ........................................................................................................................ 19
4.8 Implementation Requirements ................................................................................................. 19
4.8.1 Discovery Port .................................................................................................................... 19
4.8.2 IP versions .......................................................................................................................... 19
5. ASCOM APIs - Essential Concepts ..................................................................................................... 20
5.1.1 Object Models - Properties and Methods ......................................................................... 20
5.1.2 ASCOM API Characteristics................................................................................................ 20
5.1.3 Behavioural Rules................................................................................................................ 21
6. Document Revision Log..................................................................................................................... 22

API Reference - Version 7 2 16th June 2022

1. Introduction
1.1 Language
When used within this document, these words have the following meanings:

Term Meaning
Alpaca Device Hardware or software that supports the Alpaca Management and Alpaca
Device API protocols to provide access to one or more ASCOM Devices.
ASCOM Device An implementation of an ASCOM device interface such as ITelescope or
IFocuser that can be accessed through the Alpaca Device API protocol.
ASCOM Device Type One of ASCOM’s supported hardware device types e.g. telescopes,
focusers, rotators and cameras.
IP Endpoint The host / IP address and port number on which the Alpaca device is
operating
Must This is an absolute, mandated, requirement; no deviation is possible.
Should This is highly recommended best practice, but is not mandated
Could This is optional at the implementor’s discretion

1.2 Alpaca Devices

An Alpaca Device is a hardware device or software program that presents one or more ASCOM
Devices through the Alpaca protocol and communicates with clients over a TCP/IP network through
its IP Endpoint.

IP End Point IP End Point

Alpaca Device Alpaca Device

ASCOM Device ASCOM Device

ASCOM Device
Simple Alpaca Device
ASCOM Device
ASCOM Device
ASCOM Device
ASCOM Device

Complex Alpaca Device

The simplest Alpaca Device would present a single ASCOM Device, such as a focuser or filter wheel,
and would be dedicated to this single task. This approach will work well for existing devices that
support serial or USB connections for example and that are to be updated to support network
connectivity.

A complex Alpaca Device may present multiple1 ASCOM Devices of several different ASCOM Device
Types through its single IP Endpoint. For example, a single Alpaca Device could present a dome, a
mount, several focusers, a filter wheel and a rotator together with some observing conditions
devices.

1 Each Alpaca device can support up to 2,147,483,647 instances of each of the supported ASCOM Device Types.

API Reference - Version 7 3 16th June 2022

In today’s ASCOM COM architecture all drivers fit the “simple” model above where one ProgID, the
device’s well-known address, is associated with just one ASCOM Device.

1.3 Consolidation
The Alpaca API supports consolidation of multiple downstream Alpaca Devices into one virtual
Alpaca Device that presents a single aggregated device tree under one IP end point. This opens the
way to creation of physical devices that proxy Alpaca requests and to the use of web servers as
reverse proxies that front multiple Alpaca Devices.

1.4 Supported ASCOM Device Types

All ASCOM device types are supported except for Video. This was omitted because the Video
interface specifies that recorded video is saved as a file on local storage rather than being streamed
over an IP network.

1.5 ASCOM Alpaca API Documentation

The ASCOM RESTful APIs are documented using the Swagger toolset and are available through a
URL on the ASCOM Standards web site. The ASCOM API is fully documented here:
https://www.ascom-standards.org/api

To start exploring, go to the above URL and select either the “Device API” or the “Management API”
description using the drop-down at the top of the screen. You can then click a grey Show/Hide link to
expand one of the sets of methods and then click the blue GET or orange PUT methods for detailed
information on that API call.

Anyone who is familiar with the ASCOM COM based APIs should feel at home with the functionality
available through the Alpaca API.

1.6 Discovery
For the best astronomer user experience, Alpaca Devices should also implement the Alpaca
Discovery protocol (see section 4, Alpaca Discovery)

1.7 Robustness Principle (Postel’s Law)

“Be conservative in what you do, be liberal in what you accept from others.”

Alpaca clients and devices should behave in line with the robustness principle. For example:

• Alpaca clients should ensure that their commands adhere exactly to the API specification.
• Alpaca devices should ensure that their responses adhere exactly to the API specification.
• Alpaca clients and devices should not return errors when optional elements such as ClientID
or ServerTransactionID are not present.
• Alpaca clients and devices should not return errors when unrecognised parameters are
received.

API Reference - Version 7 4 16th June 2022

2. Alpaca Device API Contract
This section describes the Alpaca Device API format and assumes a basic knowledge of HTTP, JSON
and REST. The full Alpaca Device API is defined here: Device API Definition.

2.1 Alpaca Device API Format

2.1.1 Basic format
Alpaca APIs follow the standard Internet URL format:
http(s)://host:port/path?parameters

2.1.2 Alpaca API Path

The Alpaca device API path consists of five elements:
/api/vversion_number/device_type/device_number/command

Fixed elements are blue and variable elements are red.

Element Number Element Description

1 api Fixed lower-case text denoting the root of the API path
2 vversion_number Integer API version number prefixed with a lower-case v
3 device_type ASCOM device type e.g. camera, telescope, focuser etc.
4 device_number Integer device number of the required device
5 command Command to be processed by the device in lower-case

For example, these are valid API calls:

http://api.peakobservatory.com/api/v1/telescope/0/atpark
http://api.peakobservatory.com/api/v1/camera/0/imagearray

2.1.3 Device number

The device number, starting at 0 for each device type, (in the range 0:: 4294967295) must be unique
within the device type, but the same device number can be used concurrently within multiple device
types. E.g. all these paths are permissible within the same Alpaca device:
/api/v1/telescope/0/...
/api/v1/rotator/0/...
/api/v1/focuser/0/...

2.1.4 Parameters
Many ASCOM methods require parameter values. All methods that use the HTTP GET verb should
include parameters as query string name-value pairs.

All methods that use the HTTP PUT verb should include name-value parameters in the body using the
"application/x-www-form-urlencoded" media type.

For example, these are valid API parameters on an HTTP GET transaction:
/api/v1/telescope/0/canslew?clientid=231&clienttransactionid=23

API Reference - Version 7 5 16th June 2022

2.2 Case Sensitivity
2.2.1 URL Path Elements
All five elements of the API path are case sensitive and must always be in lower case. For example,
this is the only valid casing for a call to the Telescope.CanSlew property:
/api/v1/telescope/0/canslew

These are examples of incorrect casing:

/API/V1/TELESCOPE/0/CANSLEW /Api/V1/Telescope/0/CanSlew
/api/v1/telescopE/0/canslew /api/v1/telescope/0/CanSlew

2.2.2 Query Parameters (HTTP GET methods)

Alpaca parameters are key-value pairs where:
• The parameter key is case insensitive
• The parameter value can have any casing required.

This is the same behaviour as defined for HTTP header keys in RFC 2616 (HTTP/1.X) and RFC7540
(HTTP/2).

For example, these are all valid API parameters:

/api/v1/telescope/0/canslew?clientid=231&clienttransactionid=23
/api/v1/telescope/0/canslew?ClientID=231&ClientTransactionID=23
/api/v1/telescope/0/canslew?CLIENTID=231&CLIENTTRANSACTIONID=23

Clients and drivers must expect incoming query parameter keys to have arbitrary casing.

2.2.3 Form Parameters (HTTP PUT Methods)

Clients must case Form parameter names as specified in the online API Definition. For example,
correct parameter name casing for the X binning parameter in the PUT Camera.BinX method is:
BinX

These are examples of incorrect casing:

binx
BINX
binX

2.2.4 REST Response Key Names

JSON key names are case sensitive. Consequently, returned Alpaca parameter names must use the
casing specified in the online API definition. For example: the GET Telescope.Altitude response must
use this key name casing:
Value, ClientTransactionID, ServerTransactionID, ErrorNumber, ErrorMessage

These are examples of incorrect casing:

value, clientTransactionID, serverTransactionID, errorNumber, errorMessage
value, clienttransactionid, servertransactionid, errornumber, errormessage

API Reference - Version 7 6 16th June 2022

2.3 Locale and Culture
The Alpaca API is culture neutral in order to facilitate use between clients and devices running in
different locales, e.g. a client running on a UK locale device connecting to a remote device running
with a Spanish locale.

This has consequences for data formats in two circumstances:

2.3.1 Encoding Parameter Values That Have Decimal Points

When decimal parameter values are passed into the API, they must use period (0x2E) as the decimal
separator. This is so that they can be reliably parsed on receipt

E.g. 23.456 is a valid value to supply when setting the Telescope.TargetRightAscension property,
while 23,456 is not a valid value.

2.3.2 JSON Responses

JSON responses must be formatted in accordance with the JavaScript Object Notation (JSON) Data
Interchange Format specification RFC 8259. In consequence Alpaca devices must use the period
character (0x2E) as the decimal separator when returning decimal values.

Alpaca Clients must expect to receive decimal values in this invariant culture format and to interpret
them accordingly.

e.g. Clients must parse the value returned by the Telescope.SiteElevation property using period as
the decimal separator, regardless of the locale in which they are running.

2.4 Http Verbs

Verb Description
GET Used for all information retrieval where the device state is not changed, e.g. most
properties and a few functions such as Telescope. AxisRates(Axis).
PUT Used for all commands which change the state of the device, e.g.
Telescope.SideOfPier and Telescope.SlewToCoordinates().

2.5 HTTP Status Codes

The purpose of ASCOM interfaces is to hide real world device implementation behind a standard
facade represented by an ASCOM interface. In the business world IT developers would consider the
interfaces to be part of the enterprise’s “business logic”. ASCOM’s “business logic” defines a clear
interface contact between client and device that includes its own “do it or return an error” error
handling mechanic, which takes the form of an error number / error message pair.

Alpaca is essentially a presentation layer for the ASCOM interface “business logic” and this
distinction between transport mechanic behaviour and ASCOM interface business logic behaviour is
reflected in Alpaca’s use of HTTP status codes.

Figure 1 - Alpaca HTTP status decision tree shows this separation, with HTTP 3XX and 4XX status codes
reflecting issues in the HTTP and Alpaca protocols, such as lack of authentication, badly formed or
missing parameters. These HTTP statuses indicate that the device:

• Refused to carry out the command for some reason e.g. could not authenticate the user
• Did not understand the operation it was being asked to perform

API Reference - Version 7 7 16th June 2022

 • Did not receive the required information to attempt to carry out the intended ASCOM
interface operation.

A 200 status indicates that the “business logic” ASCOM interface command was understood, and
that the device attempted to carry it out using ASCOM’s “Do it or return an error” mechanic. The
resultant JSON response includes an ErrorNumber value that the client can inspect to determine
whether the operation was successful in an ASCOM interface sense.

These status codes should be used in device responses to Alpaca clients:

Code Interpretation Extended Interpretation

200 ASCOM interface The API request was understood and the “Do it or return an
operation was error” ASCOM interface method was executed. The response is
executed in the JSON format as defined in the Alpaca API specification.
400 ASCOM interface The API request could not be understood or was rejected. The
operation was not response is a text error message and is not in the expected JSON
executed format.
500 Unexpected device A serious technical error occurred in the Alpaca device which
error prevented successful processing of the request. The response is
a text error message and is not in the expected JSON format.

The following flow diagram shows how to decide which HTTP status code to return.
Access control

YES Return appropriate

Reject or redirect
response and
this request?
HTTP 3XX / 4XX Status

NO The device is willing to execute the command

Alpaca API protocol validation

HTTP method and NO Return text message

supplied URL are
with HTTP 400 Status
valid?

YES Alpaca API syntax is valid

Device number NO Return text message

and parameters
with HTTP 400 Status
are valid?

YES All information required to carry out the command is present

Return JSON response

Was the
ASCOM device API specification

YES
Execute in accordance with the

Attempt to carry out the with HTTP 200 Status,

command
command ErrorMessage =
successful?
and ErrorNumber = 0

Return JSON response

NO with HTTP 200 Status,
ErrorMessage = Description
and ErrorNumber > 0

Catastrophic, unrecoverable Return text message

error occurs at any point with HTTP 500 Status

Figure 1 - Alpaca HTTP status decision tree

API Reference - Version 7 8 16th June 2022

Please note that, catastrophic errors aside, an HTTP 200 status must be returned when the device
understands the supplied command regardless of whether or not it can action it in an ASCOM sense.

2.5.1 Status Code Examples - Transactions with Valid Paths

A “200” status code must be returned if the transactions below were received by an Alpaca
Telescope device that supports Alpaca interface version 1:

Path Reason for Rejection with 200 Status

PUT /api/v1/telescope/0/park Assuming this telescope device does not have
park functionality, it would return a
NotImplemented Alpaca error code (0x400)
and message with an HTTP 200 status.
PUT /api/v1/telescope/0/siteelevation Elevations lower than -300m are invalid so
New value: -400 return an InvalidValue Alpaca error code
(0x401) and message with an HTTP 200 status.

2.5.2 Status Code Examples - Transactions with Bad Paths

A “400” status code must be returned if the transactions below were received by a single Alpaca
Camera device that only supports Alpaca interface version 1:

Path Reason for Rejection with 400 Status

GET: /apii/v1/telescope/0/canslew Valid Alpaca API requests start with “api” rather than “apii”.
GET: /api/v2/telescope/0/canslew The Alpaca “v2” API is not supported by the device.
GET: /api/v1/telescop/0/canslew “telescop” is not one of the valid ASCOM device types.
GET: /api/v1/camera/1/canslew Camera device 1 does not exist.
GET: /api/v1/camera/0/canslew “CanSlew” is not a valid Camera command.

2.6 ID Fields
To aid operational management and debugging, three ID fields are defined for use in read and write
transactions:

ID Maintained by Description
ClientID Client This is a 32-bit unsigned integer that the client can
choose to identify itself. It is recommended that values
should be within the range 0::65535 so that log files
appear orderly and readable!
ClientTransactionID Client This is a 32-bit unsigned integer that the client
maintains. The value should start at 1 and be
incremented by the client on each request to the
Alpaca device.
ServerTransactionID Alpaca Device This is a 32-bit unsigned integer that the Alpaca device
maintains. The value should start at 1 and be
incremented by the Alpaca device on each request.

The client id and transaction numbers should be supplied by the client in the request to uniquely
identify the client instance and specific transaction. The Alpaca device must return the client

API Reference - Version 7 9 16th June 2022

transaction number, or zero if no value was supplied by the client, as part of its response to enable
the client to confirm that the response does relate to the request it submitted.

Alpaca devices should record client ids and transaction numbers in their logs so that issues can be
tied back to specific transactions and outcomes correlated with client-side logs.

The server transaction id must be returned by the Alpaca device with every response so that issues
identified on the client side can easily be correlated with Alpaca device logs.

2.7 JSON Responses

The outcome of the command is returned in JSON encoded form. The following information must
always be returned in every transaction response that has an HTTP 200 status:

Item Type Contents

ClientTransactionID Unsigned 32-bit integer Transaction ID supplied by the client in its
request
ServerTransactionID Unsigned 32-bit integer The server’s transaction number.
ErrorNumber Signed 32-bit integer ASCOM Alpaca error number, see section 2.8.3.
ErrorMessage String If the driver throws an exception, its message
appears here, otherwise an empty string is
returned.

In addition, the JSON response will include the output from the command (if any) in the “Value”
parameter. This example is from the Telescope Simulator SupportedActions property:
GET /api/v1/telescope/0/supportedactions?ClientID=1&ClientTransactionID=6

{"Value":["AssemblyVersionNumber","SlewToHA","AvailableTimeInThisPointingState","TimeUntilPo
intingStateCanChange"],"ClientTransactionID":6,"ServerTransactionID":6, "ErrorNumber":0,
"ErrorMessage":"" }

This example shows the response from the Telescope simulator’s CanSlewAsync property:
GET /api/v1/telescope/0/canslewasync?ClientID=1&ClientTransactionID=20

{"Value":true,"ClientTransactionID":20,"ServerTransactionID":168, "ErrorNumber":0,
"ErrorMessage":"" }

2.8 Reporting Device Errors Through the Alpaca API

2.8.1 Historic COM Approach
ASCOM COM drivers use a range of reserved ASCOM exceptions and unique driver specific
exceptions to report issues to COM clients such as “this method is not implemented” or “the
supplied parameter is invalid” and these are documented in the Developer Help file at:
https://ascom-standards.org/Help/Developer/html/N_ASCOM.htm

Each exception has an associated HResult code in the range 0x80040400 to 0x80040FFF for historic
reasons related to Microsoft’s approach to error handling for COM applications. When expressed as
signed integers these exception numbers translate into very large and unwieldy negative numbers
e.g. 0x80040400 becomes -2,147,220,480 and 0x80040FFF becomes -2,147,217,409.

API Reference - Version 7 10 16th June 2022

2.8.2 New Alpaca Approach
Alpaca devices still need to express different error conditions to the client so, for Alpaca, the error
number range has been simplified to the range 0x400 (1024) to 0xFFF (4095) by truncating the
leftmost 5 digits so that an Alpaca error number of 0x401 would have the same meaning as the
original COM error with HResult of 0x80040401.

2.8.3 ASCOM Reserved Error Numbers

The following table relates the new Alpaca error codes for reserved ASCOM error conditions to the
corresponding COM HResult numbers, which are in the range 0x80040400 to 0x800404FF.

Condition Alpaca Error Number COM Exception Number

Successful transaction 0x0 (0) N/A
Property or method not implemented 0x400 (1024) 0x80040400
Invalid value 0x401 (1025) 0x80040401
Value not set 0x402 (1026) 0x80040402
Not connected 0x407 (1031) 0x80040407
Invalid while parked 0x408 (1032) 0x80040408
Invalid while slaved 0x409 (1033) 0x80040409
Invalid operation 0x40B (1035) 0x8004040B
Action not implemented 0x40C (1036) 0x8004040C

2.8.4 Driver Specific Error Numbers

The Alpaca error number range for driver specific errors is 0x500 to 0xFFF and their use and
meanings are at the discretion of driver / firmware authors.

2.8.5 Error Number Backwards Compatibility

Native Alpaca clients will inspect the ErrorNumber and ErrorMessage fields as returned to determine
if something went wrong with the transaction. However, to ensure COM client backward
compatibility, the Platform’s Dynamic clients will translate Alpaca error numbers into their equivalent
COM exception numbers before throwing the expected ASCOM exceptions to the COM client.

2.8.6 Driver Error Example

The following example shows the expected invalid value JSON response when an attempt is made to
set the site elevation to -400, which is below the minimum allowed value of -300.
PUT /api/v1/telescope/0/siteelevation
(parameters for the PUT verb are placed in the form body (not shown here) and do not appear after the
URI as they do for the GET verb)

Expected JSON response:

{"ClientTransactionID":23,"ServerTransactionID":55,"ErrorNumber":1025,
"ErrorMessage":"SiteElevation set - '-400' is an invalid value. The valid range is: -300 to 10000."}

2.9 Alpaca API Version versus ASCOM Device InterfaceVersion

The scope of the Alpaca API version number is just the new Alpaca API presentation elements and
their order as described in sections 2.1 and 3.1.2. Any change to the naming, format or order of the

API Reference - Version 7 11 16th June 2022

elements in these URLs would constitute a breaking change and require that the Alpaca API version
be incremented so that clients and devices can adapt their behaviour to match the new standard.

For backward compatibility, a device can support more than one interface version. A list of
supported interface versions is available through the Alpaca management API as described in section
3.2.1.

Examples of breaking changes that would require a new Alpaca API version number:
• Changing element 1 from “api” to “alpacaApi”
• Changing the element 2 version number format from “v1” to “v1.0.0.0”
• Introducing a new element 6

The ASCOM Device InterfaceVersion defines the behaviour of the specified ASCOM Device when
presented with commands through the Alpaca API. InterfaceVersions will change as device APIs are
developed, however these changes are independent of the Alpaca API presentation elements and so
do not require that the Alpaca API version be changed as well.

API Reference - Version 7 12 16th June 2022

3. Alpaca Device Management
This section describes the HTTP and REST management APIs for Alpaca devices.

3.1 HTML Interfaces

The Alpaca Management API defines a main HTML browser URL that acts as the primary user entry
point for the whole Alpaca device. The returned web page must, at minimum, display overall
information about the device and its manufacturer.

In addition, the API defines a dedicated URL for each ASCOM Device presented by the Alpaca Device
so that ASCOM Device specific configuration can be set. This API is intended to facilitate
configuration of a single ASCOM Device, in a similar fashion to the COM SetupDialog method.

3.1.1 Main Alpaca Setup URL

The main Alpaca Device setup HTTP page should be provided on the “setup” path of the device’s
Alpaca Port:
http(s)://host:port/setup

At minimum this must provide manufacturer and device descriptive information. This could be a
good place to enable the astronomer user to change the Alpaca discovery port number and any
other “whole device” configuration settings.

3.1.2 ASCOM Device Specific Setup URLs

These follow a similar format to the Alpaca Device API with an overall format of:
http(s)://host:port/path

The Alpaca device API path consists of five elements:

/api/vversion_number/device_type/device_number/command

Fixed elements are blue and variable elements are red.

Element Number Element Description

1 setup Fixed lower-case text denoting the root of the API path
2 vversion_number Integer API version number prefixed with a lower-case v
3 device_type ASCOM device type e.g. camera, telescope, focuser etc.
4 device_number Integer device number of the required device
5 setup Fixed lower case text denoting the device setup page

For example, this is a device specific setup URL for telescope 0:

http://api.peakobservatory.com/setup/v1/telescope/0/setup

API Reference - Version 7 13 16th June 2022

3.2 JSON Management API
The Alpaca management API is described here: Alpaca Management API.

3.2.1 Supported API Versions

The Alpaca device API uses an interface version number (see section 2.9) to manage changes to the
Alpaca access elements that are described in section 2.1. The format of the apiversions URL is:
http(s)://host:port/management/apiversions

For example, this is an api version URL:

http://api.peakobservatory.com/management/apiversions

Please note that there is no Alpaca API version number in the apiversions URL.

This is by design so that this URL will work regardless of any Alpaca interface version number
changes in the future.

To provide backward compatibility, an Alpaca device can simultaneously support more than one
Alpaca interface version, and this is indicated by returning more than one integer version number in
the apiversions array.

At the time of writing only interface version 1 is defined and consequently all Alpaca devices should
return an integer array, containing the single value 1, as the response to this command.

3.2.2 Description and Configured Devices

The “description” endpoint should return cross cutting information about the Alpaca Device as a
whole, such as its name and location.

The “configureddevices” endpoint should return an array of device configuration objects that
describe the ASCOM Device’s that are presented by the Alpaca Device. Each device description must
include the device’s name, it’s ASCOM device type, the device number that must be used to
communicate with this particular ASCOM Device and a globally unique id for this particular device.

The Alpaca management API path for these commands consists of three elements:
/management/vversion_number/command

Fixed elements are blue and variable elements are red.

Element Number Element Description

1 management Fixed lower-case text denoting the root of the API path
2 vversion_number Integer API version number prefixed with a lower-case v
3 command Either “description” or “configureddevices” as required

For example, these are valid calls:

http://api.peakobservatory.com/management/v1/description

http://api.peakobservatory.com/management/v1/configureddevices

API Reference - Version 7 14 16th June 2022

3.2.3 Globally Unique IDs (UIDs)
These are string identifiers that must be globally unique. This means that identical hardware devices
must have unique individual UID’s that are never assigned to other devices of the same type and are
never assigned to devices of any other type.

The purpose of UIDs is to support “re-discovery” of Alpaca Devices in the event that a device’s IP
address changes but where client configurations are not automatically revised to match. For further
information please see section 0.

API Reference - Version 7 15 16th June 2022

4. Alpaca Discovery
4.1 Introduction
Clients can discover Windows COM based drivers through ASCOM’s registry-based Chooser
capability. However, Alpaca devices can run on any operating system and may be located on
different devices than client applications. Consequently, Alpaca clients need a discovery mechanism
that enables them to locate Alpaca devices within their local network environment.

4.2 Definitions
Within this section “Device” refers to something (a driver or device) that exposes the Alpaca
interface and “Client” refers to client applications that want to locate and use the Device's API(s).

• DISCOVERY PORT: the port to which the Client Broadcasts the discovery message and on
which the Device listens. The Alpaca default discovery port is 32227.
• DISCOVERY MESSAGE: the message broadcast by the client on the DISCOVERY PORT.
• RESPONSE MESSAGE: is the message that the Device sends back via unicast to the client.
• ALPACA PORT: is the port on which the Alpaca management and device APIs are available.
• ASCOM DEVICE: An implementation of an ASCOM device interface such as ITelescope or
IFocuser that can be accessed through the Alpaca Device API protocol.
• UNIQUE ID: A string identifier for an ASCOM DEVICE that is globally unique.
• ALPACA DEVICE: Hardware or software that supports the Alpaca Management and Alpaca
Device API protocols to provide access to one or more ASCOM DEVICES.

4.3 Alpaca Discovery Protocol - IPv4

4.3.1 Clients
Clients find devices through a UDP protocol (see Figure 2) that uses:
• the IPv4 network broadcast address
• a designated IP port number, whose default is 32227
• a structured DISCOVERY MESSAGE
• a structured RESPONSE MESSAGE
To search for and use ALPACA DEVICES, a client should:
1. Transmit a DISCOVERY MESSAGE to the DISCOVERY PORT by broadcast (IPv4).
2. Use the IP address from the RESPONSE MESSAGE together with the ALPACA PORT from the
DISCOVERY RESPONSE to query the Alpaca Management API to determine which ASCOM
DEVICES and device types are available.
3. When selected by the user, access specific devices through the ALPACA DEVICE API that also
runs on the ALPACA PORT at the IP address of the initiator of the RESPONSE MESSAGE.
4.3.2 Devices
To listen for IPv4 DISCOVERY MESSAGEs, Alpaca devices should:

1. Listen for IPv4 broadcasts on the DISCOVERY PORT

2. Assess each received message to confirm whether it is a valid DISCOVERY MESSAGE.
3. If the request is valid, return a RESPONSE MESSAGE indicating the device’s ALPACA PORT.
The following figure gives a conceptual overview of the IPv4 and IPv6 discovery processes.

API Reference - Version 7 16 16th June 2022

 Discovery Protocol Example

Client Alpaca Device

Listen for Alpaca discovery Listen for Alpaca

Search for Alpaca devices broadcasts and multicasts on API requests on its
DISCOVERY PORT ALPACA PORT
Discovery Phase

Send Alpaca DISCOVERY MESSSAGE by Valid DISCOVERY

IPv4 broadcast or IPvc6 multicast MESSAGE?

Yes

Return Alpaca
Parse Alpaca RESPONSE MESSAGE
RESPONSE MESSAGE
to extract the device s ALPACA PORT
containing the ALPACA PORT

Find available ASCOM devices

Selection Phase

Send Alpaca Management API Valid

ConfiguguredDevices request on the Management API
device s ALPACA PORT request?

Yes

Present list of ASCOM devices enabling Return a list of available

the user to select one. ASCOM devices

Use an Alpaca device

Send requests to the selected

Use Phase

Valid Device
ASCOM DEVICE through the
API request?
Alpaca Device API.

Yes

Return device s response to

Process the response.
the request.

Figure 2 - Alpaca IPv4 and IPv6 discovery protocol

API Reference - Version 7 17 16th June 2022

4.4 Alpaca Discovery Protocol - IPv6
4.4.1 Clients
Clients find devices through a UDP protocol (see Figure 2 - Alpaca IPv4 and IPv6 discovery protocol)
that uses:
• the fixed IPv6 link local multicast address: ff12::a1:9aca
• a designated IP port number, whose default is 32227
• a structured DISCOVERY MESSAGE
• a structured RESPONSE MESSAGE
To search for and use ALPACA DEVICES, a client should:
1. Transmit a DISCOVERY MESSAGE to the DISCOVERY PORT using IPv6 multicast address
ff12::a1:9aca.
2. Use the IP address from the RESPONSE MESSAGE together with the ALPACA PORT from the
DISCOVERY RESPONSE to query the Alpaca Management API to determine which ASCOM
DEVICES and device types are available.
3. When selected by the user, access specific devices through the ALPACA DEVICE API that also
runs on the ALPACA PORT at the IP address of the initiator of the RESPONSE MESSAGE.
4.4.2 Devices
To listen for DISCOVERY MESSAGEs, Alpaca devices should:

1. Join the Alpaca IPv6 multicast group on address ff12::a1:9aca.

2. Listen for Alpaca IPv6 multicasts on the DISCOVERY PORT
3. Assess each received message to confirm whether it is a valid DISCOVERY MESSAGE.
4. If the request is valid, return a RESPONSE MESSAGE indicating the device’s ALPACA PORT.

4.5 Discovery Message Format

To provide for future extension, if required, the DISCOVERY MESSAGE has a structured format:

Byte Number Content

0::14 Fixed ASCII text: alpacadiscovery
15 ASCII Version number: 1 for the current version.
The version number sequence is 1::9 then A::Z.
16::63 ASCOM reserved for future expansion
Table 1 - Discovery message format

The current, version 1, discovery message therefore contains 16 bytes, comprising 15 bytes from the
ASCII text: “alpacadiscovery” together with a single ASCII version byte:
alpacadiscovery1

Hex: 0x61, 0x6C, 0x70, 0x61, 0x63, 0x61, 0x64, 0x69, 0x73, 0x63, 0x6F, 0x76, 0x65, 0x72, 0x79, 0x31

The discovery message “alpacadiscovery” has been registered to ASCOM in the IANA service
registry:

https://www.iana.org/assignments/service-names-port-numbers

API Reference - Version 7 18 16th June 2022

4.6 Discovery Response Format
The ALPACA DEVICE response must be a JSON object containing the device’s ALPACA PORT e.g.:
{
"AlpacaPort":12345
}

4.7 Unique IDs (UID)

An ASCOM DEVICE’s UID is returned within the Alpaca Management API ConfiguredDevices
response.

The UID is an ASCII string that MUST be unique to each ASCOM DEVICE. Its purpose is to help clients
re-discover a previously used ASCOM DEVICE if its IP address changes.

1. The UID must be derived from a 48bit or larger space and converted to an ASCII string.
2. The UID must be exposed through the UniqueID field of the Alpaca Management API
ConfiguredDevices response.
3. Manufacturers and developers must use appropriate algorithms to ensure that otherwise
identical devices have different UIDs.
4. Alpaca Devices MUST send the same UIDs on every network interface to which the device is
attached.
5. Once a UID has been assigned to an ASCOM DEVICE, it must never change. This means that:
a. An ASCOM DEVICE served by an ALPACA DEVICE will always be uniquely identifiable
through the assigned UID.
b. UID must be retained when devices are powered down.

4.8 Implementation Requirements

4.8.1 Discovery Port
The Alpaca DISCOVERY PORT number must default to 32227 and should not require adjustment in
most implementation scenarios. However, the DISCOVER PORT must be configurable by the
astronomer user to support scenarios such as:

• the default DISCOVERY PORT is in use by another application.

• the network configuration requires multiple independent Alpaca discovery domains.

4.8.2 IP versions
All Alpaca devices should support IPv4 to ensure widest adoption and best compatibility with client
devices and astronomy equipment. Devices could also support IPv6 at the discretion of the
manufacturer / software author.

API Reference - Version 7 19 16th June 2022

5. ASCOM APIs - Essential Concepts
Today's world is clearly modular, cross-platform, and distributed. The core aspect of any modular
system is its interfaces. If a system is built on top of poorly designed interfaces, it suffers throughout
its life with limitations, instabilities, gremlins, and the like. Interface design and negotiation is an
engineering art, the best practitioners are those that have suffered and learned.

5.1.1 Object Models - Properties and Methods

The ASCOM APIs are built on an object model which provides properties that represent some state
of the device, and methods that can change the state of the device. For example, the current
positional right ascension of a telescope mount is a property, and a command to slew the mount to a
different position is a method. In ASCOM COM, properties are normally accessed by assignment
statements in the native syntax of any of twenty languages on Windows. Methods are represented
by native syntax function calls, some with parameters. There are exceptions. Some properties
require parameters to signify some aspect of state, and thus may be represented by a function call
which returns the property value (which need not be a scalar), for example,
Telescope.AxisRates(Axis).

5.1.2 ASCOM API Characteristics

The following information applies to the existing COM-based ASCOM APIs as well as the REST-based
APIs. The behaviours must be the same to provide transparent interoperation.

• Routine Operations: Interface design always involves some negotiations between the
parties. Inevitably, a device maker may wish to have included in the interface some clever
means to make their device stand out above those of his competitors. On the other hand,
client programmers don't want to be writing code to manage an ever-expanding set of
these clever functions. It defeats the purpose of the standardized API. The ASCOM API was
therefore designed at its outset to cover routine operations only.

For example, a mount really only needs "point to these coordinates" and "track the
apparent motion of my object". The more accurately it does these things, the better. As a
client program developer, I don't want to be concerned about PEC or encoder resolutions or
servo currents.

• Synchronous vs Asynchronous Methods: One may think of a method call as one that returns
only when the requested operation has completed, which is a synchronous call. But some
types of operations can benefit by starting the operation and returning immediately. For
example, the Rotator.Move() method may return immediately.

If so, its return means only that the rotation was successfully started. Rotators are typically
slow, and the system can benefit by overlapping mount and rotator movement, so both
provide asynchronous calls. The status properties such as Rotator.IsMoving and
Telescope.IsSlewing are used to monitor progress of asynchronous calls.

• "Can" Properties: Some ASCOM APIs have "can" properties, which tell the client whether or
not a corresponding capability is available. For example, in the Telescope API, the
CanSlewAltAz property tells the client whether this specific mount can successfully execute

API Reference - Version 7 20 16th June 2022

 the SlewToAltAz() method. These "can" properties exist only for methods which can't be
directly tested without changing the state of the device.

For example, a client can tell that the mount provides its positional azimuth by trying to read
the Azimuth property; it will either get an answer or a "not implemented" error. However, a
client cannot tell whether a mount can slew to alt/az coordinates without calling the method
and possibly changing the mount’s position. This is why a CanSlewAltAz property is provided
for the SlewToAltAz() method.

5.1.3 Behavioural Rules

Heterogeneous distributed systems require both common standardized APIs and a set of
behavioural rules that must be obeyed by all modules in the system. The implementation of a module
is where these rules are effected, they do not appear in the abstract API definitions themselves.
These behavioural rules are already implemented by ASCOM COM drivers.

ASCOM's modular rules are:

• Do it right or report an error: Fetching or changing a property, or calling a method, must

always result in one of two outcomes: The request must complete successfully, or an error
must be signalled, preferably with some (human readable) indication of why the request
could not be satisfied. An example of violating this rule would be a method call to move a
rotator to a given mechanical angle, but the rotator ends up at some other angle and no
error is reported to the caller.
• Retries prohibited: No module must ever depend on another to provide timeouts or retry
logic. If a device needs check-and-retry logic in its routine operation, that logic must be
contained within the module itself. If there's a problem and your module’s own retry logic
can’t resolve the issue report the error as required above.
• Independence of operations: To the extent possible with the device, each API operation
should be independent of the others. For example, don’t impose a specific call order such as
needing to fetch the positional right ascension of a mount immediately before fetching the
declination.
• Timing Independence: To the extent possible with the device, modules must not place
timing constraints on properties and methods. Implement asynchronous calls wherever
possible in order not to lock up clients unnecessarily.
• Self-Protection – Over Use: Drivers must protect themselves and the instrument from
excessive rates of incoming requests from clients. Of course, clients should minimize the
need for calling across the internet to avoid flooding, but responsibility for protecting a
device from excessive request rates rests with the device and its driver.
• Self-Protection – Illegal/hazardous operations: Drivers and instruments should protect
themselves from illegal or hazardous operations. E.g. a dome may be opening but receives a
request to close the shutter. If the shutter can be safely reversed while opening, the driver
could simply close the shutter and report success. Alternatively, the driver may permit the
shutter to fully open and return an illegal operation error response to the close command.
• No Status Inconsistencies: In the example above, the driver ShutterStatus property must
accurately reflect the physical shutter condition at all times. If it reports ShutterOpen, even
for an instant, before the shutter starts to open, the client will assume that the shutter is
properly open and move on to its next task, even though the shutter is still opening.

API Reference - Version 7 21 16th June 2022

6. Document Revision Log

Version Release Date Changes

1 9/2/19 Original release
2 6/4/20 1. Added a description of the Alpaca Discovery protocol
2. Improved the description of Alpaca devices in section 1.2, including
replacing references to the confusing “Alpaca Server” name with
“Alpaca Device”.
3. Added section on Alpaca API version number versus ASCOM device
InterfaceVersion
4. Added section on the Robustness Principle
5. Added section on Alpaca Management API
3 1. Revised HTTP status flow diagram in section 2.5 to reflect ability to
return HTTP 3XX redirects and HTTP 4XX rejections e.g. 403
insufficient access rights.
2. Restored text that was unintentionally deleted in version 2 and
recreated the table of contents.
3. Clarified that device numbers only have to be unique within a single
device type.
4. Added an example of a bad device number to the bad paths section.
4 23/7/21 1. Enlarged casing requirements section to include form parameters
and JSON response keys.
2. Corrected casing of example in section 2.8.6:
api/v1/Telescope/0/SiteElevation is now
api/v1/telescope/0/siteelevation
3. Section 2.5 Status Codes enlarged to explain the difference between
Alpaca transport issues and ASCOM interface behaviour.
5 5/4/22 1. Corrected the version number in the page footer to match the title
page.
6 3/5/22 1. Section 2.1.3 - Clarified that the Alpaca device number must start at
0 for each device type.
7 16/6/22 1. Aligned text in section 2.7 with the equivalent text in the online API
reference (https://ascom-standards.org/api/). This clarifies the
requirement that ClientTransactionId, ServerTransactionId,
ErrorNumber and ErrorText fields must be included in all Alpaca
device JSON responses.
2. Corrected grammar in several paragraphs including the status code
paragraph in section 2.5.

API Reference - Version 7 22 16th June 2022