API Reference

The Gravity HTTP API — what’s public, how to authenticate, what to call.

Gravity’s public API is intentionally small:

Endpoint	Purpose
POST /api/v1/ad	Fetch a contextually matched ad. Primary surface.
POST /api/v1/ad/group	One ad shown to multiple viewers in a group chat (up to 5). Per-viewer tracking.
POST /api/v1/ad/summary	Fetch an ad matched to a conversation summary instead of raw messages.
POST /api/v1/ad/non-contextual	Fetch an ad without conversation context (e.g. page-load ads).
POST /api/v1/bid	Two-phase flow: get a bid decision without generating creative.
POST /api/v1/render	Two-phase flow: render creative for a previously won bid.
POST /api/v1/lead	Submit a lead form response for an ad.
POST /ad-feedback	Submit end-user feedback on a served ad. Lives on platform.trygravity.ai.
GET /health	Availability probe.

If you’re using an SDK, you’re already hitting /api/v1/ad under the hood — the SDK is a thin wrapper that handles context preparation, retry, and impression tracking.

Base URL

https://server.trygravity.ai

Authentication

Pass your Gravity API key as a Bearer token:

curl -X POST https://server.trygravity.ai/api/v1/ad \
  -H "Authorization: Bearer $GRAVITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Grab the key from your dashboard under Settings → Platform Settings (for AI platforms) or Settings → Organization (for advertisers).

Health check

curl https://server.trygravity.ai/health
# → {"status":"ok","ready":true}

Returns 200 with {"status":"ok","ready":true} in the steady state, or 503 with {"status":"starting","ready":false} while the server is still warming up.

Useful for uptime probes. Doesn’t count against rate limits.

What’s next

Contextual ads endpoint

Full request / response reference for POST /api/v1/ad.

Group ads endpoint

One ad, multiple viewers — for group chat integrations.

Ad feedback

Let users react to ads with thumbs-up / thumbs-down.