API docs by Redocly

MARS (1.0)

Download OpenAPI specification:

Mozilla Ad Routing Service

Get Unified API ads

Request Body schema: application/json
required
context_id
required
string <uuid>

An identifier for the user's context.

required
Array of objects (AdPlacement) non-empty

A list of AdPlacement objects, specifying where ads should be placed.

blocks
Array of strings

A list of strings specifying blocked content. The string values come from the block_key field in returned ads.

object (Consent)

An object to specify consent specifiers for this request

Responses

Request samples

Content type
application/json
{
  • "context_id": "12347fff-00b0-aaaa-0978-189231239808",
  • "placements": [
    ],
  • "blocks": [
    ],
  • "consent": {
    }
}

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

Report ad interaction

Interaction callback URLs are returned in an ad response. When the corresponding action on the client occurs, those URLs should be fetched.

query Parameters
data
required
string

Encoded interaction data

placement_id
string

Identifier representing the instance of the placement (different identifier than placement from the ad request), used only in special situations.

position
string

Identifier indicating the position of the placement (optional). May be a string or numeric. If a numeric index is used it must be 0-based.

reason
string
Enum: "inappropriate" "not_interested" "seen_too_many_times"

Identifier indicating the reason for the ad reporting interaction. Used only for, and required with, the 'report' action.

Responses

Record client events

This endpoint can be used to persist a prometheus metric.

query Parameters
event
string
Enum: "init" "error"

Identifier of the event to capture.

Responses

Delete user data

Delete any data persisted associated with a given context_id.

Request Body schema: application/json
required
context_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "context_id": "12347fff-00b0-aaaa-0978-189231239808"
}

Get ad image

Proxies an ad image from an encoded URL. Encoded image URLs are returned in an ad response, calls to this endpoint shouldn't be constructed manually.

query Parameters
image_data
required
string

Encoded ad image url

Responses

(legacy) Get sponsored content

Get a list of spocs based on region and pocket_id. The IP address is used to deduce a rough geographic region, for example "Texas" in the U.S. or "England" in the U.K. The IP is not stored or shared to preserve privacy.

query Parameters
site
integer <int32> [ 1 .. 2147483647 ]
Example: site=2500

override siteId in ad decision requests

region
string

override region in keywords of ad decision requests for testing

country
string

override country in keywords of ad decision requests for testing

Request Body schema: application/json
required
version
required
integer <int32> [ 1 .. 2 ]

API version

consumer_key
required
string

Identifies that the request is coming from Firefox.

pocket_id
required
string^\{[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}\...

ID that uniquely identifies a session.

Array of objects (Placement)
site
integer <int32> [ 1 .. 2147483647 ]

override siteId in ad decision requests

country
string

override country in keywords of ad decision requests for testing

region
string

override region in keywords of ad decision requests for testing

Responses

Request samples

Content type
application/json
Example
{
  • "version": 1,
  • "consumer_key": "40249-e88c401e1b1f2242d9e441c4",
  • "pocket_id": "{12345678-8901-2345-aaaa-bbbbbbcccccc}"
}

Response samples

Content type
application/json
{
  • "settings": {
    },
  • "__debug__": { },
  • "property1": [
    ],
  • "property2": [
    ]
}

(legacy) Delete a user's personal data

Used when a user opts-out of sponsored content to delete the user's data.

Request Body schema: application/json
required
pocket_id
required
string

ID that uniquely identifies a session.

Responses

Request samples

Content type
application/json
{
  • "pocket_id": "{12345678-8901-2345-aaaa-bbbbbbcccccc}"
}

(legacy) Get tiles

Responses

Response samples

Content type
application/json
{}