Skip to main content
POST
Send the recent conversation messages and get back ads that match the conversation, with ad text that the engine writes for it. For the terms on this page, see Core concepts.

Headers

string
required
Your Gravity API key in the format Bearer YOUR_API_KEY.
string
Optional. Browsers with Global Privacy Control turned on send Sec-GPC: 1. When the value is 1, the engine serves contextual ads only, the same as consent.gpc: true.

Body

array
required
The conversation history: an array of {role, content} objects. Both values are strings. The engine uses the most recent messages to match ads. This field is required by default.
string
required
The ID of the conversation. Gravity uses it for frequency limits, experiment groups, and reports. Use one stable value for each chat thread.If the Gravity pixel is on the page and you use @gravity-ai/api 1.1.7 or later, gravityContext() uses the pixel session ID (gr_sess_ prefix) when you do not pass a sessionId. The pixel session ends after 30 minutes with no activity, or after 1 day. To use your own session scope, pass your own sessionId.
array
required
The ad slots to fill: 1 to 10 placements in each request. The response has at most one ad for each placement.
object
Optional. Data about the user for targeting and attribution. All fields are optional. The engine accepts other fields too and stores them as request context.
object
Optional. Usage for one model call behind a reply, not cumulative totals for the conversation, session or user. It lets the dashboard show model cost next to earnings. Malformed values are ignored without failing the request. See Report model usage.The snake_case keys from provider usage objects also work: input_tokens / output_tokens and prompt_tokens / completion_tokens. Report one model response per ad request: the reply the ad is shown with, or the previous reply if you request the ad before the reply finishes. See Understand what your users earn you.
object
Data about the end user’s device. Send ip and ua in each request. Gravity uses them for fraud and bot detection, and for the Device and Geography reports in your dashboard. The browser SDK collects them through gravityContext().
If you call the API from your server, forward the device object that the client collected. If you do not, the request carries the IP address and User-Agent of your server, not of the end user.
The engine also reads timezone, locale, browser, device_model, region, and city, and stores other fields as request context. A native app or other client with no browser must send its real client User-Agent (for example CFNetwork/Darwin, okhttp, or ktor-client) and the end user’s IP address. See Request ads → Device signals.
number
Optional. The minimum relevance threshold, from 0.0 to 1.0. An explicit value, including 0, overrides your saved Network ads default in Ad settings → Relevance for this request. If omitted or null, the saved default applies; if neither is set, the system default applies. Account-enforced overrides, network quality requirements, and blocked advertisers still apply.This threshold is independent of your Index relevance and sponsorship preference. Saved changes normally reach network ad serving within five minutes. The SDKs send 0.2 by default, which counts as an explicit request value; omit relevancy from the request to use your saved default.
array
Optional. Topics that ads must not match, for example ["politics"].
boolean
default:"false"
Optional. When true, the engine returns test ads and does not bill or count them. The SDKs send the opposite of their production setting.
boolean
default:"false"
Optional, for test requests only (testAd: true). When true, the engine returns a default test ad instead of a 204. Use it to build your UI.
string
Optional, for test requests only (testAd: true). Makes the engine return a sample of one ad format, so that you can build and check your UI.Send alwaysReturn: true too to get an ad in each response. With "image", send adLayout ("image_left", "image_right", or "image_top") to see one layout. The default is "image_right". Live requests ignore adLayout, because Gravity selects the layout for each publisher.
boolean
Optional. Tells the engine if your client can draw server-rendered designs (renderer_spec). Send false if you draw ads with your own code. If you do not send this field, a specCapabilities value means true. The official SDKs set this field for you.
string
Optional. The type of server-rendered design that your client can draw. The official SDKs set this field for you. The engine ignores values that it does not know.
boolean
Optional. Send true if your client can show Gravity frames in a sandboxed iframe: rich frame ads (iframe) and carousels (carousel). @gravity-ai/api sends true by default (its enableFrames option). The iOS, Android, and Python SDKs don’t send it, because they can’t show frames. React Native can’t show frames either, so set enableFrames: false on the server requests for a React Native app.true alone doesn’t get you a frame. The engine sends a frame only when the ad units of the request include iframe or carousel. Where Gravity hasn’t turned on ad unit settings, Gravity’s settings for your account decide instead. When neither allows a frame, the engine sends another format.
array
Optional. The ad unit types that this request can show, for example ["text", "designer", "image_top"]. It replaces the ad units of every placement in the request (set in the dashboard under Placements, Ad units) for this request only.The engine ignores IDs that it doesn’t know. The engine uses units when you send it, and the ad units of the placements when you don’t. Then it serves a unit from that set that the request can show. Where Gravity hasn’t turned on ad unit settings, the engine ignores this field. See Ad units.
Optional. The privacy and consent choices of the end user. If you do not send this object, the engine works as usual.When gdprApplies is true and the request has no valid tcfString, the engine serves contextual-only ads. It does not process user identifiers for that request. The same occurs when usPrivacy opts out of sale or when gpc is true. Contextual matching needs no personal data, so ads still serve.For gpp, the engine reads the US national section and the US state sections that apply. It serves contextual-only ads when one of them opts the user out of sale, sharing, or targeted advertising, sends GPC, or records no consent for a known child’s data. A sale opt-out in the uspv1 section has the same result. An EU TCF section in gpp counts as the tcfString, and a gppSid that includes 2 means GDPR applies. If the engine can’t decode gpp, it serves contextual-only ads.

Response

When the engine finds a match, the response is HTTP 200 with a JSON array of ad objects. The array has at most one ad for each placement in the request.
The SDKs put this array in a result object: { ads, status, elapsed } in JavaScript and AdResult(ads, status, elapsed_ms, ...) in Python. The API response does not contain this object.

Ad object

The response does not include fields that have no value.
Always use clickUrl for ad links, not url. Load impUrl when the ad becomes visible. If you do not, Gravity cannot count the click or the impression, and you do not get paid for it.

renderer_spec

Gravity sets the server-rendered design for each placement. When a design is available for your client, the response includes renderer_spec. If not, the SDK uses its built-in card. The official SDKs handle this for you. To get a custom placement design, contact support@trygravity.com.

Image ads

When the campaign has a product image, the ad includes brandImage (the image URL) and a renderer_spec with an image card. The image card shows the image on one side and the text on the other side. An ad with no image has brandImage: "" and shows as the usual text card.
  • Official SDKs (@gravity-ai/react 1.3.0 and later, @gravity-ai/ui 0.3.0 and later, @gravity-ai/react-native 0.2.0 and later) draw the image card for you. Older versions ignore it and show the text card.
  • Direct API integrations can ignore renderer_spec and draw their own design from brandImage, title, adText, cta, and clickUrl.
  • Gravity selects the layout (image_left, image_right, or image_top) for each publisher. You do not need to send a value.
To get an image ad while you build your UI, send these fields in a request:

Experiment fields

When an experiment is active, the ad object also includes these fields: The impUrl and clickUrl values already contain the experiment data, so the reports join the data for you.

No ad available

The response is HTTP 204 No Content with an empty body in these cases:
  • No ad matches the conversation.
  • The engine identifies the request as a bot.
  • The request takes more than 4 seconds.
  • The engine has an error that it cannot recover from.
There is no JSON body. Hide the ad slot in your UI.

Errors

To fix a 400, send the conversation messages. See Request ads. To recover from a 429, wait for the number of seconds in Retry-After, then try again. The daily limit resets at reset_at, midnight UTC. See Request limits.