# Getting Started | HTTP API AI Autocomplete Docs

> For the complete documentation index, see [llms.txt](https://ai-autocomplete.com/llms.txt). A markdown version of any page on this site is available by appending `.md` to its URL path — the homepage is at `/index.md`.

Getting Started guide for integrating the AI Autocomplete SDK with HTTP API. Code examples, setup, and API reference.

Source: https://ai-autocomplete.com/docs/http/getting-started

---

Use the HTTP endpoint when an SDK doesn't fit your stack — backend services, alternative languages, or when you're rendering autocomplete UI yourself. When an SDK is available for your platform, it handles refresh, retries, cancellation, and request shaping for you.

## Install with an AI agent

Let your AI coding agent set up the integration and walk you through the two browser steps.

Paste this into your agent. It will scaffold the integration and tell you exactly what to do in the browser to finish setup.

**Agent prompt**

```bash
Install AI Autocomplete using the instructions at https://ai-autocomplete.com/install/http.md
```

Works with Claude Code, Cursor, Windsurf, GitHub Copilot, ChatGPT — any agent that can read URLs and run shell commands. [View the prompt](https://ai-autocomplete.com/install/http.md)

## First request

Hit POST /api/suggest with a Bearer credential. The body has two halves — data (what the user is typing) and meta (request envelope).

**curl**

```bash
curl https://api.ai-autocomplete.com/api/suggest \
  -H "Authorization: Bearer $MAGICX_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": { "raw_query": "Create a" },
    "meta": {
      "request_id": "5a0d1c1e-1b3f-4a9e-8a4f-001a1c3b7d20",
      "request_at": "2026-05-26T18:30:00Z",
      "session_id": "9e5b7c0e-2a1b-4f8e-9c2d-3e4f5a6b7c8d"
    }
  }'
```

On first load, before the user has typed anything, send raw_query: "" to fetch the initial set of suggestions.

-   `request_id` — UUIDv4.
-   `request_at` — ISO 8601 timestamp.
-   `session_id` — UUIDv4. Reuse across keystrokes in one session, rotate after submit.

The server returns suggestions to surface next, plus a parsed view of the input. The completion is iterative — call /api/suggest again on each keystroke, passing the updated raw_query.

**response.json**

```json
{
  "data": {
    "raw_query": "Create a",
    "suggestions": [
      { "type": "placeholder", "text": "Create a" },
      {
        "type": "type",
        "text": "type",
        "options": [
          { "text": "email", "is_tappable": true },
          { "text": "automation", "is_tappable": true },
          { "text": "insight", "is_tappable": true }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "5a0d1c1e-1b3f-4a9e-8a4f-001a1c3b7d20",
    "request_at": "2026-05-26T18:30:00Z",
    "session_id": "9e5b7c0e-2a1b-4f8e-9c2d-3e4f5a6b7c8d"
  }
}
```

## After the user picks an option

Say the user picks "email" from the type options above. Your client builds the next request by (a) substituting "email" with the placeholder token "{{TYPE_1}}" in raw_query and (b) appending an entry to completed_params recording the pick. Reuse the same session_id; mint a fresh request_id.

**curl (next request)**

```bash
curl https://api.ai-autocomplete.com/api/suggest \
  -H "Authorization: Bearer $MAGICX_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "raw_query": "Create a {{TYPE_1}}",
      "completed_params": [
        { "placeholder": "{{TYPE_1}}", "type": "type", "text": "email" }
      ]
    },
    "meta": {
      "request_id": "7f8a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "request_at": "2026-05-26T18:30:00Z",
      "session_id": "9e5b7c0e-2a1b-4f8e-9c2d-3e4f5a6b7c8d"
    }
  }'
```

Placeholder names must be unique within raw_query — the server replaces each one by string match, so duplicates collide. The SDK convention is {{TYPE_N}}: the param's type uppercased (spaces → underscores), then a 1-based per-type counter. First "goal" pick → {{GOAL_1}}; a second "goal" pick → {{GOAL_2}}; a "contact" pick → {{CONTACT_1}}.

## Get a key

Grab a [public key](https://ai-autocomplete.com/account/keys) for client-side use, or a secret key for your backend. Public keys go directly in client code; secret keys must stay server-side.

Security

Never ship a secret key (sk_v1_...) in client code. Use a public key (pk_v1_...) for client apps, or mint short-lived access tokens from your backend — see Authentication.

## What's next

Authentication has the full secret-key + access-token flow. API reference has the complete endpoint spec. Advanced covers token caching, 401 retry, and cancellation patterns.