Upsource API overview

Upsource API is an RPC-style HTTP API. You can make calls using HTTP GET and POST. All data is sent and received as JSON. While the RPC methods don't enforce the use of a specific HTTP method, we recommend that you conform to HTTP semantics by using GET for retrieving data (e.g. getRevisionsList) and POST for modifying data (e.g. createReview).

All timestamps are Unix timestamps, the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT).

To invoke a method of the Upsource API using HTTP GET, make the following request:

http://your-upsource-host/~rpc/methodName?params={JSON-encoded-params}

To make a POST request, use the same URL but pass the request payload in the POST body instead. A Content-Type of application/json should be set.

Authorization

If no credentials are provided, the request will be executed with guest permissions.

To make a request on behalf of a specific user, send the Authorization header along with your request:

Authorization: Basic login:password

Substitute login:password with the actual credentials, encoded in Base64.

Example

To get the latest revisions in MyProject project, perform the following request:


URL: http://your-upsource-host/~rpc/getRevisionsList
POST body: {"projectId":"MyProject", "limit":30}

Raw request:


POST /~rpc/getRevisionsList HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=
Host: your-upsource-host
Connection: close
Content-Length: XXX

{"projectId":"MyProject", "limit":30}

Example of an error response:


HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: XXX
Connection: close
Date: Fri, 24 Apr 2015 11:09:20 GMT
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
X-Upsource-Server: your-upsource-host

{
  "error": {
    "code": 103,
    "message": "User guest doesn't have read access to project MyProject"
  }
}

Errors are usually transient and therefore are returned with no-cache headers.

Example of a success response:


HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: XXX
Connection: close
Date: Fri, 24 Apr 2015 10:55:08 GMT
Cache-Control: public, must-revalidate
ETag: aa1ce9f680e31b8b
X-Upsource-Server: your-upsource-host

{
  "result": {
    "revision": [{
      "revisionId": "cea8888e1b9eff4c9887a1fe8bdcee59898e7f43",
      "revisionDate": 1429718289000,
      "effectiveRevisionDate": 1429718289000,
      "revisionCommitMessage": "#DSH-325 extract directives describes to top level\n",
      "state": 3,
      "revisionIdShort": "cea8888",
      "authorId": "~John Doe <john.doe@mycompany.com>",
      "parentRevisions": ["b9b0ee4fb570d7457ac1cf2631d3bd4fc164017c"],
      "childRevisions": ["7c8bf9e7b9ab8e240d489fa59f6c79bfb1409de9"]
    }
    ...],
    "headHash": "57c491029f0f89b9"
  }
}

Most success responses contain a ETag which allows a client to make conditional requests.

API Reference

See the complete reference.

Webhooks

Webhooks allow you to notify external services, such as an issue tracker, a CI server, or a deployment tool, about events that occur in an Upsource project. Webhooks are a way to push notifications to external services which is usually preferable to polling. When an event occurs inside Upsource we'll send a JSON payload to specified URLs using HTTP POST. The following events are available:

When configuring a webhook, you can choose which events you would like to receive payloads for, or you can opt-in to receive all events in a project. Each event type has a specific payload format with the relevant event information. To see a full list of events and corresponding payloads, check out the documentation page.

Example of a webhook request sent by Upsource:


      POST /my-webhook HTTP/1.1
      Host: example.com
      Content-Type: application/json; charset=UTF-8
      Content-Length: XXX
      Connection: close
      User-Agent: Jakarta Commons-HttpClient/3.1
      X-Request-Id: c8a5b163-508f-42b5-939a-e11b02caf72e

      {
        "majorVersion": 3,
        "minorVersion": 0,
        "projectId": "demo-project",
        "dataType": "NewRevisionEventBean",
        "data": {
          "revisionId": "c1f4de8e6c5aca9b5615fa6656e1f26e4f26d0d0",
          "branches": [
            "master"
          ],
          "author": "John Doe <john.doe@mycompany.com>",
          "message": "#DSH-325 extract directives describes to top level\n",
          "date": 1454432013000
        }
      }

projectId and dataType properties describe the payload, data property contains the actual event-specific payload.

VCS Settings

Certain methods (createProject, editProject, loadProject, testVcsConnection) include a field named vcsSettings, whose value is a JSON-encoded string of VCS configuration parameters.

Generic example:


      {
          "mappings": [{
              "id": "id", // ID of the first repository is "id", IDs of other repositories are arbitrary alphanumeric strings
              "vcs": "git", // VCS type ID, one of "git", mercurial", "perforce", "svn"
              "url": "url", // VCS repository URL

              // VCS credentials, either "username" and "password" or "key" and "key-passphrase"
              "username": "username",
              "password": "password",

              "key": "key",
              "key-passphrase": "key-passphrase"
          }]
      }

Example of a multi-repository project:


      {
          "mappings": [{
              "id": "id",
              "vcs": "git",
              "url": "https://github.com/user/project.git"
          }, {
              "id": "another-repo",
              "vcs": "git",
              "url": "https://github.com/user/another-repo.git",
              "mapping": "another-repo"
          }]
      }

Example of a GitHub-connected project:


      {
          "mappings": [{
              "id": "id",
              "vcs": "git",
              "url": "https://github.com/user/project.git",
              "pull-requests": "github", // Optional, enables "Import pull requests as branches"
              "sync-comments": "github", // Optional, enables "Synchronize comments and pull requests"
              "sync-token": "sync-token" // OAuth token
          }]
      }