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 }
- Code:
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 specifiedCode:
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] }
- Code:
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 specifiedCode:
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] }
- Code:
Delete App¶
DELETE /apps/:appId
Deletes the app that has id appId
.
Success Response
- Code:
204
- Code:
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] }
- Code:
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 specifiedCode:
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] }
- Code:
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 specifiedCode:
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] }
- Code:
Delete Template¶
DELETE /apps/:appId/templates/:templateId
Deletes the templaye that has id templateId
.
Success Response
- Code:
204
- Code:
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] }
- Code:
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 specifiedCode:
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] }
- Code:
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 specifiedCode:
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] }
- Code:
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] }
- Code:
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] }
- Code: