Marathon API

Every request other than GET /healthcheck must pass a x-forwarded-email header, otherwise it will return 401 Unauthorized.

Healthcheck Routes

Healthcheck

GET /healthcheck

Validates that the app is still up, including the database connection.

• Success Response

  • Code: 200

  • Content:

      {
        "healthy": true
      }
    

  • Headers:

    It will add an MARATHON-VERSION header with the current marathon module version.

• Error Response

  It will return an error if it failed to connect to the database.

  • Code: 500
  • Content:

    {
      "healthy": false
    }
  

App Routes

List Apps

GET /apps

List all apps in Marathon DB.

• Success Response

  • Code: 200

  • Content:

    [
      {  
        id:        [uuid],
        name:      [string],
        bundleId:  [string],
        createdBy: [string], // email
        createdAt: [int64],  // nanoseconds since epoch
        updatedAt: [int64]   // nanoseconds since epoch
      },
      {  
        id:        [uuid],
        name:      [string],
        bundleId:  [string],
        createdBy: [string], // email
        createdAt: [int64],  // nanoseconds since epoch
        updatedAt: [int64]   // nanoseconds since epoch
      },
      ...
    ]
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Create App

POST /apps

Creates a new app with the given parameters.

• Payload

  {
    "name":                          [string],  // 255 characters max
    "bundleId":                      [string]   // matching ^[a-z0-9]+\\.[a-z0-9]+(\\.[a-z0-9]+)+$
  }
  

• Success Response

  • Code: 201

  • Content:

    {  
      id:        [uuid],   // generated by marathon
      name:      [string],
      bundleId:  [string],
      createdBy: [string], // email of the authenticated user
      createdAt: [int64],  // nanoseconds since epoch
      updatedAt: [int64]   // nanoseconds since epoch
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  It will return an error if there is already an app with the same bundleId.

  • Code: 409

  • Content:

    {
      "reason": [string]
    }
    

  It will return an error if there are missing or invalid parameters.

  • Code: 422

  • Content:

    {
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Retrieve App

GET /apps/:appId

Retrieves the app that has id appId.

• Success Response

  • Code: 200

  • Content:

    {  
      id:        [uuid],
      name:      [string],
      bundleId:  [string],
      createdBy: [string], // email
      createdAt: [int64],  // nanoseconds since epoch
      updatedAt: [int64]   // nanoseconds since epoch
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Update App

PUT /apps/:appId

Updates the app that has id appId.

• Payload

  {
    "name":                          [string],  // 255 characters max
    "bundleId":                      [string]   // matching ^[a-z0-9]+\\.[a-z0-9]+(\\.[a-z0-9]+)+$
  }
  

• Success Response

  • Code: 201

  • Content:

    {  
      id:        [uuid],   // generated by marathon
      name:      [string],
      bundleId:  [string],
      createdBy: [string], // email of the authenticated user
      createdAt: [int64],  // nanoseconds since epoch
      updatedAt: [int64]   // nanoseconds since epoch
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  It will return an error if there is already an app with the same bundleId.

  • Code: 409

  • Content:

    {
      "reason": [string]
    }
    

  It will return an error if there are missing or invalid parameters.

  • Code: 422

  • Content:

    {
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Delete App

DELETE /apps/:appId

Deletes the app that has id appId.

• Success Response

  • Code: 204

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  It will return an error if there are missing or invalid parameters.

  • Code: 422

  • Content:

    {
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Template Routes

List app templates

GET /apps/:appId/templates

List all templates for the app with the given id.

• Success Response

  • Code: 200

  • Content:

    [
      {  
        id:        [uuid],
        name:      [string],
        locale:    [string],
        defaults:  [json],
        body:      [json],
        appId:     [uuid],
        createdBy: [string], // email
        createdAt: [int64],  // nanoseconds since epoch
        updatedAt: [int64]   // nanoseconds since epoch
      },
      {  
        id:        [uuid],
        name:      [string],
        locale:    [string],
        defaults:  [json],
        body:      [json],
        appId:     [uuid],
        createdBy: [string], // email
        createdAt: [int64],  // nanoseconds since epoch
        updatedAt: [int64]   // nanoseconds since epoch
      },
      ...
    ]
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Create Template

POST /apps/:appId/templates

Creates a new template with the given parameters.

• Payload

  {
    name:      [string],
    locale:    [string],
    defaults:  [json],   // cannot be empty
    body:      [json]   // cannot be empty
  }
  

• Success Response

  • Code: 201

  • Content:

    {  
      id:        [uuid],
      name:      [string],
      locale:    [string],
      defaults:  [json],   // cannot be empty
      body:      [json],   // cannot be empty
      appId:     [uuid],
      createdBy: [string], // email
      createdAt: [int64],  // nanoseconds since epoch
      updatedAt: [int64]   // nanoseconds since epoch
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  It will return an error if there is already a template with the same appId, name and locale.

  • Code: 409

  • Content:

    {
      "reason": [string]
    }
    

  It will return an error if there are missing or invalid parameters.

  • Code: 422

  • Content:

    {
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Retrieve Template

GET /apps/:appId/templates/:templateId

Retrieves the app that has id templateId.

• Success Response

  • Code: 200

  • Content:

    {  
      id:        [uuid],
      name:      [string],
      locale:    [string],
      defaults:  [json],
      body:      [json],
      appId:     [uuid],
      createdBy: [string]
      createdAt: [int64],
      updatedAt: [int64]
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Update Template

PUT /apps/:appId/templates/:templateId

Updates the template that has id templateId.

• Payload

  {
    name:      [string],
    locale:    [string],
    defaults:  [json],   // cannot be empty
    body:      [json]   // cannot be empty
  }
  

• Success Response

  • Code: 201

  • Content:

    {  
      id:        [uuid],
      name:      [string],
      locale:    [string],
      defaults:  [json],  
      body:      [json],  
      appId:     [uuid],
      createdBy: [string],
      createdAt: [int64],
      updatedAt: [int64]  
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  It will return an error if there is already a template with the same appId, name and locale.

  • Code: 409

  • Content:

    {
      "reason": [string]
    }
    

  It will return an error if there are missing or invalid parameters.

  • Code: 422

  • Content:

    {
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Delete Template

DELETE /apps/:appId/templates/:templateId

Deletes the templaye that has id templateId.

• Success Response

  • Code: 204

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  It will return an error if there are missing or invalid parameters.

  • Code: 422

  • Content:

    {
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Job Routes

List app jobs

GET /apps/:appId/jobs?template=<optional-template-name>

List all jobs for the app with the given id. If the template query string parameter is sent only jobs for the templates with this name will be returned.

• Success Response

  • Code: 200

  • Content:

    [
      {  
        id:                  [uuid],
        totalBatches:        [null|int], // if null the total batches that will be sent was not calculated yet
        completedBatches:    [int],
        totalUsers:          [null|int], // if null the total users that will receive the push was not calculated yet
        totalTokens:         [null|int], // if null the total tokens that will receive the push was not calculated yet
        completedTokens:     [int],
        dbPageSize:          [int],    // page size that will be used for retrieving tokens from the database
        localized:           [boolean],
        completedAt:         [int64],  // nanoseconds since epoch,
        expiresAt:           [int64],  // nanoseconds since epoch, optional but if > 0 push will no longer be sent after this timestamp,
        startsAt:            [int64],  // nanoseconds since epoch, optional but if > 0 job was scheduled,
        context:             [json],   // optional
        service:             [gcm|apns],
        filters:             [json],   // optional
        metadata:            [json],   // optional
        csvPath:             [string], // full path of the S3 file with the csv containing users ids for this job,
        templateName:        [string], // can also be several strings separated by commas
        pastTimeStrategy:    [null|string], // null if job is not localized or one of [skip, nextDay]
        status:              [null|string], // null if job is running or one of [paused, stopped, circuitbreak]
        appId:               [uuid],
        createdBy:           [string], // email
        createdAt:           [int64],  // nanoseconds since epoch
        updatedAt:           [int64],  // nanoseconds since epoch
        controlGroup:        [float],  // float between 0-1, represents the % of users that won't receive notifications
        controlGroupCsvPath: [string]  // full path of the S3 file with the csv containing users ids of users in the control group
      },
      {  
        id:                  [uuid],
        totalBatches:        [null|int],
        completedBatches:    [int],
        totalUsers:          [null|int],
        totalTokens:         [null|int],
        completedTokens:     [int],
        dbPageSize:          [int],   
        localized:           [boolean],
        completedAt:         [int64],
        expiresAt:           [int64],
        startsAt:            [int64],
        context:             [json],  
        service:             [gcm|apns],
        filters:             [json],  
        metadata:            [json],  
        csvPath:             [string],
        templateName:        [string],
        pastTimeStrategy:    [null|string],
        status:              [null|string],
        appId:               [uuid],
        createdBy:           [string],
        createdAt:           [int64],
        updatedAt:           [int64],
        controlGroup:        [float],
        controlGroupCsvPath: [string]
      },
      ...
    ]
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Create Job

POST /apps/:appId/jobs?template=<mandatory-template-name>

Creates a new job with the given parameters and template name. The template name can be composed of several template names separated by commas. Example POST /apps/:appId/jobs?template=tpl1,tpl2,tpl3,tpl4. In this case the template messages will be randomly chosen for each user using a uniform distribution.

• Payload

  {
    localized:        [boolean],
    expiresAt:        [int64],  // nanoseconds since epoch, optional but if > 0 push will no longer be sent after this timestamp,
    startsAt:         [int64],  // nanoseconds since epoch, optional but if > 0 job was scheduled,
    context:          [json],   // optional
    service:          [gcm|apns],
    filters:          [json],   // optional
    metadata:         [json],   // optional
    csvPath:          [string], // full path of the S3 file with the csv containing users ids for this job,
    pastTimeStrategy: [null|string], // null if job is not localized or one of [skip, nextDay]
    controlGroup:     [float]   // float between 0-1, represents the % of users that won't receive notifications
  }
  

• Success Response

  • Code: 201

  • Content:

    {  
      id:               [uuid],
      totalBatches:     [null|int],
      completedBatches: [int],
      totalUsers:       [null|int],
      completedUsers:   [int],
      completedTokens:  [int],
      dbPageSize:       [int],   
      localized:        [boolean],
      completedAt:      [int64],
      expiresAt:        [int64],
      startsAt:         [int64],
      context:          [json],  
      service:          [gcm|apns],
      filters:          [json],  
      metadata:         [json],  
      csvPath:          [string],
      templateName:     [string],
      pastTimeStrategy: [null|string],
      status:           [null|string],
      appId:            [uuid],
      createdBy:        [string],
      createdAt:        [int64],
      updatedAt:        [int64],
      controlGroup:        [float],
      controlGroupCsvPath: [string]
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  It will return an error if there are missing or invalid parameters.

  • Code: 422

  • Content:

    {
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Retrieve Job

GET /apps/:appId/jobs/:jobId

Retrieves the app that has id jobId.

• Success Response

  • Code: 200

  • Content:

    {  
      id:               [uuid],
      totalBatches:     [null|int],
      completedBatches: [int],
      totalUsers:       [null|int],
      completedUsers:   [int],
      completedTokens:  [int],
      dbPageSize:       [int],   
      localized:        [boolean],
      completedAt:      [int64],
      expiresAt:        [int64],
      startsAt:         [int64],
      context:          [json],  
      service:          [gcm|apns],
      filters:          [json],  
      metadata:         [json],  
      csvPath:          [string],
      templateName:     [string],
      pastTimeStrategy: [null|string],
      status:           [null|string],
      appId:            [uuid],
      createdBy:        [string],
      createdAt:        [int64],
      updatedAt:        [int64],
      controlGroup:        [float],
      controlGroupCsvPath: [string]
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Pause Job

PUT /apps/:appId/jobs/:jobId/pause

Pauses the job that has id jobId.

• Payload

  {}
  

• Success Response

  • Code: 201

  • Content:

    {  
      id:               [uuid],
      totalBatches:     [null|int],
      completedBatches: [int],
      totalUsers:       [null|int],
      completedUsers:   [int],
      completedTokens:  [int],
      dbPageSize:       [int],   
      localized:        [boolean],
      completedAt:      [int64],
      expiresAt:        [int64],
      startsAt:         [int64],
      context:          [json],  
      service:          [gcm|apns],
      filters:          [json],  
      metadata:         [json],  
      csvPath:          [string],
      templateName:     [string],
      pastTimeStrategy: [null|string],
      status:           "paused",
      appId:            [uuid],
      createdBy:        [string],
      createdAt:        [int64],
      updatedAt:        [int64],
      controlGroup:        [float],
      controlGroupCsvPath: [string]
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  It will return an error if there are missing or invalid parameters or if the job previous status was not null.

  • Code: 422

  • Content:

    {
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Stop Job

PUT /apps/:appId/jobs/:jobId/pause

Stops the job that has id jobId.

• Payload

  {}
  

• Success Response

  • Code: 201

  • Content:

    {  
      id:               [uuid],
      totalBatches:     [null|int],
      completedBatches: [int],
      totalUsers:       [null|int],
      completedUsers:   [int],
      completedTokens:  [int],
      dbPageSize:       [int],   
      localized:        [boolean],
      completedAt:      [int64],
      expiresAt:        [int64],
      startsAt:         [int64],
      context:          [json],  
      service:          [gcm|apns],
      filters:          [json],  
      metadata:         [json],  
      csvPath:          [string],
      templateName:     [string],
      pastTimeStrategy: [null|string],
      status:           "stopped",
      appId:            [uuid],
      createdBy:        [string],
      createdAt:        [int64],
      updatedAt:        [int64],
      controlGroup:        [float],
      controlGroupCsvPath: [string]
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  It will return an error if there are missing or invalid parameters.

  • Code: 422

  • Content:

    {
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "reason": [string]
    }
    

Resume Job

PUT /apps/:appId/jobs/:jobId/resume

Resumes the job that has id jobId.

• Payload

  {}
  

• Success Response

  • Code: 201

  • Content:

    {  
      id:               [uuid],
      totalBatches:     [null|int],
      completedBatches: [int],
      totalUsers:       [null|int],
      completedUsers:   [int],
      completedTokens:  [int],
      dbPageSize:       [int],   
      localized:        [boolean],
      completedAt:      [int64],
      expiresAt:        [int64],
      startsAt:         [int64],
      context:          [json],  
      service:          [gcm|apns],
      filters:          [json],  
      metadata:         [json],  
      csvPath:          [string],
      templateName:     [string],
      pastTimeStrategy: [null|string],
      status:           null,
      appId:            [uuid],
      createdBy:        [string],
      createdAt:        [int64],
      updatedAt:        [int64],
      controlGroup:        [float],
      controlGroupCsvPath: [string]
    }
    

• Error Response

  It will return an error if no x-forwarded-email header is specified

  • Code: 401

  It will return an error if there are missing or invalid parameters or if the job previous status was not [paused|circuitbreak].

  • Code: 422

  • Content:

    {
      "reason": [string]
    }
    

  • Code: 500

  • Content:

    {
      "reason": [string]
    }