API Reference - Gravity

Gravity’s public API is intentionally small:

Endpoint	Host	Purpose
`POST /api/v1/ad`	`server.trygravity.ai`	Fetch a contextually matched ad. Primary surface.
`POST /api/v1/lead`	`api.trygravity.ai`	Submit a lead-form response for an ad. The SDK reads this URL off `leadForm.submit_url` — don’t hardcode it.
`POST /ad-feedback`	`platform.trygravity.ai`	Submit end-user feedback on a served ad. Authenticated with `X-API-Key`.
`GET /health`	`server.trygravity.ai`	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,"release_sha":"221d530…"}

Returns 200 with status: "ok", ready: true, and the deployed release_sha 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.

Ad feedback

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

​Base URL

​Authentication

​Health check

​What’s next