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. This array also carries suggestions the user dismissed rather than filled — see Advanced.
`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).
`data.additional_context`	`object (free-form JSON)`	Optional. Free-form JSON describing what your app knows about this request — a user profile, recent activity, workspace or session state. The server conditions suggested parameters and option values on it (values it names are listed first) but never interprets or stores it. Capped at 2000 bytes compacted; treated strictly as data. See Advanced.
`data.identified_params`	`IdentifiedParam[]`	Optional. Your echo of the params inferred from freely typed text on the previous response — every data.input[] entry that came back with source: "identified". Unlike completed_params these are tentative: they can be revised or dropped on the next turn, and their text stays inline in raw_query rather than being replaced by a placeholder. Echoing them back keeps that reading stable across keystrokes.
`data.identified_params[].type`	`string`	The inferred param's type, as the server sent it in data.input[].type.
`data.identified_params[].value`	`string`	The literal text in raw_query the server read as that param's value.
`data.recently_suggested`	`RecentlySuggested[]`	Optional. The suggestions that were on screen while the user typed the trailing text they haven't finished — a hint that lets the server read typed words as an answer to a suggestion instead of re-suggesting it. Send it only while such text is unresolved; omit the field otherwise. See Advanced for when to start and stop.
`data.recently_suggested[].type`	`string`	The relayed suggestion's type, exactly as the server sent it in data.suggestions[].type (e.g. "special_instructions").
`data.recently_suggested[].text`	`string`	The relayed suggestion's display text, as the server sent it in data.suggestions[].text — not the words the user typed.
`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, but a value that isn't a valid UUIDv4 is rejected with a 400 rather than replaced.
`meta.language`	`string (e.g. "en-US")`	Optional. BCP-47 locale (e.g. "en-US", "pt-BR"). The server localizes suggestions when possible.
`meta.client_version`	`string`	Optional. Your client's version string, recorded with the request so support can correlate behavior with a specific build of your integration.

{
  "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.input[].state`	`"completed" \| "in_progress" \| "need_confirmation"`	Whether the segment is finished ("completed"), still being filled ("in_progress"), or read with low enough confidence that it's worth confirming with the user ("need_confirmation").
`data.input[].source`	`"selected" \| "identified"`	Confidence tier for this segment. Absent or "selected" means the segment echoes a param you sent in completed_params, so it's settled. "identified" means it was inferred from text the user typed freely — treat it as revisable, and echo it back in the next request's identified_params.
`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[].required`	`boolean`	Whether this parameter must be filled before the query is complete. Optional suggestions can be skipped; is_ready only waits on the required ones.
`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…".
`data.is_ready`	`boolean`	True once the query has every required parameter filled — the signal to enable your submit affordance. Suggestions may still be returned alongside it; they're optional refinements at that point.
`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"
  }
}