API Reference — HTTP API — AI Autocomplete Docs

Endpoint

POSThttps://api.ai-autocomplete.com/api/suggest

Headers

Prop	Type	Description
`Authorization`Required	`"Bearer <token>"`	Public key, secret key, or short-lived access token. All three are sent the same way.
`Content-Type`Required	`"application/json"`	Always application/json.

Request body

Top-level object with two halves — data (the autocomplete state) and meta (request envelope).

Autocomplete is a loop. On every keystroke send the current raw_query plus the running completed_params list. When the user picks an option from the previous response's suggestions, your client (a) replaces the chosen text in raw_query with a placeholder token like "{{TYPE_1}}" (the type name uppercased + a per-type counter), and (b) appends an entry to completed_params recording { placeholder, type, text }. The server resolves placeholders against completed_params to reconstruct the user's intent. See the Getting Started worked example.

Prop	Type	Description
`data.raw_query`	`string`	The query you send, with each picked value replaced by its {{TYPE_N}} placeholder (e.g. "Create a {{TYPE_1}}") — distinct from the display string the user sees, which keeps the real values. completed_params maps each placeholder back to its text. The server accepts an empty string for the initial-state request.
`data.completed_params`	`CompletedParam[]`	One entry per placeholder token in raw_query. Each entry maps a placeholder (e.g. "{{TYPE_1}}") to its type and the chosen text. Omit when raw_query has no placeholders.
`data.completed_params[].placeholder`	`string`	Token in raw_query this entry fills — e.g. "{{TYPE_1}}".
`data.completed_params[].type`	`string`	The suggestion type that produced this param. Tenant-specific (e.g. "type", "contact", "automation").
`data.completed_params[].text`	`string`	Literal text shown to the user for this filled placeholder. Omit when you don't want the server to see the value (PII masking — the server then only sees the type).
`meta.request_id`Required	`string (UUID)`	UUIDv4. Echoed back in the response for log correlation.
`meta.request_at`Required	`string (ISO 8601)`	ISO 8601 timestamp with timezone (e.g. "2026-05-26T18:30:00Z") representing when the client assembled the request. Echoed back so the client can detect stale responses.
`meta.session_id`	`string (UUIDv4)`	UUIDv4 grouping requests from the same user session — reuse across keystrokes, rotate after submit. The server auto-generates one and echoes it back if you don't send it.
`meta.language`	`string (e.g. "en-US")`	Optional. BCP-47 locale (e.g. "en-US", "pt-BR"). The server localizes suggestions when possible.

{
  "data": {
    "raw_query": "Create a {{TYPE_1}} for {{CONTACT_1}}",
    "completed_params": [
      { "placeholder": "{{TYPE_1}}", "type": "type", "text": "email" },
      { "placeholder": "{{CONTACT_1}}", "type": "contact", "text": "Alex" }
    ]
  },
  "meta": {
    "request_id": "5a0d1c1e-1b3f-4a9e-8a4f-001a1c3b7d20",
    "request_at": "2026-05-26T18:30:00Z",
    "session_id": "9e5b7c0e-2a1b-4f8e-9c2d-3e4f5a6b7c8d"
  }
}

Response body

Mirrors the request shape — data (autocomplete output) and meta (echoed envelope).

Prop	Type	Description
`data.raw_query`	`string`	Echo of the raw_query you sent.
`data.input[]`	`InputSegment[]`	Server-parsed view of the current input — an "intent" segment for the user-typed prefix plus one segment per completed param. null when raw_query has no placeholders.
`data.input[].type`	`string`	Segment type. "intent" for the user-typed prefix; otherwise the suggestion type that produced the filled placeholder (e.g. "type", "contact").
`data.input[].text`	`string`	For "intent" segments, the user-typed prefix (text before the first placeholder in raw_query). For filled-param segments, the placeholder token itself (e.g. "{{TYPE_1}}").
`data.suggestions[]`	`Suggestion[]`	Suggestions for what comes next — prompt hints, or selectable options the user can pick from.
`data.suggestions[].type`	`string`	Suggestion type. "placeholder" is the initial prompt-hint suggestion; other values are param names produced by the model (e.g. "type", "automation", "contact").
`data.suggestions[].text`	`string`	Label or hint for this suggestion. For "placeholder" type suggestions, the prompt to display in the input (e.g. "Create a"). For other suggestions, the param's name (e.g. "type", "automation"). Not a {{TYPE_N}} token — your client mints those when constructing the next request.
`data.suggestions[].options`	`Option[]`	Tappable options for this suggestion. Omitted when there are no options to choose from.
`data.suggestions[].options[].text`	`string`	Display text for the option.
`data.suggestions[].options[].is_tappable`	`boolean`	Whether the option can be selected directly. False on hint/fallback rows like "or type something else…".
`meta.request_id`	`string`	Echo of the request_id you sent. Use for log correlation.
`meta.request_at`	`string (ISO 8601)`	ISO 8601 timestamp when the server returned.
`meta.session_id`	`string (UUIDv4)`	Echo of the session_id you sent, or the one the server generated if you didn't send one.

{
  "data": {
    "raw_query": "Create a {{TYPE_1}} for {{CONTACT_1}}",
    "input": [
      { "type": "intent",  "text": "Create a",     "state": "completed" },
      { "type": "type",    "text": "{{TYPE_1}}",    "state": "completed" },
      { "type": "contact", "text": "{{CONTACT_1}}", "state": "completed" }
    ],
    "suggestions": [
      {
        "type": "automation",
        "text": "automation",
        "required": false,
        "options": [
          { "text": "send draft for review", "is_tappable": true },
          { "text": "schedule for tomorrow", "is_tappable": true }
        ]
      }
    ],
    "is_ready": false
  },
  "meta": {
    "request_id": "5a0d1c1e-1b3f-4a9e-8a4f-001a1c3b7d20",
    "request_at": "2026-05-26T18:30:00Z",
    "session_id": "9e5b7c0e-2a1b-4f8e-9c2d-3e4f5a6b7c8d"
  }
}