> ## 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.

# 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/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:

```bash theme={null}
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](https://app.trygravity.ai) under **Settings → Platform Settings** (for AI platforms) or **Settings → Organization** (for advertisers).

## Health check

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Contextual ads endpoint" icon="code" href="/engine/contextual-ads">
    Full request / response reference for `POST /api/v1/ad`.
  </Card>

  <Card title="Ad feedback" icon="thumbs-up" href="/engine/ad-feedback">
    Let users react to ads with thumbs-up / thumbs-down.
  </Card>
</CardGroup>