Ship.io apiShip.io API


Authentication

To authenticate with Ship.io you must send your API token in the 'Authentication' header of your request.

curl -H 'Authorization: Bearer ddo32q1gw68ht5vbov8ykhaeb21gv2s66' \
     https://ship.io/jobs.json

Versioning

As we improve and make changes to the Ship.io API, we will release new versions. To protect your application from potentially breaking changes in future versions we strongly recommend specifying a specific version number in your API calls.

You can specify which version of the the Ship.io API you are using via the "Accept" header. Version information is sent in the format "application/vnd.shipio.v{version_number}". For example, the current version is 'application/vnd.shipio.v1'

curl -H 'Accept: application/vnd.shipio.v1' \
     -H 'Authorization: Bearer ddo32q1gw68ht5vbov8ykhaeb21gv2s66' \
     https://ship.io/jobs.json

Build Notifications

The Ship.io API is integrated with Pusher, allowing us to send real time job updates via web sockets. The following API operations can be used to subscribe to a Pusher channel and receive notifications whenever a build is queued, starts running or finishes.

Notification Channel

GET https://ship.io/user/channel.json

Description

This operation is used to retrieve the Key and Channel Name for connecting to the user's notification channel (via Pusher). This allows the client to subscribe to build notification events in real time. Learn more about Pusher channels here.

Response

{
	"pusher_key" : "s8tw5b",
	"name" : "private-user-fg7q1sj"
}

Channel Auth

POST https://ship.io/user/channel/auth

Description

This operation is used for authenticating Notification channels with Pusher. This is always used in combination with a Pusher client and is not called directly.

Notification Payload

Description

Build state changes are communicated via events named "build-state-changed". The payload includes information about both the Job and the Build.

Example

{
	"build":{
		"id":"68m7e9ag4",
		"build_number":1,
		"commit_sha":"ec458234eaa46662b1c43d572188a7be1d2cb203",
		"state":"succeeded",
		"successful":true
	},
	"job":{
		"id":"4fdaqe5xtid5oxnyq",
		"name":"my_ios_app",
		"repository":{
			"name":"my_ios_app",
			"selected_branch":"master",
			"html_url":"https://github.com/mygithubuser/my_ios_app",
			"clone_url":"https://github.com/mygithubuser/my_ios_app"
		}
	}
}

Notification Example

This example uses the Pusher Javascript client.
function subscribeToPusherChannel(key, channelName, token, callback) {
    Pusher.channel_auth_endpoint = 'https://ship.io/user/channel/auth';
    var pusher = new Pusher(key, {
        auth: {
            headers: {
                'X-CSRF-Token': $('meta[name="csrf-token"]').attr('content'),
                'Authorization': "Bearer " + token
            }
        }
    });

    var channel = pusher.subscribe(channelName);
    channel.bind('build-state-changed', callback);
}

function register(token, callback) {
    $.ajax({
      url: "https://ship.io/user/channel.json",
      type: 'GET',
      dataType: 'json',
      beforeSend: function(xhr){xhr.setRequestHeader('Authorization', 'Bearer ' + token);},
      success: function (result) {
        subscribeToPusherChannel(result["pusher_key"], result["name"], token, callback);
      }
    });
}

register("ddo32q1gw68ht5vbov8ykhaeb21gv2s66", function(data) {
	alert("Build is " + data["build"]["state"]);
});

Jobs

GET https://ship.io/jobs.json

Description

This operation will return a list of all jobs belonging to the authenticated user.

Response

[
	{
		"id":"4fdaqe5xtid5oxnyq",
		"name":"my_ios_app",
		"repository":{
			"name":"my_ios_app",
			"selected_branch":"master",
			"html_url":"https://github.com/mygithubuser/my_ios_app",
			"clone_url":"https://github.com/mygithubuser/my_ios_app"
		}
	}
]

Builds

This operation is used to retrieve the Key and Channel Name for connecting to the user's notification channel (via Pusher). This allows the client to subscribe to build notification events in real time. Learn more about Pusher channels here.

List Builds

GET https://ship.io/jobs/:job_id/builds.json

Description

This operation will return a list of all builds for the specified job.

Response

[
	{
		"id":"68m7e9ag4",
		"build_number":1,
		"commit_sha":"ec458234eaa46662b1c43d572188a7be1d2cb203",
		"state":"FINISHED",
		"successful":true,
		"artifacts":[
			{
				"id":"53vhqab8c",
				"name":"my_ios_app.ipa",
				"download_url":"https://ship.io/..."
			}
		]
	}
]

Get Build

GET https://ship.io/jobs/:job_id/builds/:build_id.json

Description

This operation will return a single build specified by id.

Response

{
	"id":"68m7e9ag4",
	"build_number":1,
	"commit_sha":"ec458234eaa46662b1c43d572188a7be1d2cb203",
	"state":"FINISHED",
	"successful":true,
	"artifacts":[
		{
			"id":"53vhqab8c",
			"name":"my_ios_app.ipa",
			"download_url":"https://ship.io/..."
		}
	]
}

Start Build

POST https://ship.io/jobs/:job_id/builds.json

Description

This operation will start a new build for the specified job.
{
	"id":"w7g2gj35c",
	"build_number":2,
	"commit_sha":null,
	"state":"QUEUED",
	"successful":false,
	"artifacts":[]
}

Stop Builds

POST https://ship.io/jobs/:job_id/stop_builds.json

Description

This operation will stop all currently running builds for the specified job.
[
	{
		"id":"7hcg5dxw1",
		"build_number":9,
		"commit_sha":null,
		"state":"FINISHED",
		"successful":false,
		"artifacts":[]
	}
]

Errors

Status Codes

  • 400 - Bad Request
  • 401 - Authentication Failed or Resource Not Authorized
  • 404 - Resource Not Found
  • 500 - Unexpected Error
{ "message" : "Resource Not Found" }