Repository Resource

Readable attributes

id	integer	Unique ID.
account_id	integer	ID of the associated account.
title	string	Human-readable name.
description	string	Any additional information you want to attach to a repository. For your information only, not used by the app.
name	string	File-system name.
color_label	string	Name of the specified color label. See a list of available labels below.
default_branch	string	Branch that is used by default when creating a new clone. Git only.
type	string	Type of the repository. See a list of available types below.
vcs	string	Name of a version control system the repoistory is using. See a list of available types below.
repository_url	string	A URL that can be used to checkout or clone the repository.
last_commit_at	datetime	Time of the last commit.
public_key	string	Repository-wide deployment key. Add this key to your server to make all ReleaseServers from this repository to be able to deploy to it.
updated_at	datetime	Time when the repository was last updated.
created_at	datetime	Time when the repository was first added to the system.

Writable attributes

title	string	Required on create.
description	string	Always optional.
name	string	Required on create. Only writable on create and rename. Must be unique in account.
color_label	string	White by default. See list of available labels below.
default_branch	string	Git only. “master” by default.
type_id	string	Type of repository. See a list of available types below.
create_structure	boolean	Subversion only. Determines if you want to create “trunk”, “branches” and “tags” directories in your new repository. If `true`, Beanstalk will create those directories for you.

Available repository types

The type_id attribute accepts one of the following values:

subversion
git

type_id is a write-only attribute, you will never receive it when fetching a repository. Instead there will be a vcs attribute that will contain the same value.

In addition there’s a read-only attribute called type that will contain a repository class name. One of the following:

SubversionRepository
GitRepository

Available color labels

label-white
label-pink
label-red
label-red-orange
label-orange
label-yellow
label-yellow-green
label-aqua-green
label-green
label-green-blue
label-sky-blue
label-light-blue
label-blue
label-orchid
label-violet
label-brown
label-black
label-grey

Find All Repositories

This method support optional pagination that is disabled by default. Simply pass the page parameter to turn it on.

Optional GET parameters:

page (integer) — page number for pagination;
per_page (integer) — number of elements per page (default 30, maximum 50).

json http-request

GET /api/repositories.json

Click to expand…

json http-response

[
  {
    "repository": {
      "name": "beanstalk",
      "created_at": "2011/09/23 11:53:46 +0800",
      "title": "beanstalk",
      "storage_used_bytes": 0,
      "default_branch": "master",
      "updated_at": "2011/09/23 11:53:46 +0800",
      "color_label": "label-white",
      "account_id": 2,
      "id": 13,
      "type": "GitRepository",
      "last_commit_at": null,
      "vcs": "git",
      "repository_url": "git@account.beanstalkapp.com:/beanstalk.git",
      "public_key": "ssh-rsa ..."
    }
  }
]

xml http-request

GET /api/repositories.xml

Click to expand…

xml http-response

<?xml version="1.0" encoding="UTF-8"?>
<repositories type="array">
  <repository>
    <account-id type="integer">9247</account-id>
    <anonymous type="boolean">false</anonymous>
    <color-label>label-blue</color-label>
    <created-at type="datetime">
      2007-06-14T22:15:37Z
    </created-at>
    <id type="integer">82346</id>
    <type>SubversionRepository</id>
    <last-commit-at type="datetime">
      2009-11-18T13:21:24Z
    </last-commit-at>
    <name>ProjectAlpha</name>
    <revision type="integer">36</revision>
    <storage-used-bytes type="integer">
      151130112
    </storage-used-bytes>
    <title>Beanstalk</title>
    <updated-at type="datetime">
      2009-11-18T13:21:42Z
    </updated-at>
    <repository-url>https://account.svn.beanstalkapp.com/ProjectAlpha</repository-url>
    <public-key>ssh-rsa ...</public-key>
  </repository>

  <repository>
    <account-id type="integer">7334</account-id>
    <anonymous type="boolean">false</anonymous>
    <color-label>label-</color-label>
    <created-at type="datetime">
      2007-07-23T06:59:15Z
    </created-at>
    <id type="integer">63722</id>
    <type>SubversionRepository</id>
    <last-commit-at type="datetime">
      2007-07-23T08:11:13Z
    </last-commit-at>
    <name>mt</name>
    <revision type="integer">2</revision>
    <storage-used-bytes type="integer">
      180224
    </storage-used-bytes>
    <title>Super Repository</title>
    <updated-at type="datetime">
      2009-08-10T06:05:39Z
    </updated-at>
    <repository-url>https://account.svn.beanstalkapp.com/mt</repository-url>
    <public-key>ssh-rsa ...</public-key>
  </repository>
