Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trygravity.ai/llms.txt

Use this file to discover all available pages before exploring further.

Gravity’s public API is intentionally small:
EndpointPurpose
POST /api/v1/adFetch a contextually matched ad. Primary surface.
POST /api/v1/ad/summaryFetch an ad matched to a conversation summary instead of raw messages.
POST /api/v1/ad/non-contextualFetch an ad without conversation context (e.g. page-load ads).
POST /api/v1/bidTwo-phase flow: get a bid decision without generating creative.
POST /api/v1/renderTwo-phase flow: render creative for a previously won bid.
POST /api/v1/leadSubmit a lead form response for an ad.
GET /healthAvailability 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.