Getting Started

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

{
  "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 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 for client-side use, or a secret key for your backend. Public keys go directly in client code; secret keys must stay server-side.

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.