</repositories>

Find Repository

json http-request

GET /api/repositories/{REPOSITORY_ID}.json

Click to expand…

json http-response

{
  "repository": {
    "name": "beanstalk",
    "created_at": "2011/09/23 11:53:46 +0800",
    "title": "beanstalk",
    "storage_used_bytes": 0,
    "default_branch": "master",
    "updated_at": "2011/09/23 11:53:46 +0800",
    "color_label": "label-white",
    "account_id": 2,
    "id": 13,
    "type": "GitRepository",
    "last_commit_at": null,
    "vcs": "git",
    "repository_url": "git@account.beanstalkapp.com:/beanstalk.git",
    "public_key": "ssh-rsa ..."
  }
}

xml http-request

GET /api/repositories/{REPOSITORY_ID}.xml

Click to expand…

xml http-response

<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <account-id type="integer">9247</account-id>
  <anonymous type="boolean">false</anonymous>
  <color-label>label-blue</color-label>
  <created-at type="datetime">
    2007-06-14T22:15:37Z
  </created-at>
  <id type="integer">82346</id>
  <type>SubversionRepository</id>
  <last-commit-at type="datetime">
    2009-11-18T13:21:24Z
  </last-commit-at>
  <name>ProjectAlpha</name>
  <revision type="integer">36</revision>
  <storage-used-bytes type="integer">
    151130112
  </storage-used-bytes>
  <title>Beanstalk</title>
  <updated-at type="datetime">
    2009-11-18T13:21:42Z
  </updated-at>
  <repository-url>https://account.svn.beanstalkapp.com/ProjectAlpha</repository-url>
  <public-key>ssh-rsa ...</public-key>
</repository>

Find Branches

Returns an array of repository’s branches. For Subversion always returns an empty array.

json http-request

GET /api/repositories/{REPOSITORY_ID}/branches.json

Click to expand…

json http-response

[
  {"branch": "master"},
  {"branch": "new-feature"}
]

xml http-request

GET /api/repositories/{REPOSITORY_ID}/branches.xml

Click to expand…

xml http-response

<?xml version="1.0" encoding="UTF-8"?>
<branches>
  <branch>master</branch>
  <branch>new-feature</branch>
</branches>

Find Tags

Returns an array of repository’s tags. For Subversion always returns an empty array.

json http-request

GET /api/repositories/{REPOSITORY_ID}/tags.json

Click to expand…

json http-response

[
  {"tag": "0.9"},
  {"tag": "1.0"},
  {"tag": "1.1"}
]

xml http-request

GET /api/repositories/{REPOSITORY_ID}/tags.xml

Click to expand…

xml http-response

<?xml version="1.0" encoding="UTF-8"?>
<tags>
  <tag>0.9</tag>
  <tag>1.0</tag>
  <tag>1.1</tag>
</tags>

Create Repository

Admin privileges required for this API method.

See a list of writable attributes at the top of the page.

json http-request

POST /api/repositories.json
{
  "repository": {
    "type_id": "git",
    "name": "project-beta",
    "title": "Project Beta",
    "color_label": "label-blue"
  }
}

Click to expand…

json http-response

{
  "repository": {
    "name": "project-beta",
    "created_at": "2011/09/23 11:53:46 +0800",
    "title": "Project Beta",
    "storage_used_bytes": 0,
    "updated_at": "2011/09/23 11:53:46 +0800",
    "color_label": "label-blue",
    "account_id": 2,
    "id": 13,
    "type": "GitRepository",
    "last_commit_at": null,
    "vcs": "git",
    "repository_url": "git@account.beanstalkapp.com:/project-beta",
    "public_key": "ssh-rsa ..."
  }
}

xml http-request

POST /api/repositories.xml
<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <name>shiny_new_repo</name>
  <title>Bubblegum</title>
  <color_label>label-pink</color_label>
</repository>

Click to expand…

xml http-response

