Marathon REST API

Apps

POST /v2/apps

Create and start a new application.

Here is an example of an application JSON which includes all fields.

{
    "id": "/product/service/myApp",
    "cmd": "env && sleep 300",
    "cpus": 1.5,
    "mem": 256.0,
    "portDefinitions": [
        { "port": 8080, "protocol": "tcp", "name": "http", labels: { "VIP_0": "10.0.0.1:80" } },
        { "port": 9000, "protocol": "tcp", "name": "admin" }
    ],
    "requirePorts": false,
    "instances": 3,
    "executor": "",
    "container": {
        "type": "DOCKER",
        "docker": {
            "image": "group/image",
            "network": "BRIDGE",
            "portMappings": [
                {
                    "containerPort": 8080,
                    "hostPort": 0,
                    "servicePort": 9000,
                    "protocol": "tcp"
                },
                {
                    "containerPort": 161,
                    "hostPort": 0,
                    "protocol": "udp"
                }
            ],
            "privileged": false,
            "parameters": [
                { "key": "a-docker-option", "value": "xxx" },
                { "key": "b-docker-option", "value": "yyy" }
            ]
        },
        "volumes": [
            {
                "containerPath": "/etc/a",
                "hostPath": "/var/data/a",
                "mode": "RO"
            },
            {
                "containerPath": "/etc/b",
                "hostPath": "/var/data/b",
                "mode": "RW"
            }
        ]
    },
    "env": {
        "LD_LIBRARY_PATH": "/usr/local/lib/myLib"
    },
    "constraints": [
        ["attribute", "OPERATOR", "value"]
    ],
    "acceptedResourceRoles": [ /* since 0.9.0 */
        "role1", "*"
    ],
    "labels": {
        "environment": "staging"
    },
    "fetch": [
        { "uri": "https://raw.github.com/mesosphere/marathon/master/README.md" },
        { "uri": "https://foo.com/archive.zip", "executable": false, "extract": true, "cache": true }
    ],
    "dependencies": ["/product/db/mongo", "/product/db", "../../db"],
    "healthChecks": [
        {
            "protocol": "HTTP",
            "path": "/health",
            "gracePeriodSeconds": 3,
            "intervalSeconds": 10,
            "portIndex": 0,
            "timeoutSeconds": 10,
            "maxConsecutiveFailures": 3
        },
        {
            "protocol": "HTTPS",
            "path": "/machinehealth",
            "gracePeriodSeconds": 3,
            "intervalSeconds": 10,
            "port": 3333,
            "timeoutSeconds": 10,
            "maxConsecutiveFailures": 3
        },
        {
            "protocol": "TCP",
            "gracePeriodSeconds": 3,
            "intervalSeconds": 5,
            "portIndex": 1,
            "timeoutSeconds": 5,
            "maxConsecutiveFailures": 3
        },
        {
            "protocol": "COMMAND",
            "command": { "value": "curl -f -X GET http://$HOST:$PORT0/health" },
            "maxConsecutiveFailures": 3
        }
    ],
    "backoffSeconds": 1,
    "backoffFactor": 1.15,
    "maxLaunchDelaySeconds": 3600,
    "taskKillGracePeriodSeconds": 2,
    "upgradeStrategy": {
        "minimumHealthCapacity": 0.5,
        "maximumOverCapacity": 0.2
    },
    "ipAddress": {
        "groups": [
            "backend"
        ],
        "labels": {
            "color":   "purple",
            "flavor":  "grape",
            "org":     "product",
            "service": "myApp",
            "tier":    "backend"
        },
        "networkName": "dev-network"
    }
}
id (String)

Unique identifier for the app consisting of a series of names separated by slashes. Each name must be at least 1 character and may only contain digits (0-9), dashes (-), dots (.), and lowercase letters (a-z). The name may not begin or end with a dash.

The allowable format is represented by the following regular expression ^(([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])\\.)*([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])$

cmd (String)

The command that is executed. This value is wrapped by Mesos via /bin/sh -c ${app.cmd}. Either cmd or args must be supplied. It is invalid to supply both cmd and args in the same app.

args (Array of Strings)

An array of strings that represents an alternative mode of specifying the command to run. This was motivated by safe usage of containerizer features like a custom Docker ENTRYPOINT. This args field may be used in place of cmd even when using the default command executor. This change mirrors API and semantics changes in the Mesos CommandInfo protobuf message starting with version 0.20.0. Either cmd or args must be supplied. It is invalid to supply both cmd and args in the same app.

cpus (Float)

