skydeck

Authorization

An application using the Skydeck API must use the OAuth protocol version 1.0 to request authorization from a user to access the user’s account.

The OAuth endpoints are

    https://api.skydeck.com/api/oauth/request_token
    https://skydeck.com/oauth/authorize
    https://api.skydeck.com/api/oauth/access_token

All requests must be made over SSL, and the only supported signature method is PLAINTEXT. Both GET and POST requests are supported, and OAuth parameters may be passed in the Authorization header or as CGI arguments.

The application requests and is granted a set of capabilities which allow it to perform particular actions on the user’s account. The capabilities are

    Item_read
    Item_write_source
    Contact_read

To use an API call, the application must have been granted the capability for that call. The capabilities needed for each call are given below.

When calling the Request Token endpoint, you must pass in the capabilities your application needs as CGI arguments. For example (removing line breaks):

    https://api.skydeck.com/request_token?capability=Usage_read&capability=Usage_write

To use the API in a public application, you must register an OAuth consumer. Once you have a consumer key and secret, you must use the OAuth endpoints above to get a request token, have it authorized by the user, and exchange it for an access token, following the OAuth protocol specification.

To use the API on your own account, without registering an OAuth consumer, get a preauthorized access token. (By default this token has all the capabilities.) This access token is authorized against the Skydeck Developer consumer, whose consumer key and secret are (literally)

    skydeck_developer_key
    skydeck_developer_secret

For example, once you have gotten an access token access_token with secret access_token_secret, you can retrieve the usage on your account at the following URL (removing line breaks)

    https://api.skydeck.com/api/usage/get?oauth_consumer_key=skydeck_developer_key&oauth_token=access_token&
oauth_signature_method=PLAINTEXT&oauth_signature=skydeck_developer_secret%2526access_token_secret&oauth_timestamp=&
oauth_nonce=

General

Most API parameters are passed as CGI arguments. For calls which write some object, the written object is passed as a JSON object in the POST body, with Content-type:application/json.

Responses are always JSON objects. The type of the returned object is given with the following syntax:

number	built-in Javascript number type
string	built-in Javascript string type
date or date/time	date or date/time given Unix-style (seconds since 1/1/1970 00:00:00)
[ type, ... ]	Fixed-length Javascript array with elements of the given types
type array	Variable-length Javascript-array with elements of the given type
{ field : type, … }	Javascript object with the given fields/types
(type1, type2) map	Javascript object mapping fields of type1 to values of type2
type1 | type2	either type1 or type2
“String”	the literal string “String” (tags used to tell types apart)
name	a defined type with name name
type?	object of type or possibly null; without ? a type will never be null

All API calls take a version argument. If you don’t pass a version you get the current version of the API. The current version of the API is 0.2; it is recommended that you pass version=0.2.

All API calls take a style argument. If style=pretty then the resulting JSON will be pretty-printed; otherwise it will be minified.

All API calls take a callback argument. If callback=foo then the JSON response is returned wrapped in a call to foo; otherwise the JSON response is returned directly.

Call Log

Datatypes:

  item :=                       // returned by /api/item/get
  {
    id : number,
    kind : item_kind,
    direction : item_direction,
    lineNumber : string,        // number call was billed to
    remoteNumber : string,      // number of the other party on call
    contact : int?,             // ID of contact overriding remoteContact
    lineContact : int?,         // ID of contact with number lineNumber
    remoteContact : int?,       // ID of contact with number remoteNumber
    incurred : date/time,       // Date/time call happened
    tags : string array,        // Tags associated with call
    duration : int,             // Call duration in seconds
    charges : int,              // Call charges in cents
    note : string,
    message : string,           // text message contents, if supplied by the source
    in_inbox : bool,            // true if message is in inbox
    is_starred : bool,          // true if message is starred
    source : string,            // string identifying item source
    source_group : string,      // see in_source_item
    source_key : string         // see in_source_item
  }

  in_source_item :=             // passed to /api/item/add
  {
    id : number,                // not used, pass -1
    kind : item_kind;
    direction : item_direction;
    lineNumber : string;
    remoteNumber : string;
    incurred : float;
    duration : int;
    charges : int;
    message? : string;          // text message contents, "" if unavailable
    in_inbox? : bool;           // true if message is in inbox
    is_starred? : bool;         // true if message is starred
    source_group : string;      // string identifying a group of related items (e.g. a bill)
    source_key : string         // key for duplicate removal (item with preexisting key is not added)
  }

  item_kind := "Call" | "Sms" | "Missed" | "Voicemail"

  item_direction := "Incoming" | "Outgoing"

  order := "incurred" | "lineNumber" | "remoteNumber" | "duration" |
           "charges" | "direction" | "contact"

API calls:

URL	/api/item/get
Function	Returns items from user’s call log.
Capability	Item_read
Arguments
order?	order	Sort order
limit?	number	Limit number of items returned; the maximum items returned per call is 5000
query?	string	Match call log query as in application
Returns	item array
URL	/api/item/add
Function	Adds a list of items to user’s call log.
Capability	Item_write_source
POST body	in_source_item array

Address Book

Datatypes:

  contact :=                                          // returned by /api/contact/get
  {
    id : number,
    name : [ string, string, string, string, string ] // prefix, first, middle, last, suffix
    birthday : date?,
    notes : string,
    tags : string array,
    created : date/time,
    updated : date/time,
    emails : email array,
    ims : im array,
    phoneNumbers : phoneNumber array,
    postalAddresses : postalAddress array,
    organizations : organization array,
    is_hidden : bool                                  // flag whether contact is hidden
  }

  email :=
  {
    address : string,
    section : section
  }

  im :=
  {
    address : string,
    protocol : im_protocol,
    section : section
  }

  im_protocol := "AIM" | "GoogleTalk" | "ICQ" | "IRC" | "Jabber" | "MSN" | "Skype" | "Yahoo" | "Other"

  phone_number :=
  {
    number : string,
    kind : pn_kind,
    section : section
  }

  pn_kind := "Fax" | "Mobile" | "Pager" | "Text_msg" | "Voice"

  postal_address :=
  {
    address : string,
    section : section
  }

  organization :=
  {
    name : string,
    title : string,
    section : section
  }

  section := "Personal" | "Work" | "Other"

  order := "name" | "rank" | "volume" | "lastCall" | "balance"

API calls:

URL	/api/contact/get
Function	Returns contacts from user’s address book.
Capability	Contact_read
Arguments
order?	order	Sort order
limit?	number	Limit number of contacts returned
query?	string	Match address book query as in application
tag?	string	Match contacts with given tag
id?	number	Match contact with given id
phoneNumber?	string	Match contacts with given phone number
im?	string	Match contacts with given IM handle
email?	string	Match contacts with given email address
Returns	contact array