API docs by Redocly

MARS (1.0)

Download OpenAPI specification:

Mozilla Ad Routing Service

Get Unified API ads

header Parameters
X-User-Agent
string

For OHTTP requests, the X-User-Agent header must be populated with a valid User Agent string. This string will typically be acquired from a /v1/ads-preflight response.

For non-OHTTP requests, the header should be omitted.

X-Geo-Location
string^(\d+)?,(\w+)?,(\w+)?$
Example: 506,MA,US

For OHTTP requests, the X-Geo-Location header must be populated with a valide geo location string. This string will typically be acquired from a /v1/ads-preflight response.

For non-OHTTP requests, the header should be omitted.

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": [
    ]
}

Preflight request for OHTTP callers

This endpoint is used to obtain information that OHTTP callers will need to include in OHTTP requests to the /v1/ads endpoint.

Responses

Response samples

Content type
application/json
{
  • "geoname_id": "6077243,6252001",
  • "geo_location": "506,MA,US",
  • "normalized_ua": "string"
}

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

Get attribution reporting configuration

The attribution reporting configuration is returned for the partner ID specified in the URL.

query Parameters
partner_id
required
string <uuid>
Example: partner_id=295beef7-1e3b-4128-b8f8-858e12aa660b

The ID of the partner.

Responses

Response samples

Content type
application/json
{
  • "task_id": "pL9iVhsLWNFb_W044YEbdOYC5y5_RZlPJZovrlk-8Vs",
  • "vdaf": "histogram",
  • "bits": 0,
  • "length": 10,
  • "time_precision": 3600,
  • "default_measurement": 0
}

(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
{}