The number of CPU`s this application needs per instance. This number does not have to be integer, but can be a fraction.

mem (Float)

The amount of memory in MB that is needed for the application per instance.

ports (Array of Integers)

Since v1.0.0: Deprecated . Use portDefinitions instead.

An array of required port resources on the host.

The port array currently serves multiple roles:

  • The number of items in the array determines how many dynamic ports are allocated for every task.
  • For every port that is zero, a globally unique (cluster-wide) port is assigned and provided as part of the app definition to be used in load balancing definitions. See Service Discovery Load Balancing doc page for details.

Since this is confusing, we recommend to configure ports assignment for Docker containers for BRIDGE and USER networking in container.docker.portMappings instead, see Docker Containers doc page).

Alternatively or if you use the Mesos Containerizer, pass zeros as port values to generate one or more arbitrary free ports for each application instance. Each port value is exposed to the instance via environment variables $PORT0, $PORT1, etc. Ports assigned to running instances are also available via the task resource.

We will probably provide an alternative way to configure this for non-Docker apps in the future as well, see Rethink ports API.

portsDefinitions (Array of Objects)

Since v1.0.0:

An array of required port resources on the host.

The portDefinitions array currently serves multiple roles:

  • The number of items in the array determines how many dynamic ports are allocated for every task.
  • For every port that is zero, a globally unique (cluster-wide) port is assigned and provided as part of the app definition to be used in load balancing definitions. See Service Discovery Load Balancing doc page for details.

Since this is confusing, we recommend to configure ports assignment for Docker containers for BRIDGE and USER networking in container.docker.portMappings instead, see Docker Containers doc page).

Alternatively or if you use the Mesos Containerizer, pass zeros as port values to generate one or more arbitrary free ports for each application instance.

Each port value is exposed to the instance via environment variables $PORT0, $PORT1, etc. Ports assigned to running instances are also available via the task resource.

We will probably provide an alternative way to configure this for non-Docker apps in the future as well, see Rethink ports API.

requirePorts (Boolean)

Normally, the host ports of your tasks are automatically assigned. This corresponds to the requirePorts value false which is the default.

If you need more control and want to specify your host ports in advance, you can set requirePorts to true. This way the ports you have specified are used as host ports. That also means that Marathon can schedule the associated tasks only on hosts that have the specified ports available.

instances (Integer)

The number of instances of this application to start. Please note: this number can be changed everytime as needed to scale the application.

executor (String)

The executor to use to launch this application. Different executors are available. The simplest one (and the default if none is given) is //cmd, which takes the cmd and executes that on the shell level.

container (Object)

Additional data passed to the containerizer on application launch. These consist of a type, zero or more volumes, and additional type-specific options. Volumes and type are optional (the default type is DOCKER). In order to make use of the docker containerizer, specify --containerizers=docker,mesos to the Mesos slave. For a discussion of docker-specific options, see the native docker document.

env (Object with String values)

Key value pairs that get added to the environment variables of the process to start.

constraints

Valid constraint operators are one of [“UNIQUE”, “CLUSTER”, “GROUP_BY”]. For additional information on using placement constraints see the Constraints doc page.

acceptedResourceRoles v0.9.0

Optional. A list of resource roles. Marathon considers only resource offers with roles in this list for launching tasks of this app. If you do not specify this, Marathon considers all resource offers with roles that have been configured by the --default_accepted_resource_roles command line flag. If no --default_accepted_resource_roles was given on startup, Marathon considers all resource offers.

Example 1: "acceptedResourceRoles": [ "production", "*" ] Tasks of this app definition are launched either on “production” or “*” resources.

Example 2: "acceptedResourceRoles": [ "public" ] Tasks of this app definition are launched only on “public” resources.

Background: Mesos can assign roles to certain resource shares. Frameworks which are not explicitly registered for a role do not see resources of that role. In this way, you can reserve resources for frameworks. Resources not reserved for custom role, are available for all frameworks. Mesos assigns the special role “*” to them.

To register Marathon for a role, you need to specify the --mesos_role command line flag on startup. If you want to assign all resources of a slave to a role, you can use the --default_role argument when starting up the slave. If you need a more fine-grained configuration, you can use the --resources argument to specify resource shares per role. The Mesos master needs to be started with --roles followed by a comma-separated list of all roles you want to use across your cluster. See the Mesos command line documentation for details.

Note: Mesos does not currently support multiple roles for a framework, which means that you cannot deploy apps to more than one role. An interim solution is to create one Marathon per role.

labels (Object of String values)

Attaching metadata to apps can be useful to expose additional information to other services, so we added the ability to place labels on apps (for example, you could label apps “staging” and “production” to mark services by their position in the pipeline).

fetch (Array of Objects)

Since v0.15.0: The list of URIs to fetch before the task starts. Example: { "uri": "http://get.me" } Example: { "uri": "https://foo.com/archive.zip", "executable": false, "extract": true, "cache": true } On every artifact you can define the following properties:

  • uri: URI to be fetched by Mesos fetcher module
  • executable: Set fetched artifact as executable
  • extract: Extract fetched artifact if supported by Mesos fetcher module
  • cache: Cache fetched artifact if supported by Mesos fetcher module

For documentation about the mesos fetcher cache, see here: http://mesos.apache.org/documentation/latest/fetcher/

uris (Array of Strings)

Since v0.15.0: Deprecated . Use fetch instead. URIs defined here are resolved, before the application gets started. If the application has external dependencies, they should be defined here.

dependencies (Array of Strings)

A list of services upon which this application depends. An order is derived from the dependencies for performing start/stop and upgrade of the application. For example, an application /a relies on the services /b which itself relies on /c. To start all 3 applications, first /c is started than /b than /a.

healthChecks

An array of checks to be performed on running tasks to determine if they are operating as expected. Health checks begin immediately upon task launch. By default, health checks are executed by the Marathon scheduler. In this case, the only supported protocol is COMMAND and each app is limited to at most one defined health check.

An HTTP health check is considered passing if (1) its HTTP response code is between 200 and 399, inclusive, and (2) its response is received within the timeoutSeconds period.

If a task fails more than maxConsecutiveFailures health checks consecutively, that task is killed causing Marathon to start more instances. These restarts are modulated like any other failing app by backoffSeconds, backoffFactor and maxLaunchDelaySeconds. The kill of the unhealthy task is signalled via unhealthy_task_kill_event event.

Health Check Options
  • command: Command to run in order to determine the health of a task.
  • gracePeriodSeconds (Optional. Default: 15): Health check failures are ignored within this number of seconds of the task being started or until the task becomes healthy for the first time.
  • intervalSeconds (Optional. Default: 10): Number of seconds to wait between health checks.
  • maxConsecutiveFailures(Optional. Default: 3) : Number of consecutive health check failures after which the unhealthy task should be killed.
  • protocol (Optional. Default: “HTTP”): Protocol of the requests to be performed. One of “HTTP”, “HTTPS”, “TCP”, or “Command”.
  • path (Optional. Default: “/”): Path to endpoint exposed by the task that will provide health status. Example: “/path/to/health”. Note: only used if protocol == "HTTP".
  • portIndex (Optional. Default: 0): Index in this app’s ports array to be used for health requests. An index is used so the app can use random ports, like “[0, 0, 0]” for example, and tasks could be started with port environment variables like $PORT1.
  • timeoutSeconds (Optional. Default: 20): Number of seconds after which a health check is considered a failure regardless of the response.
backoffSeconds, backoffFactor and maxLaunchDelaySeconds

Configures exponential backoff behavior when launching potentially sick apps. This prevents sandboxes associated with consecutively failing tasks from filling up the hard disk on Mesos slaves. The backoff period is multiplied by the factor for each consecutive failure until it reaches maxLaunchDelaySeconds. This applies also to tasks that are killed due to failing too many health checks.

taskKillGracePeriodSeconds (Optional.)

Configures the termination signal escalation behavior of executors when stopping tasks. Sets the number of seconds between the executor sending SIGTERM to a task it is about to stop and then finally sending SIGKILL to enforce the matter.

Using this grace period, tasks should perform orderly shutdown immediately upon receiving SIGTERM.

By default, there is no grace period in effect or at most a minimal one, at the discretion of the Mesos implementation in use.

upgradeStrategy

During an upgrade all instances of an application get replaced by a new version. The upgradeStrategy controls how Marathon stops old versions and launches new versions. It consists of two values:

  • minimumHealthCapacity (Optional. Default: 1.0) - a number between 0and 1 that is multiplied with the instance count. This is the minimum number of healthy nodes that do not sacrifice overall application purpose. Marathon will make sure, during the upgrade process, that at any point of time this number of healthy instances are up.
  • maximumOverCapacity (Optional. Default: 1.0) - a number between 0 and 1 which is multiplied with the instance count. This is the maximum number of additional instances launched at any point of time during the upgrade process.

The default minimumHealthCapacity is 1, which means no old instance can be stopped before another healthy new version is deployed. A value of 0.5 means that during an upgrade half of the old version instances are stopped first to make space for the new version. A value of 0 means take all instances down immediately and replace with the new application.

The default maximumOverCapacity is 1, which means that all old and new instances can co-exist during the upgrade process. A value of 0.1 means that during the upgrade process 10% more capacity than usual may be used for old and new instances. A value of 0.0 means that even during the upgrade process no more capacity may be used for the new instances than usual. Only when an old version is stopped, a new instance can be deployed.

If minimumHealthCapacity is 1 and maximumOverCapacity is 0, at least one additional new instance is launched in the beginning of the upgrade process. When it is healthy, one of the old instances is stopped. After it is stopped, another new instance is started, and so on.

A combination of minimumHealthCapacity equal to 0.9 and maximumOverCapacity equal to 0 results in a rolling update, replacing 10% of the instances at a time, keeping at least 90% of the app online at any point of time during the upgrade.

A combination of minimumHealthCapacity equal to 1.0 and maximumOverCapacity equal to 0.1 results in a rolling update, replacing 10% of the instances at a time and keeping at least 100% of the app online at any point of time during the upgrade with 10% of additional capacity.

ipAddress

ipAddress declares that your application will use IP-per-task networking.

  • groups (Optional) - A group is the name given to a set of logically-related interfaces that are allowed to communicate among themselves. Network traffic is allowed between two container interfaces that share at least one network group. For example, one might want to create separate groups for isolating dev, testing, qa and prod deployment environments.

  • labels (Optional) - To tag certain metadata to be used by Isolator/IPAM, e.g., rack, etc.

  • networkName (Optional) - Name of the network which will be used by Mesos to determine the network that the container joins. It is up to Mesos to decide how to interpret this field. If ipAddress is defined and its networkName is not then the value of networkName defaults to the value of the default_network_name command-line flag (if specified).

Example

Request:

POST /v2/apps HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Content-Length: 562
Content-Type: application/json; charset=utf-8
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

{
    "cmd": "env && python3 -m http.server $PORT0",
    "constraints": [
        [
            "hostname",
            "UNIQUE"
        ]
    ],
    "container": {
        "docker": {
            "image": "python:3"
        },
        "type": "DOCKER"
    },
    "cpus": 0.25,
    "healthChecks": [
        {
            "gracePeriodSeconds": 3,
            "intervalSeconds": 10,
            "maxConsecutiveFailures": 3,
            "path": "/",
            "portIndex": 0,
            "protocol": "HTTP",
            "timeoutSeconds": 5
        }
    ],
    "id": "my-app",
    "instances": 2,
    "mem": 50,
    "ports": [
        0
    ],
    "upgradeStrategy": {
        "minimumHealthCapacity": 0.5,
        "maximumOverCapacity": 0.5
    }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://mesos.vm:8080/v2/apps/my-app
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "args": null,
    "backoffFactor": 1.15,
    "backoffSeconds": 1,
    "maxLaunchDelaySeconds": 3600,
    "cmd": "env && python3 -m http.server $PORT0",
    "constraints": [
        [
            "hostname",
            "UNIQUE"
        ]
    ],
    "container": {
        "docker": {
            "image": "python:3"
        },
        "type": "DOCKER",
        "volumes": []
    },
    "cpus": 0.25,
    "dependencies": [],
    "deployments": [
        {
            "id": "f44fd4fc-4330-4600-a68b-99c7bd33014a"
        }
    ],
    "disk": 0.0,
    "env": {},
    "executor": "",
    "healthChecks": [
        {
            "command": null,
            "gracePeriodSeconds": 3,
            "intervalSeconds": 10,
            "maxConsecutiveFailures": 3,
            "path": "/",
            "portIndex": 0,
            "protocol": "HTTP",
            "timeoutSeconds": 5
        }
    ],
    "id": "/my-app",
    "instances": 2,
    "mem": 50.0,
    "portDefinitions": [
        {"port": 0}
    ],
    "requirePorts": false,
    "storeUrls": [],
    "upgradeStrategy": {
        "minimumHealthCapacity": 0.5,
        "maximumOverCapacity": 0.5
    },
    "uris": [],
    "user": null,
    "version": "2014-08-18T22:36:41.451Z"
}
Example (create an app with an already existing ID)

If the ID you are trying to create already exists, then the create operation fails.

Request:

POST /v2/apps HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Content-Type: application/json; charset=utf-8
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

{
    "id":"duplicated",
    "cmd":"sleep 100",
    "cpus":0.1,
    "mem":16,
    "instances":1
}

Response:

HTTP/1.1 409 Conflict
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "id":"duplicated",
    "message": "An app with id [/duplicated] already exists."
}

GET /v2/apps

List all running applications.

The list of running applications can be filtered by application identifier, command and label selector. All filters can be applied at the same time.

Parameters
Name Type Description
cmd string Filter apps to only those whose commands contain cmd. Default: "".
embed string Embeds nested resources that match the supplied path. You can specify this parameter multiple times with different values, e.g. "embed=apps.deployments&embed=apps.lastTaskFailure" Default: apps.counts. You are encouraged to specify "embed=apps.counts" explicitly if you rely on this information because we will change the default in a future release. Possible values:
  • "apps.tasks". Apps' tasks are not embedded in the response by default. This currently implies "apps.deployments" currently but that will change in a future version.
  • "apps.counts". Apps' task counts (tasksStaged, tasksRunning, tasksHealthy, tasksUnhealthy) are currently embedded by default but this will change in a future release.
  • "apps.deployments". This embeds the IDs of deployments related to this app into "deployments".
  • "apps.lastTaskFailure". This embeds the "lastTaskFailure" for every app if there is one.
  • "apps.failures". deprecated Apps' last failures are not embedded in the response by default. This implies "apps.lastTaskFailure", "apps.tasks", "apps.counts" and "apps.deployments".
  • "apps.taskStats". v0.11 This exposes some task statatistics in the JSON.
taskRunning (Integer)

Warning Future versions of Marathon will only deliver this information when you specify “embed=apps.counts” as a query parameter.

The number of tasks running for this application definition.

tasksStaged (Integer)

Warning Future versions of Marathon will only deliver this information when you specify “embed=apps.counts” as a query parameter.

The number of tasks staged to run.

tasksHealthy (Integer)

Warning Future versions of Marathon will only deliver this information when you specify “embed=apps.counts” as a query parameter.

The number of tasks which are healthy.

tasksUnhealthy (Integer)

Warning Future versions of Marathon will only deliver this information when you specify “embed=apps.counts” as a query parameter.

The number of tasks which are unhealthy.

deployments (Array of Objects)

Use the query parameter “embed=apps.deployments” to embed this information.

A list of currently running deployments that affect this application. If this array is nonempty, then this app is locked for updates.

The objects in the list only contain the id of the deployment, e.g.:

{
    "id": "44c4ed48-ee53-4e0f-82dc-4df8b2a69057"
}
taskStats (Object) v0.11

Provides task statistics. The “taskStats” object only gets embedded into the app JSON if you pass an embed=apps.taskStats query argument.

Task statistics are provided for the following groups of tasks. If no tasks for the group exist, no statistics are offered:

  • "withLatestConfig" contains statistics about all tasks that run with the same config as the latest app version.
  • "startedAfterLastScaling" contains statistics about all tasks that were started after the last scaling or restart operation.
  • "withOutdatedConfig" contains statistics about all tasks that were started before the last config change which was not simply a restart or scaling operation.
  • "totalSummary" contains statistics about all tasks.

Example JSON:

{
  // ...
  "taskStats": {
    {
      "startedAfterLastScaling" : {
        "stats" : {
          "counts" : { // equivalent to tasksStaged, tasksRunning, tasksHealthy, tasksUnhealthy
            "staged" : 1,
            "running" : 100,
            "healthy" : 90,
            "unhealthy" : 4
          },
          // "lifeTime" is only included if there are running tasks.
          "lifeTime" : { 
            // Measured from `"startedAt"` (timestamp of the Mesos TASK_RUNNING status update) of each running task 
            // until now.
            "averageSeconds" : 20.0,
            "medianSeconds" : 10.0
          }
        }
      },
      "withLatestConfig" : {
        "stats" : { /* ... same structure as above ... */ }
      },
      "withOutdatedConfig" : {
        "stats" : { /* ... same structure as above ... */ }
      },
      "totalSummary" : {
        "stats" : { /* ... same structure as above ... */ }
      }
    }
  }
  // ...
}

The calculation of these statistics is currently performed for every request and expensive if you have very many tasks.

lastTaskFailure (Object)

Information about the last task failure for debugging purposes.

This information only gets embedded if you specify the “embed=apps.lastTaskFailure” query parameter.

version

The version of the current app definition

versionInfo.lastConfigChangeAt (Timestamp as String)

"lastConfigChangeAt" contains the time stamp of the last change to this app which was not simply a scaling or a restarting configuration.

versionInfo.lastScalingAt (Timestamp as String)

"lastScalingAt" contains the time stamp of the last change including changes like scaling or restarting the app. Since our versions are time based, this is currently equal to "version".

Example

Request:

GET /v2/apps HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2


Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "apps": [
        {
            "id": "/product/us-east/service/myapp", 
            "cmd": "env && sleep 60", 
            "constraints": [
                [
                    "hostname", 
                    "UNIQUE", 
                    ""
                ]
            ], 
            "container": null, 
            "cpus": 0.1, 
            "env": {
                "LD_LIBRARY_PATH": "/usr/local/lib/myLib"
            }, 
            "executor": "", 
            "instances": 3, 
            "mem": 5.0, 
            "ports": [
                15092, 
                14566
            ], 
            "tasksRunning": 0, 
            "tasksStaged": 1, 
            "uris": [
                "https://raw.github.com/mesosphere/marathon/master/README.md"
            ], 
            "version": "2014-03-01T23:42:20.938Z"
        }
    ]
}

GET /v2/apps?cmd={command}

List all running applications, filtered by command. Note: the specified command must be contained in the applications command (substring).

Example

Request:

GET /v2/apps?cmd=sleep%2060 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2


Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "apps": [
        {
            "id": "/product/us-east/service/myapp", 
            "cmd": "env && sleep 60", 
            "constraints": [
                [
                    "hostname", 
                    "UNIQUE", 
                    ""
                ]
            ], 
            "container": null, 
            "cpus": 0.1, 
            "env": {
                "LD_LIBRARY_PATH": "/usr/local/lib/myLib"
            }, 
            "executor": "", 
            "instances": 3, 
            "mem": 5.0, 
            "ports": [
                15092, 
                14566
            ], 
            "tasksRunning": 1, 
            "tasksStaged": 0, 
            "uris": [
                "https://raw.github.com/mesosphere/marathon/master/README.md"
            ], 
            "version": "2014-03-01T23:42:20.938Z"
        }
    ]
}

GET /v2/apps?id={identifier}

List all running applications, filtered by id. Note: the specified id must be contained in the applications id (substring).

Example

Request:

GET /v2/apps?id=my HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2


Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "apps": [
        {
            "id": "/product/us-east/service/myapp", 
            "cmd": "env && sleep 60", 
            "constraints": [
                [
                    "hostname", 
                    "UNIQUE", 
                    ""
                ]
            ], 
            "container": null, 
            "cpus": 0.1, 
            "env": {
                "LD_LIBRARY_PATH": "/usr/local/lib/myLib"
            }, 
            "executor": "", 
            "instances": 3, 
            "mem": 5.0, 
            "ports": [
                15092, 
                14566
            ], 
            "tasksRunning": 1, 
            "tasksStaged": 0, 
            "uris": [
                "https://raw.github.com/mesosphere/marathon/master/README.md"
            ], 
            "version": "2014-03-01T23:42:20.938Z"
        }
    ]
}

GET /v2/apps?label={labelSelectorQuery}

List all running applications, filtered by labelSelectorQuery. This filter selects applications by application labels.

Label Selector Query

A label selector query contains one or more label selectors, which are comma separated. Marathon supports three types of selectors: existence-based, equality-based and set-based. In the case of multiple selectors, all must be satisfied so comma separator acts as an AND logical operator. Labels and values must consist of alphanumeric characters plus - _ and .: -A-Za-z0-9_.. Any other character is possible, but must be escaped with a backslash character.

Example: environment==production, tier!=frontend\ tier, deployed in (us, eu), deployed notin (aa, bb)

Existence based Selector Query

Matches the existence of a label.

  • label

Example:

  • environment
Equality based Selector Query

Matches existence of labels and the (non) equality of the value.

  • label == value
  • label != value

Example:

  • environment = production
  • tier != frontend
Set based Selector Query

Matches existence of labels and the (non) existence of the value in a given set.

  • label in ( value, value, … , value )
  • label notin ( value, value, … , value )

Example:

  • environment in (production, qa)
  • tier notin (frontend, backend)
Example

Request:

GET /v2/apps?label=foo%3d%3done%2c+bla!%3done%2c+foo+in+(one%2c+two%2c+three)%2c+bla+notin+(one%2c+two%2c+three)%2c+existence%22 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2


Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "apps": [
        {
            "id": "/product/us-east/service/myapp", 
            "cmd": "env && sleep 60", 
            "labels": {
                "foo": "one", 
                "bla": "four", 
                "existence": "yes"
            }, 
            "container": null, 
            "cpus": 0.1, 
            "env": {
                "LD_LIBRARY_PATH": "/usr/local/lib/myLib"
            }, 
            "executor": "", 
            "instances": 3, 
            "mem": 5.0, 
            "ports": [
                15092, 
                14566
            ], 
            "tasksRunning": 1, 
            "tasksStaged": 0, 
            "uris": [
                "https://raw.github.com/mesosphere/marathon/master/README.md"
            ], 
            "version": "2014-03-01T23:42:20.938Z"
        }
    ]
}

GET /v2/apps/product/us-east/*

List all running applications, which live in the namespace /product/us-east

Example

Request:

GET /v2/apps/product/us-east/* HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2


Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "apps": [
        {
            "id": "/product/us-east/service/myapp", 
            "cmd": "env && sleep 60", 
            "constraints": [
                [
                    "hostname", 
                    "UNIQUE", 
                    ""
                ]
            ], 
            "container": null, 
            "cpus": 0.1, 
            "env": {
                "LD_LIBRARY_PATH": "/usr/local/lib/myLib"
            }, 
            "executor": "", 
            "instances": 3, 
            "mem": 5.0, 
            "ports": [
                15092, 
                14566
            ], 
            "tasksRunning": 1, 
            "tasksStaged": 0, 
            "uris": [
                "https://raw.github.com/mesosphere/marathon/master/README.md"
            ], 
            "version": "2014-03-01T23:42:20.938Z"
        }
    ]
}

GET /v2/apps/{appId}?embed={embed}

List the application with id appId.

The response includes some status information besides the current configuration of the app.

You can specify optional embed arguments, to get more embedded information.

taskRunning (Integer)

Warning Future versions of Marathon will only deliver this information when you specify “embed=app.counts” as a query parameter.

The number of tasks running for this application definition.

tasksStaged (Integer)

Warning Future versions of Marathon will only deliver this information when you specify “embed=app.counts” as a query parameter.

The number of tasks staged to run.

tasksHealthy (Integer)

Warning Future versions of Marathon will only deliver this information when you specify “embed=app.counts” as a query parameter.

The number of tasks which are healthy.

tasksUnhealthy (Integer)

Warning Future versions of Marathon will only deliver this information when you specify “embed=app.counts” as a query parameter.

The number of tasks which are unhealthy.

taskStats (Object) v0.11

Provides task statistics. The “taskStats” object only gets embedded into the app JSON if you pass an embed=app.taskStats query argument.

Task statistics are provided for the following groups of tasks. If no tasks for the group exist, no statistics are offered:

  • "withLatestConfig" contains statistics about all tasks that run with the same config as the latest app version.
  • "startedAfterLastScaling" contains statistics about all tasks that were started after the last scaling or restart operation.
  • "withOutdatedConfig" contains statistics about all tasks that were started before the last config change which was not simply a restart or scaling operation.
  • "totalSummary" contains statistics about all tasks.

Example JSON:

{
  // ...
  "taskStats": {
    {
      "startedAfterLastScaling" : {
        "stats" : {
          "counts" : { // equivalent to tasksStaged, tasksRunning, tasksHealthy, tasksUnhealthy
            "staged" : 1,
            "running" : 100,
            "healthy" : 90,
            "unhealthy" : 4
          },
          // "lifeTime" is only included if there are running tasks.
          "lifeTime" : { 
            // Measured from `"startedAt"` (timestamp of the Mesos TASK_RUNNING status update) of each running task 
            // until now.
            "averageSeconds" : 20.0,
            "medianSeconds" : 10.0
          }
        }
      },
      "withLatestConfig" : {
        "stats" : { /* ... same structure as above ... */ }
      },
      "withOutdatedConfig" : {
        "stats" : { /* ... same structure as above ... */ }
      },
      "totalSummary" : {
        "stats" : { /* ... same structure as above ... */ }
      }
    }
  }
  // ...
}

The calculation of these statistics is currently performed for every request and expensive if you have very many tasks.

deployments (Array of Objects)

Warning Future versions of Marathon will only deliver this information when you specify “embed=app.deployments” as a query parameter.

A list of currently running deployments that affect this application. If this array is nonempty, then this app is locked for updates.

The objects in the list only contain the id of the deployment, e.g.:

{
    "id": "44c4ed48-ee53-4e0f-82dc-4df8b2a69057"
}
readiness (Array of Objects)

A list of readiness check results. Only available during a deployment in the start phase.

The object in the list contains a readiness check in the format of:

 {
     "name": "myReadyCheck",
     "taskId": "foo.c3c80be4-f780-11e5-8d32-e24449f9e499",
     "ready": false,
     "lastResponse": {
       "status": 500,
       "contentType": "application/json",
       "body": "{}"
     }
   }
lastTaskFailure (Object)

Information about the last task failure for debugging purposes.

This information only gets embedded if you specify the “embed=app.lastTaskFailure” query parameter.

version

The version of the current app definition

versionInfo.lastConfigChangeAt (Timestamp as String)

"lastConfigChangeAt" contains the time stamp of the last change to this app which was not simply a scaling or a restarting configuration.

versionInfo.lastScalingAt (Timestamp as String)

"lastScalingAt" contains the time stamp of the last change including changes like scaling or restarting the app. Since our versions are time based, this is currently equal to "version".

Example

Request:

GET /v2/apps/myapp HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2


Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "app": {
        "args": null,
        "backoffFactor": 1.15,
        "backoffSeconds": 1,
        "maxLaunchDelaySeconds": 3600,
        "cmd": "python toggle.py $PORT0",
        "constraints": [],
        "container": null,
        "cpus": 0.2,
        "dependencies": [],
        "deployments": [
            {
                "id": "44c4ed48-ee53-4e0f-82dc-4df8b2a69057"
            }
        ],
        "disk": 0.0,
        "env": {},
        "executor": "",
        "healthChecks": [
            {
                "command": null,
                "gracePeriodSeconds": 5,
                "intervalSeconds": 10,
                "maxConsecutiveFailures": 3,
                "path": "/health",
                "portIndex": 0,
                "protocol": "HTTP",
                "timeoutSeconds": 10
            },
            {
                "command": null,
                "gracePeriodSeconds": 5,
                "intervalSeconds": 10,
                "maxConsecutiveFailures": 6,
                "path": "/machinehealth",
                "overridePort": 3333,
                "protocol": "HTTP",
                "timeoutSeconds": 10
            }
        ],
        "id": "/toggle",
        "instances": 2,
        "lastTaskFailure": { // soon only for ?embed=lastTaskFailure
            "appId": "/toggle",
            "host": "10.141.141.10",
            "message": "Abnormal executor termination",
            "state": "TASK_FAILED",
            "taskId": "toggle.cc427e60-5046-11e4-9e34-56847afe9799",
            "timestamp": "2014-09-12T23:23:41.711Z",
            "version": "2014-09-12T23:28:21.737Z"
        },
        "mem": 32.0,
        "ports": [
            10000
        ],
        "requirePorts": false,
        "storeUrls": [],
        "tasks": [ // soon only for ?embed=tasks
            {
                "appId": "/toggle",
                "healthCheckResults": [
                    {
                        "alive": true,
                        "consecutiveFailures": 0,
                        "firstSuccess": "2014-09-13T00:20:28.101Z",
                        "lastFailure": null,
                        "lastSuccess": "2014-09-13T00:25:07.506Z",
                        "taskId": "toggle.802df2ae-3ad4-11e4-a400-56847afe9799"
                    },
                    {
                        "alive": true,
                        "consecutiveFailures": 0,
                        "firstSuccess": "2014-09-13T00:20:28.101Z",
                        "lastFailure": null,
                        "lastSuccess": "2014-09-13T00:25:07.506Z",
                        "taskId": "toggle.802df2ae-3ad4-11e4-a400-56847afe9799"
                    }
                ],
                "host": "10.141.141.10",
                "id": "toggle.802df2ae-3ad4-11e4-a400-56847afe9799",
                "ports": [
                    31045
                ],
                "stagedAt": "2014-09-12T23:28:28.594Z",
                "startedAt": "2014-09-13T00:24:46.959Z",
                "version": "2014-09-12T23:28:21.737Z"
            },
            {
                "appId": "/toggle",
                "healthCheckResults": [
                    {
                        "alive": true,
                        "consecutiveFailures": 0,
                        "firstSuccess": "2014-09-13T00:20:28.101Z",
                        "lastFailure": null,
                        "lastSuccess": "2014-09-13T00:25:07.508Z",
                        "taskId": "toggle.7c99814d-3ad4-11e4-a400-56847afe9799"
                    },
                    {
                        "alive": true,
                        "consecutiveFailures": 0,
                        "firstSuccess": "2014-09-13T00:20:28.101Z",
                        "lastFailure": null,
                        "lastSuccess": "2014-09-13T00:25:07.506Z",
                        "taskId": "toggle.802df2ae-3ad4-11e4-a400-56847afe9799"
                    }
                ],
                "host": "10.141.141.10",
                "id": "toggle.7c99814d-3ad4-11e4-a400-56847afe9799",
                "ports": [
                    31234
                ],
                "stagedAt": "2014-09-12T23:28:22.587Z",
                "startedAt": "2014-09-13T00:24:46.965Z",
                "version": "2014-09-12T23:28:21.737Z"
            }
        ],
        "tasksRunning": 2, // soon only for ?embed=counts
        "tasksHealthy": 2, // soon only for ?embed=counts
        "tasksUnhealthy": 0, // soon only for ?embed=counts
        "tasksStaged": 0, // soon only for ?embed=counts
        "upgradeStrategy": {
            "minimumHealthCapacity": 1.0
        },
        "uris": [
            "http://downloads.mesosphere.com/misc/toggle.tgz"
        ],
        "user": null,
        "version": "2014-09-12T23:28:21.737Z",
        "versionInfo": {
            "lastConfigChangeAt": "2014-09-11T02:26:01.135Z",
            "lastScalingAt": "2014-09-12T23:28:21.737Z"
        }
    }
}

GET /v2/apps/{appId}/versions

List the versions of the application with ID appId.

Example

Request:

GET /v2/apps/my-app/versions HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "versions": [
        "2014-04-04T06:25:31.399Z"
    ]
}

GET /v2/apps/{appId}/versions/{version}

List the configuration of the application with ID appId at version version.

Example

Request:

GET /v2/apps/my-app/versions/2014-03-01T23:17:50.295Z HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate, compress
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "cmd": "sleep 60",
    "constraints": [],
    "container": null,
    "cpus": 0.1,
    "env": {},
    "executor": "",
    "id": "my-app",
    "instances": 4,
    "mem": 5.0,
    "ports": [
        18027,
        13200
    ],
    "uris": [
        "https://raw.github.com/mesosphere/marathon/master/README.md"
    ],
    "version": "2014-03-01T23:17:50.295Z"
}

PUT /v2/apps/{appId}

If application appId is running, then update the parameters; if it is not running, create it.

The new application parameters apply only to subsequently created tasks.
Currently running tasks are restarted while maintaining the minimumHealthCapacity.

Parameters
Name Type Description
force boolean If the app is affected by a running deployment, then the update operation will fail. The current deployment can be overridden by setting the `force` query parameter. Default: false.
Example

Request:

PUT /v2/apps/my-app HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 126
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

{
    "cmd": "sleep 55",
    "constraints": [
        [
            "hostname",
            "UNIQUE",
            ""
        ]
    ],
    "cpus": "0.3",
    "instances": "2",
    "mem": "9",
    "ports": [
        9000
    ]
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "deploymentId": "83b215a6-4e26-4e44-9333-5c385eda6438",
    "version": "2014-08-26T07:37:50.462Z"
}
Example (version rollback)

If the version key is supplied in the JSON body, the rest of the object is ignored. If the supplied version is known, then the app is updated (a new version is created) with those parameters. Otherwise, if the supplied version is not known, Marathon responds with a 404.

Request:

PUT /v2/apps/my-app HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 39
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

{
    "version": "2014-03-01T23:17:50.295Z"
}
HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "deploymentId": "83b215a6-4e26-4e44-9333-5c385eda6438",
    "version": "2014-08-26T07:37:50.462Z"
}
Example (update an app that is locked by a running deployment)

If the app is affected by a currently running deployment, then the update operation fails. As indicated by the response message, the current deployment can be overridden by setting the force query parameter in a subsequent request.

Request:

PUT /v2/apps/test HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Content-Length: 18
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.8.0

{
    "instances": "2"
}
HTTP/1.1 409 Conflict
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "deployments": [
        {
            "id": "5cd987cd-85ae-4e70-8df7-f1438367d9cb"
        }
    ],
    "message": "App is locked by one or more deployments. Override with the option '?force=true'. View details at '/v2/deployments/<DEPLOYMENT_ID>'."
}

POST /v2/apps/{appId}/restart

Initiates a rolling restart of all running tasks of the given app. This call respects the configured minimumHealthCapacity.

Parameters
Name Type Description
force boolean If the app is affected by a running deployment, then the update operation will fail. The current deployment can be overridden by setting the `force` query parameter. Default: false.
Example

Request:

POST /v2/apps/my-app/restart HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 0
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "deploymentId": "83b215a6-4e26-4e44-9333-5c385eda6438",
    "version": "2014-08-26T07:37:50.462Z"
}

DELETE /v2/apps/{appId}

Destroy an application. All data about that application will be deleted.

Example

Request:

DELETE /v2/apps/my-app HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 0
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
Server: Jetty(8.1.15.v20140411)
Transfer-Encoding: chunked

{
    "deploymentId": "14f48a7d-261e-4641-a158-8c5894c3116a",
    "version": "2015-04-21T10:34:13.646Z"
}

GET /v2/apps/{appId}/tasks

List all running tasks for application appId.

Example (as JSON)

Request:

GET /v2/apps/my-app/tasks HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "tasks": [
        {
            "host": "agouti.local",
            "id": "my-app_1-1396592790353",
            "ports": [
                31336,
                31337
            ],
            "stagedAt": "2014-04-04T06:26:30.355Z",
            "startedAt": "2014-04-04T06:26:30.860Z",
            "version": "2014-04-04T06:26:23.051Z"
        },
        {
            "host": "agouti.local",
            "id": "my-app_0-1396592784349",
            "ports": [
                31382,
                31383
            ],
            "stagedAt": "2014-04-04T06:26:24.351Z",
            "startedAt": "2014-04-04T06:26:24.919Z",
            "version": "2014-04-04T06:26:23.051Z"
        }
    ]
}
Example (as text)

Request:

GET /v2/apps/my-app/tasks HTTP/1.1
Accept: text/plain
Accept-Encoding: gzip, deflate, compress
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

my-app  19385 agouti.local:31336  agouti.local:31364  agouti.local:31382 
my-app  11186 agouti.local:31337  agouti.local:31365  agouti.local:31383 

DELETE /v2/apps/{appId}/tasks

Kill tasks that belong to the application appId.

Parameters
Name Type Description
host string Kill only those tasks running on host host. Default: none.
scale boolean Scale the app down (i.e. decrement its instances setting by the number of tasks killed) after killing the specified tasks. Default: false.
wipe boolean If wipe=true is specified and the app uses local persistent volumes, associated dynamic reservations will be unreserved, and persistent volumes will be destroyed. Only possible if scale=false or not specified. Default: false.
Example

Request:

DELETE /v2/apps/my-app/tasks?host=mesos.vm&scale=false HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 0
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "tasks": []
}

DELETE /v2/apps/{appId}/tasks/{taskId}

Kill the task with ID taskId that belongs to the application appId.

Parameters
Name Type Description
scale boolean Scale the app down (i.e. decrement its instances setting by the number of tasks killed) after killing the specified task. Only possible if wipe=false or not specified. Default: false.
wipe boolean If wipe=true is specified and the app uses local persistent volumes, associated dynamic reservations will be unreserved, and persistent volumes will be destroyed. Only possible if scale=false or not specified. Default: false.
Example

Request:

DELETE /v2/apps/my-app/tasks/my-app_3-1389916890411 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 0
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "task": {
        "host": "mesos.vm",
        "id": "my-app_3-1389916890411",
        "ports": [
            31509,
            31510
        ],
        "stagedAt": "2014-01-17T00:01+0000",
        "startedAt": "2014-01-17T00:01+0000"
    }
}

Groups

GET /v2/groups

List all groups.

Request:

GET /v2/groups HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "apps": [],
    "dependencies": [],
    "groups": [
        {
            "apps": [
                {
                    "args": null,
                    "backoffFactor": 1.15,
                    "backoffSeconds": 1,
                    "maxLaunchDelaySeconds": 3600,
                    "cmd": "sleep 30",
                    "constraints": [],
                    "container": null,
                    "cpus": 1.0,
                    "dependencies": [],
                    "disk": 0.0,
                    "env": {},
                    "executor": "",
                    "healthChecks": [],
                    "id": "/test/app",
                    "instances": 1,
                    "mem": 128.0,
                    "ports": [
                        10000
                    ],
                    "requirePorts": false,
                    "storeUrls": [],
                    "upgradeStrategy": {
                        "minimumHealthCapacity": 1.0
                    },
                    "uris": [],
                    "user": null,
                    "version": "2014-08-28T01:05:40.586Z"
                }
            ],
            "dependencies": [],
            "groups": [],
            "id": "/test",
            "version": "2014-08-28T01:09:46.212Z"
        }
    ],
    "id": "/",
    "version": "2014-08-28T01:09:46.212Z"
}

GET /v2/groups/{groupId}

List the group with the specified ID.

Request:

GET /v2/groups/test HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "apps": [
        {
            "args": null,
            "backoffFactor": 1.15,
            "backoffSeconds": 1,
            "maxLaunchDelaySeconds": 3600,
            "cmd": "sleep 30",
            "constraints": [],
            "container": null,
            "cpus": 1.0,
            "dependencies": [],
            "disk": 0.0,
            "env": {},
            "executor": "",
            "healthChecks": [],
            "id": "/test/app",
            "instances": 1,
            "mem": 128.0,
            "ports": [
                10000
            ],
            "requirePorts": false,
            "storeUrls": [],
            "upgradeStrategy": {
                "minimumHealthCapacity": 1.0
            },
            "uris": [],
            "user": null,
            "version": "2014-08-28T01:05:40.586Z"
        }
    ],
    "dependencies": [],
    "groups": [],
    "id": "/test",
    "version": "2014-08-28T01:09:46.212Z"
}

POST /v2/groups

Create and start a new application group. Application groups can contain other application groups. An application group can either hold other groups or applications, but they cannot contain both.

The JSON format of a group resource is as follows:

{
  "id": "product",
  "groups": [{
    "id": "service",
    "groups": [{
      "id": "us-east",
      "apps": [{
        "id": "app1",
        "cmd": "someExecutable"
      }, 
      {
        "id": "app2",
        "cmd": "someOtherExecutable"
      }]
    }],
    "dependencies": ["/product/database", "../backend"]
  }
],
"version": "2014-03-01T23:29:30.158Z"
}

Since the deployment of the group can take a considerable amount of time, this endpoint returns immediately with a version. The failure or success of the action is signalled via an event. There is a group_change_success and group_change_failed event with the given version.

Example

Request:

POST /v2/groups HTTP/1.1
User-Agent: curl/7.35.0
Accept: application/json
Host: localhost:8080
Content-Type: application/json
Content-Length: 273

{
  "id" : "product",
  "apps":[
    {
      "id": "myapp",
      "cmd": "ruby app2.rb",
      "instances": 1
    }
  ]
}

Response:

HTTP/1.1 201 Created
Location: http://localhost:8080/v2/groups/product
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(8.y.z-SNAPSHOT)
{"version":"2014-07-01T10:20:50.196Z"}

Create and start a new application group. Application groups can contain other application groups. An application group can either hold other groups or applications, but they cannot contain both.

The JSON format of a group resource is as follows:

{
  "id": "product",
  "groups": [{
    "id": "service",
    "groups": [{
      "id": "us-east",
      "apps": [{
        "id": "app1",
        "cmd": "someExecutable"
      }, 
      {
        "id": "app2",
        "cmd": "someOtherExecutable"
      }]
    }],
    "dependencies": ["/product/database", "../backend"]
  }
],
"version": "2014-03-01T23:29:30.158Z"
}

Since the deployment of the group can take a considerable amount of time, this endpoint returns immediately with a version. The failure or success of the action is signalled via an event. There is a group_change_success and group_change_failed event with the given version.

Example

Request:

POST /v2/groups HTTP/1.1
User-Agent: curl/7.35.0
Accept: application/json
Host: localhost:8080
Content-Type: application/json
Content-Length: 273

{
  "id" : "product",
  "apps":[
    {
      "id": "myapp",
      "cmd": "ruby app2.rb",
      "instances": 1
    }
  ]
}

Response:

HTTP/1.1 201 Created
Location: http://localhost:8080/v2/groups/product
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(8.y.z-SNAPSHOT)
{"version":"2014-07-01T10:20:50.196Z"}

PUT /v2/groups/{groupId}

Change parameters of a deployed application group.

  • Changes to application parameters will result in a restart of this application.
  • A new application added to the group is started.
  • An existing application removed from the group gets stopped.

If there are no changes to the application definition, no restart is triggered. During restart, Marathon ensures that the configured amount of minimal running instances are always available.

A deployment can run forever. This can happen when a new application has a problem and does not become healthy. In this case, human interaction is needed with 2 possible choices:

  • Roll back to an existing older version (send an existing version in the body).
  • Update with a newer version of the group that does not have the problems of the old one.

If there is an upgrade process already in progress, a new update will be rejected unless the force flag is set. With the force flag given, a running upgrade is terminated and a new one is started.

Since the deployment of the group can take a considerable amount of time, this endpoint returns immediately with a version. The failure or success of the action is signalled via an event. There is a group_change_success and group_change_failed event with the given version.

Example

Request:

PUT /v2/groups/test/project HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Content-Length: 541
Content-Type: application/json; charset=utf-8
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

{
    "apps": [
        {
            "cmd": "ruby app2.rb",
            "constraints": [],
            "container": null,
            "cpus": 0.2,
            "env": {},
            "executor": "//cmd",
            "healthChecks": [
                {
                    "initialDelaySeconds": 15,
                    "intervalSeconds": 5,
                    "path": "/health",
                    "portIndex": 0,
                    "protocol": "HTTP",
                    "timeoutSeconds": 15
                }
            ],
            "id": "app",
            "instances": 6,
            "mem": 128.0,
            "ports": [
                19970
            ],
            "uris": []
        }
    ]
}
HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "deploymentId": "c0e7434c-df47-4d23-99f1-78bd78662231",
    "version": "2014-08-28T16:45:41.063Z"
}

Example

Scale a group.

The scaling affects apps directly in the group as well as all transitive applications referenced by subgroups of this group. The scaling factor is applied to each individual instance count of each application.

Since the deployment of the group can take a considerable amount of time, this endpoint returns immediately with a version. The failure or success of the action is signalled via an event. There is a group_change_success and group_change_failed event with the given version.

Request:

PUT /v2/groups/product/service HTTP/1.1
Content-Length: 123
Host: localhost:8080
User-Agent: HTTPie/0.7.2
{ "scaleBy": 1.5 }

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "deploymentId": "c0e7434c-df47-4d23-99f1-78bd78662231",
    "version": "2014-08-28T16:45:41.063Z"
}

Example

Roll back a group.

In case of an erroneous update, a group can be rolled back by sending just a version that is known to work to the update endpoint.

Request:

PUT /v2/groups/product/service HTTP/1.1
Content-Length: 123
Host: localhost:8080
User-Agent: HTTPie/0.7.2
{ "version": "2014-08-27T15:34:48.163Z" }

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "deploymentId": "c0e7434c-df47-4d23-99f1-78bd78662231",
    "version": "2014-08-28T16:45:41.063Z"
}

Example

Deployment dry run.

Get a preview of the deployment steps Marathon would run for a given group update.

Request:

PUT /v2/groups/product?dryRun=true HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Content-Type: application/json
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

{
    "id": "product",
    "groups": [{
        "id": "service",
        "groups": [{
            "id": "us-east",
            "apps": [
                {
                    "id": "app1",
                    "cmd": "someExecutable"
                },
                {
                    "id": "app2",
                    "cmd": "someOtherExecutable"
                }
            ]
        }],
        "dependencies": ["/product/database", "../backend"]
    }],
    "version": "2014-03-01T23:29:30.158Z"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "steps" : [
        {
            "actions" : [
                {
                    "app" : "app1",
                    "type" : "StartApplication"
                },
                {
                    "app" : "app2",
                    "type" : "StartApplication"
                }
            ]
        },
        {
            "actions" : [
                {
                    "type" : "ScaleApplication",
                    "app" : "app1"
                }
            ]
        },
        {
            "actions" : [
                {
                    "app" : "app2",
                    "type" : "ScaleApplication"
                }
            ]
        }
    ]
}

DELETE /v2/groups/{groupId}

Destroy a group. All data about that group and all associated applications will be deleted.

Since the deployment of the group can take a considerable amount of time, this endpoint returns immediately with a version. The failure or success of the action is signalled via an event. There is a group_change_success and group_change_failed event with the given version.

Request:

DELETE /v2/groups/product/service/app HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 0
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: curl/7.35.0

Response:

HTTP/1.1 200 Ok
Content-Type: application/json
Transfer-Encoding: chunked
Server: Jetty(8.y.z-SNAPSHOT)
{"version":"2014-07-01T10:20:50.196Z"}

Tasks

GET /v2/tasks

List tasks of all applications.

Parameters
Name Type Description
status string Return only those tasks whose status matches this parameter. If not specified, all tasks are returned. Possible values: running, staging. Default: none.
Example (as JSON)

Request:

GET /v2/tasks HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Content-Type: application/json; charset=utf-8
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "tasks": [
        {
            "appId": "/bridged-webapp",
            "healthCheckResults": [
                {
                    "alive": true,
                    "consecutiveFailures": 0,
                    "firstSuccess": "2014-10-03T22:57:02.246Z",
                    "lastFailure": null,
                    "lastSuccess": "2014-10-03T22:57:41.643Z",
                    "taskId": "bridged-webapp.eb76c51f-4b4a-11e4-ae49-56847afe9799"
                }
            ],
            "host": "10.141.141.10",
            "id": "bridged-webapp.eb76c51f-4b4a-11e4-ae49-56847afe9799",
            "ports": [
                31000
            ],
            "servicePorts": [
                9000
            ],
            "stagedAt": "2014-10-03T22:16:27.811Z",
            "startedAt": "2014-10-03T22:57:41.587Z",
            "version": "2014-10-03T22:16:23.634Z"
        },
        {
            "appId": "/bridged-webapp",
            "healthCheckResults": [
                {
                    "alive": true,
                    "consecutiveFailures": 0,
                    "firstSuccess": "2014-10-03T22:57:02.246Z",
                    "lastFailure": null,
                    "lastSuccess": "2014-10-03T22:57:41.649Z",
                    "taskId": "bridged-webapp.ef0b5d91-4b4a-11e4-ae49-56847afe9799"
                }
            ],
            "host": "10.141.141.10",
            "id": "bridged-webapp.ef0b5d91-4b4a-11e4-ae49-56847afe9799",
            "ports": [
                31001
            ],
            "servicePorts": [
                9000
            ],
            "stagedAt": "2014-10-03T22:16:33.814Z",
            "startedAt": "2014-10-03T22:57:41.593Z",
            "version": "2014-10-03T22:16:23.634Z"
        }
    ]
}

Example (as text)

In text/plain, only tasks with status running will be returned.

Request:

GET /v2/tasks HTTP/1.1
Accept: text/plain
Accept-Encoding: gzip, deflate, compress
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

my-app  19385 agouti.local:31336  agouti.local:31364  agouti.local:31382 
my-app2  11186 agouti.local:31337  agouti.local:31365  agouti.local:31383 

POST /v2/tasks/delete

Kill the given list of tasks and scale apps if requested.

Parameters
Name Type Description
scale boolean Scale the app down (i.e. decrement its instances setting by the number of tasks killed) after killing the specified tasks. Only possible if wipe=false or not specified. Default: false.
wipe boolean If wipe=true is specified and the app uses local persistent volumes, associated dynamic reservations will be unreserved and persistent volumes will be destroyed. Only possible if scale=false or not specified. Default: false.
Example (as JSON)

Request:

POST /v2/tasks/delete HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Content-Type: application/json; charset=utf-8
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0
{
    "ids": [
        "task.25ab260e-b5ec-11e4-a4f4-685b35c8a22e",
        "task.5e7b39d4-b5f0-11e4-8021-685b35c8a22e",
        "task.a21cb64a-b5eb-11e4-a4f4-685b35c8a22e"
    ]
}

Response:

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)

Deployments

v0.7.0

GET /v2/deployments

List all running deployments. A deployment is a change in the service setup.

A deployment is identified by an id, affects a set of applications and is composed of deployment steps. Every step contains a list of actions with following types:

  • StartApplication: starts an application, which is currently not running.
  • StopApplication: stops an already running application.
  • ScaleApplication: changes the number of instances of an application and allows to kill specified instances while scaling.
  • RestartApplication: upgrades an already deployed application with a new version.
  • KillAllOldTasksOf: last step of a restart action.
Example

Request:

GET /v2/deployments HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Host: localhost:8080

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

[
    {
        "affectedApps": [
            "/test/service/srv1", 
            "/test/db/mongo1", 
            "/test/frontend/app1"
        ], 
        "currentStep": 2,
        "currentActions": [
          {
              "action": "RestartApplication", 
              "app": "/test/frontend/app1",
              "readinessChecks": [
                  {
                      "lastResponse": {
                          "body": "{}", 
                          "contentType": "application/json", 
                          "status": 500
                      }, 
                      "name": "myReadyCheck", 
                      "ready": false, 
                      "taskId": "test_frontend_app1.c9de6033"
                  }
              ]

          }
        ],
        "totalSteps": 9,
        "id": "2e72dbf1-2b2a-4204-b628-e8bd160945dd", 
        "steps": [
            {
                "actions": [
                    {
                        "action": "RestartApplication", 
                        "app": "/test/service/srv1"
                    }
                ]
            },
            {
                "actions": [
                    {
                        "action": "RestartApplication", 
                        "app": "/test/db/mongo1"
                    }
                ]
            },
            {
                "actions": [
                    {
                        "action": "RestartApplication", 
                        "app": "/test/frontend/app1"
                    }
                ]
            },
            {
                "actions": [
                    {
                        "action": "KillAllOldTasksOf", 
                        "app": "/test/frontend/app1"
                    }
                ]
            },
            {
                "actions": [
                    {
                        "action": "KillAllOldTasksOf", 
                        "app": "/test/db/mongo1"
                    }
                ]
            },
            {
                "actions": [
                    {
                        "action": "KillAllOldTasksOf", 
                        "app": "/test/service/srv1"
                    }
                ]
            },
            {
                "actions": [
                    {
                        "action": "ScaleApplication", 
                        "app": "/test/service/srv1"
                    }
                ]
            },
            {
                "actions": [
                    {
                        "action": "ScaleApplication", 
                        "app": "/test/db/mongo1"
                    }
                ]
            },
            {
                "actions": [
                    {
                        "action": "ScaleApplication", 
                        "app": "/test/frontend/app1"
                    }
                ]
            }
        ], 
        "version": "2014-07-09T11:14:11.477Z"
    }
]

DELETE /v2/deployments/{deploymentId}

Parameters
Name Type Description
force boolean If set to false (the default) then the deployment is canceled and a new deployment is created to revert the changes of this deployment. Without concurrent deployments, this restores the configuration before this deployment. If set to true, then the deployment is still canceled but no rollback deployment is created. Default: false.
Example

Revert the deployment with deploymentId by creating a new deployment which reverses all changes.

Request:

DELETE /v2/deployments/867ed450-f6a8-4d33-9b0e-e11c5513990b HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Content-Length: 0
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "deploymentId": "0b1467fc-d5cd-4bbc-bac2-2805351cee1e",
    "version": "2014-08-26T08:20:26.171Z"
}
Example

Cancel the deployment with deploymentId, and do not create a new rollback deployment.

Request:

DELETE /v2/deployments/177b7556-1287-4e09-8432-3d862981a987?force=true HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Content-Length: 0
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

Response:

HTTP/1.1 202 Accepted
Content-Length: 0
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)

Event Stream

v0.9.0

GET /v2/events

Attach to the Marathon event stream.

To use this endpoint, the client has to accept the text/event-stream content type. Note: A request to this endpoint will not be closed by the server. If an event happens on the server side, this event will be propagated to the client immediately. See Server Sent Events for a more detailed explanation.

Request:

GET /v2/events HTTP/1.1
Accept: text/event-stream
Accept-Encoding: gzip, deflate
Host: localhost:8080
User-Agent: HTTPie/0.8.0

Response:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Connection: close
Content-Type: text/event-stream;charset=UTF-8
Expires: 0
Pragma: no-cache
Server: Jetty(8.1.15.v20140411)

If an event happens on the server side, it is sent as plain JSON prepended with the mandatory data: field.

Response:

data: {"remoteAddress":"96.23.11.158","eventType":"event_stream_attached","timestamp":"2015-04-28T12:14:57.812Z"}

data: {"groupId":"/","version":"2015-04-28T12:24:12.098Z","eventType":"group_change_success","timestamp":"2015-04-28T12:24:12.224Z"}

Event Subscriptions

POST /v2/eventSubscriptions

Register a callback URL as an event subscriber.

NOTE: To activate this endpoint, you need to start Marathon with --event_subscriber http_callback.

Parameters
Name Type Description
callbackUrl string URL to which events should be posted. Required.

Request:

POST /v2/eventSubscriptions?callbackUrl=http://localhost:9292/callback HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 0
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "callbackUrl": "http://localhost:9292/callback",
    "clientIp": "0:0:0:0:0:0:0:1",
    "eventType": "subscribe_event"
}

GET /v2/eventSubscriptions

List all event subscriber callback URLs.

NOTE: To activate this endpoint, you need to start Marathon with --event_subscriber http_callback.

Example

Request:

GET /v2/eventSubscriptions HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "callbackUrls": [
        "http://localhost:9292/callback"
    ]
}

DELETE /v2/eventSubscriptions

Unregister a callback URL from the event subscribers list.

NOTE: To activate this endpoint, you need to start Marathon with --event_subscriber http_callback.

Parameters
Name Type Description
callbackUrl string URL passed when the event subscription was created. Required.
Example

Request:

DELETE /v2/eventSubscriptions?callbackUrl=http://localhost:9292/callback HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Length: 0
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "callbackUrl": "http://localhost:9292/callback",
    "clientIp": "0:0:0:0:0:0:0:1",
    "eventType": "unsubscribe_event"
}

Queue

v0.7.0

GET /v2/queue

Show content of the launch queue.

Example
GET /v2/queue HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Host: localhost:8080
User-Agent: HTTPie/0.8.0
HTTP/1.1 200 OK
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "queue": [
        {
            "count" : 10,
            "delay": {
              "overdue": "true",
              "timeLeftSeconds": 784
            }
            "app" : {
                "cmd" : "tail -f /dev/null",
                "backoffSeconds" : 1,
                "healthChecks" : [],
                "storeUrls" : [],
                "constraints" : [],
                "env" : {},
                "cpus" : 0.1,
                "labels" : {},
                "instances" : 10,
                "ports" : [
                   10000
                ],
                "requirePorts" : false,
                "uris" : [],
                "container" : null,
                "backoffFactor" : 1.15,
                "args" : null,
                "version" : "2015-02-09T10:49:59.831Z",
                "maxLaunchDelaySeconds" : 3600,
                "upgradeStrategy" : {
                   "minimumHealthCapacity" : 1,
                   "maximumOverCapacity" : 1
                },
                "dependencies" : [],
                "mem" : 16,
                "id" : "/foo",
                "disk" : 0,
                "executor" : "",
                "user" : null
            }
        }
    ]
}

DELETE /v2/queue/{appId}/delay

The application-specific task launch delay can be reset by calling this endpoint.

Example
DELETE /v2/queue/myapp/delay HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: localhost:8080
User-Agent: HTTPie/0.9.2
HTTP/1.1 204 No Content
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache
Server: Jetty(8.1.15.v20140411)

Server Info

v0.7.0

GET /v2/info

Get info about the Marathon instance.

Request:

GET /v2/info HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Content-Type: application/json; charset=utf-8
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Length: 872
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)

{
    "frameworkId": "20140730-222531-1863654316-5050-10422-0000",
    "leader": "127.0.0.1:8080",
    "http_config": {
        "assets_path": null,
        "http_port": 8080,
        "https_port": 8443
    },
    "event_subscriber": {
        "type": "http_callback",
        "http_endpoints": [
            "localhost:9999/events"
        ]
    },
    "marathon_config": {
        "checkpoint": false,
        "executor": "//cmd",
        "failover_timeout": 604800,
        "ha": true,
        "hostname": "127.0.0.1",
        "local_port_max": 49151,
        "local_port_min": 32767,
        "master": "zk://localhost:2181/mesos",
        "mesos_leader_ui_url": "http://mesos.vm:5050",
        "mesos_role": null,
        "mesos_user": "root",
        "reconciliation_initial_delay": 30000,
        "reconciliation_interval": 30000,
        "task_launch_timeout": 60000
    },
    "name": "marathon",
    "version": "0.7.0-SNAPSHOT",
    "zookeeper_config": {
        "zk": "zk://localhost:2181/marathon",
        "zk_timeout": 10000,
        "zk_session_timeout": 1800000,
        "zk_max_version": 5
    }
}

GET /v2/leader

Returns the current leader. If no leader exists, Marathon will respond with a 404 error.

Request:

GET /v2/leader HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Length: 872
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)

{
    "leader": "127.0.0.1:8080"
}

DELETE /v2/leader

v0.7.7

Causes the current leader to abdicate, triggering a new election. If no leader exists, Marathon will respond with a 404 error.

Request:

DELETE /v2/leader HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Host: localhost:8080
User-Agent: HTTPie/0.7.2

Response:

HTTP/1.1 200 OK
Content-Length: 872
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)

{
    "message": "Leadership abdicated"
}

Miscellaneous

Request:

Response:

GET /ping

Request:

GET /ping HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

Response:

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Cache-Control: must-revalidate,no-cache,no-store
Content-Length: 5
Content-Type: text/plain;charset=ISO-8859-1
Server: Jetty(8.y.z-SNAPSHOT)

pong

GET /logging

Request:

GET /logging HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

Response:

HTML-only endpoint

GET /help

Request:

GET /help HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

Response:

HTML-only endpoint

GET /metrics

Request:

GET /metrics HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Host: mesos.vm:8080
User-Agent: HTTPie/0.8.0

Response:

HTTP/1.1 200 OK
Cache-Control: must-revalidate,no-cache,no-store
Content-Type: application/json
Server: Jetty(8.y.z-SNAPSHOT)
Transfer-Encoding: chunked

{
    "counters": {
        ...
    },
    "gauges": {
        ...
    },
    "histograms": {},
    "meters": {
        ...
    },
    "timers": {
        ...
    },
    "version": "3.0.0"
}