<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <account-id type="integer">9247</account-id>
  <anonymous type="boolean">false</anonymous>
  <color-label>label-pink</color-label>
  <created-at type="datetime">
    2007-06-14T22:15:37Z
  </created-at>
  <id type="integer">82346</id>
  <type>SubversionRepository</id>
  <last-commit-at type="datetime">
    2009-11-18T13:21:24Z
  </last-commit-at>
  <name>ProjectAlpha</name>
  <revision type="integer">36</revision>
  <storage-used-bytes type="integer">
    151130112
  </storage-used-bytes>
  <title>Beanstalk</title>
  <updated-at type="datetime">
    2009-11-18T13:21:42Z
  </updated-at>
  <repository-url>https://account.svn.beanstalkapp.com/ProjectAlpha</repository-url>
  <public-key>ssh-rsa ...</public-key>
</repository>

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Name can't be blank</error>
</errors>

Update Repository

Admin privileges required for this API method.

See a list of writable attributes at the top of the page. You only need to pass the attributes that you want to change.

json http-request

PUT /api/repositories/{REPOSITORY_ID}.json
{
  "repository": {
    "title": "New Project"
  }
}

Click to expand…

json http-response

{
  "repository": {
    "name": "project-beta",
    "created_at": "2011/09/23 11:53:46 +0800",
    "title": "New Project",
    "storage_used_bytes": 0,
    "updated_at": "2011/09/23 11:53:46 +0800",
    "color_label": "label-white",
    "account_id": 2,
    "id": 13,
    "type": "GitRepository",
    "last_commit_at": null,
    "vcs": "git",
    "repository_url": "git@account.beanstalkapp.com:/project-beta",
    "public_key": "ssh-rsa ..."
  }
}

xml http-request

PUT /api/repositories/{REPOSITORY_ID}.xml
<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <name>bahroma_tunec</name>
  <title>bla</title>
  <color_label>label-red</color_label>
</repository>

Click to expand…

xml http-response

HEAD 200 OK

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Name can't be blank</error>
</errors>

Rename Repository

Admin privileges required for this API method.

json http-request

PUT /api/repositories/{REPOSITORY_ID}/rename.json
{
  "repository": {
    "name": "new-project"
  }
}

Click to expand…

json http-response

{
  "repository": {
    "name": "new-project",
    "created_at": "2011/09/23 11:53:46 +0800",
    "title": "Project Beta",
    "storage_used_bytes": 2621440,
    "updated_at": "2014/05/15 10:23:45 +0800",
    "color_label": "label-white",
    "account_id": 2,
    "id": 13,
    "type": "GitRepository",
    "last_commit_at": "2014/05/14 11:53:46 +0800",
    "vcs": "git",
    "repository_url": "git@account.beanstalkapp.com:/new-project",
    "public_key": "ssh-rsa ..."
  }
}
--OR IF INVALID--

{
  "errors": ["Error message"]
}

xml http-request

PUT /api/repositories/{REPOSITORY_ID}/rename.xml
<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <name>new-project</name>
</repository>

Click to expand…

xml http-response

<?xml version="1.0" encoding="UTF-8"?>
<repository>
  <account-id type="integer">2</account-id>
  <color-label>label-white</color-label>
  <created-at type="datetime">
    2007-06-14T22:15:37Z
  </created-at>
  <id type="integer">13</id>
  <type>GitRepository</id>
  <last-commit-at type="datetime">
    2014-05-14T13:21:24Z
  </last-commit-at>
  <name>new-project</name>
  <revision type="integer">36</revision>
  <storage-used-bytes type="integer">
    2621440
  </storage-used-bytes>
  <title>Project Beta</title>
  <updated-at type="datetime">
    2014-05-15T13:21:42Z
  </updated-at>
  <repository-url>git@account.beanstalkapp.com:/new-project</repository-url>
  <public-key>ssh-rsa ...</public-key>
  <vcs>git</vcs>
</repository>

--OR IF INVALID--

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Name can't be blank</error>
</errors>

Delete Repository

Account owner privileges required for this API method.

This method submits a request for repository deletion. If request was successfully submitted HTTP 202 will be returned with no response body. If previously submitted request is still in progress HTTP 304 will be returned with no response body. It is safe to call this method more than once as Beanstalk will make sure that only one request can be submitted.

Repository deletion requests can take several seconds to finish for smaller repositories and hours for extremely big repos.

json http-request

DELETE /api/repositories/{REPOSITORY_ID}.json

Click to expand…

json http-response

HEAD 202 OR HEAD 304

xml http-request

DELETE /api/repositories/{REPOSITORY_ID}.xml

Click to expand…

xml http-response

HEAD 202 OR HEAD 304