Skip to main content
Use the ad serving API to request ads and to send user feedback on ads. For the terms on this page, see Core concepts. To manage an account with code, see the Advertiser Dashboard API and the Publisher Dashboard API. To send conversions from your backend, see the Conversions API (POST /gateway/events).

Endpoints

The SDKs call /api/v1/ad for you. They prepare the request context, record impressions, and return an empty result when a request fails.

Base URL

server.trygravity.com and server.trygravity.ai point to the same load balancer and serve the same engine, so either host works. The SDKs and Gravity’s own services use https://server.trygravity.ai by default. The examples on this page use .com.

Authentication

Each endpoint needs your Gravity API key. Get the key from your dashboard under Settings → Platform Settings (AI platforms) or Settings → Organization (advertisers).
Keep your API key on your server. Do not put it in client code or in a public repository.
For POST /api/v1/ad, send the key as a Bearer token:
For POST /ad-feedback, send the key in the X-API-Key header. See Ad feedback.

Common errors

Each endpoint page lists its own errors.

Health check

When the server is ready, the response is 200:
While the server starts, the response is 503 with {"status": "starting", "ready": false}. Use this endpoint for uptime checks. Rate limits do not apply to it.

Next steps

Contextual ads endpoint

The full request and response reference for POST /api/v1/ad.

Ad feedback

Let users react to ads with a thumbs up or a thumbs down.