> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygravity.com/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 | Host | Purpose |
| - | - | - |
| `POST /api/v1/ad` | `server.trygravity.ai` | Fetch a contextually matched ad. Primary surface. |
| `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:

```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.com) 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,"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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.