Predict API (Beta)

/v1/predict is a Beta endpoint design for cases where SuggestAPI should return the best next action, not just the best matching suggestion.

Use it for experiences like:

• SaaS navigation search
• intent-driven search bars
• action-first product discovery
• deep-link routing from fuzzy user input

What makes it different

• /v1/typeahead returns fast prefix suggestions
• /v1/autocomplete returns ranked suggestion objects
• /v1/predict returns a primary predicted action plus alternatives

The goal is to answer: “What should the user do next?”

Endpoint

POST /v1/predict

Authentication

Use a SuggestAPI key:

x-api-key: <public-or-private-key>

Request body

{
  "index": "products",
  "query": "billng setings",
  "limit": 5,
  "user_id": "user_123",
  "filters": {
    "plan": ["growth"]
  },
  "context": {
    "surface": "global-search",
    "page_type": "dashboard",
    "locale": "en",
    "device": "desktop"
  },
  "allowed_types": ["destination", "intent", "product", "category"],
  "include": {
    "alternatives": true,
    "supporting_suggestions": true,
    "debug": false
  }
}

Recommended request fields

• index: target index ID
• query: raw user input
• limit: max number of alternative predictions
• user_id: optional personalization hook
• filters: optional exact or range filters
• context: optional UI and request context
• allowed_types: limit prediction classes for a given surface
• include: toggle alternatives, supporting suggestions, and debug data

Response shape

{
  "query": "billing settings",
  "original_query": "billng setings",
  "corrected_query": "billing settings",
  "mode": "predict",
  "prediction": {
    "type": "destination",
    "label": "Billing Settings",
    "action": {
      "kind": "navigate",
      "target": "/settings/billing",
      "method": "GET"
    },
    "entity": {
      "id": "settings_billing",
      "object": "destination"
    },
    "confidence": 0.93,
    "reason_codes": ["spell_corrected", "intent_match", "behavioral_boost"]
  },
  "alternatives": [
    {
      "type": "destination",
      "label": "Manage Subscription",
      "action": {
        "kind": "navigate",
        "target": "/settings/billing/subscription",
        "method": "GET"
      },
      "confidence": 0.81
    },
    {
      "type": "intent",
      "label": "Update Payment Method",
      "action": {
        "kind": "navigate",
        "target": "/settings/billing/payment-method",
        "method": "GET"
      },
      "confidence": 0.77
    }
  ],
  "supporting_suggestions": [
    {
      "id": "settings_billing",
      "type": "destination",
      "title": "Billing Settings",
      "score": 0.93
    }
  ],
  "debug": null
}

Prediction types

Suggested Beta types:

• destination
• intent
• product
• category
• content
• workflow

Action object

Each top prediction should include a machine-usable action object.

Beta action kinds

• navigate
• search
• apply_filter
• start_workflow

Recommended MVP scope:

• ship navigate first
• add more action kinds only when the UI contract is stable

How it fits the current platform

/v1/predict should be built on top of the existing SuggestAPI stack:

1. normalize the query
2. correct spelling
3. expand synonyms
4. run autocomplete-style retrieval and ranking
5. optionally apply personalization with user_id
6. optionally apply graph and recommendation signals
7. map top candidates into prediction objects
8. return one primary prediction plus alternatives

This keeps predict as a high-level orchestration layer instead of a disconnected second search engine.

Schema support

To support predict cleanly, indexes should be able to define action mappings and intent rules.

Example shape:

{
  "predict": {
    "enabled": true,
    "default_types": ["destination", "product", "intent"],
    "action_mappings": {
      "destination": {
        "target_field": "route",
        "label_field": "title"
      },
      "product": {
        "target_field": "product_url",
        "label_field": "title"
      }
    },
    "intent_rules": [
      {
        "intent": "billing_settings",
        "match_terms": ["billing", "payment", "subscription", "invoice"],
        "target": "/settings/billing",
        "label": "Billing Settings",
        "type": "destination"
      }
    ]
  }
}

Beta guidance

Because this endpoint is still Beta, teams should expect the contract to evolve in these areas:

• prediction type taxonomy
• action object fields
• schema-level predict configuration
• how alternatives and supporting suggestions are blended

Use it when you want to validate the product shape and UX contract before locking down a stable public API version.