Skip to main content

🧪 Tramline API

Tramline currently exposes 3 API endpoints to fetch release information and to send custom build metadata. Before you start, you need your API credentials to make requests. To get these click on Organization Settings in the top navbar:

Under the Settings tab, inside the API section, you will find the Account ID and the API key that will be used later for all API calls.

info

Only a user with owner or developer privileges can view these API settings.

Get the latest release made to the store for an app​

Request​

curl -H "Authorization: Bearer your-api-key" \
     -H "X-TRAMLINE-ACCOUNT-ID: your-account-id" \
     -H "Accept: application/json" \
     https://tramline.dev/api/v1/apps/<app-id>

Response​

This API would respond with a format like this:

{
  "latest": {
    "ios": {
      "build_version": "8.0.0",
      "build_number": "471279587",
      "updated_at": "2023-07-04T06:50:46.180Z",
      "platform": "ios",
      "rollout_percentage": 48.15
    },
    "android": {
      "build_version": "10.18.1",
      "build_number": "471280026",
      "updated_at": "2023-09-14T09:55:02.743Z",
      "platform": "android",
      "rollout_percentage": 16.23
    }
  }
}

You can use jq to parse parts for this response on your CI (or CLI) as follows:

jq '.latest.android.build_version'

...to get the latest build version for Android.

Get all release versions sent to the store for a given release​

Request​

You can either specify a particular branch

curl -H "Authorization: Bearer your-api-key" \
     -H "X-TRAMLINE-ACCOUNT-ID: your-account-id" \
     -H "Accept: application/json" \
     https://tramline.dev/api/v1/releases/<release-branch-name>

...or you can just use the release ID directly.

curl -H "Authorization: Bearer your-api-key" \
     -H "X-TRAMLINE-ACCOUNT-ID: your-account-id" \
     -H "Accept: application/json" \
     https://tramline.dev/api/v1/releases/<release-id>

Response​

This API would respond with a format like this:

{
  "releases": {
    "android": [
      {
        "build_version": "8.0.0",
        "build_number": "471279578",
        "updated_at": "2023-07-03T17:19:49.428Z",
        "platform": "android",
        "rollout_percentage": 48.15
      },
      {
        "build_version": "8.0.2",
        "build_number": "471279585",
        "updated_at": "2023-07-03T18:40:58.189Z",
        "platform": "android",
        "rollout_percentage": 16.23
      }
    ],
    "ios": [
      {
        "build_version": "8.0.0",
        "build_number": "471279587",
        "updated_at": "2023-07-04T06:50:46.180Z",
        "platform": "ios",
        "rollout_percentage": 42.48
      }
    ]
  }
}

You can use jq to parse parts for this response on your CI (or CLI) as follows:

jq '.releases.android | map(.build_version)'

...to get all the builds generated for Android during the release.

Send custom metadata for a build​

Request​

You can send custom metadata to be displayed on Tramline dashboard about your build. Each metadata should have a unique identifier, and its value can be numerical or textual. The trend of all numeric metadata will be shown on Tramline dashboard.

Examples of metadata: app launch time, unit test coverage etc.

For a valid build, identified by version-name and version-code, Tramline will create or update the custom build metadata.

curl -X PATCH \
     -H "Authorization: Bearer your-api-key" \
     -H "X-TRAMLINE-ACCOUNT-ID: your-account-id" \
     -H "Content-Type: application/json" \
     -d '{
        "external_metadata": [
            {
                "identifier": "app_launch_time",
                "name": "App Launch Time",
                "description": "This is the time in seconds for the app to start",
                "value": 0.6,
                "type": "number",
                "unit": "seconds"
            }
        ]
    }' \
     https://tramline.dev/api/v1/apps/<app-id>/builds/<version-name>/<version-code>/external_metadata

The external_metadata in the request body should adhere to the following schema:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "identifier": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "value": {
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          }
        ]
      },
      "type": {
        "type": "string",
        "enum": [
          "number",
          "string"
        ]
      },
      "unit": {
        "type": "string"
      }
    },
    "required": [
      "identifier",
      "value",
      "type"
    ]
  }
}

Sample request body:

{
    "external_metadata": [
        {
            "identifier": "app_launch_time",
            "name": "App Launch Time",
            "description": "This is the time in seconds for the app to start",
            "value": 0.7,
            "type": "number",
            "unit": "seconds"
        },
        {
            "identifier": "unit_test_coverage",
            "name": "Unit Test Coverage",
            "description": "Percentage of code covered by unit tests",
            "value": 65,
            "type": "number",
            "unit": "percentage"
        },
        {
            "identifier": "end_to_end_test_report",
            "name": "End to end test report",
            "description": "End to end test report",
            "value": "The end to end tests ran for 15 minutes and passed",
            "type": "string",
            "unit": "none"
        }
    ]
}

Response​

If the schema is valid and the request is successful, the response will be a 200 OK.