← Back to API docs

Search API

The Search API provides managed full-text search with App Engine Search semantics: structured documents; text, atom, number, date, and geo fields; a boolean query language; facets; sorting; and pagination. All paths below are relative to a search instance you provision in the console.

Authentication and base URL

Send requests to https://api.altengine.net with an organization API key as a bearer token. Reads require a read grant, writes a write grant, and deletes a full grant — see Authentication.

Authorization: Bearer ae_yourkeyid.your-api-key-secret

Every path is scoped to an instance: /v1/search/{instance}/…. Within an instance, documents live in named indexes. An optional namespace partitions data for multi-tenancy; set it with a ?namespace= query parameter or an X-Namespace header (the default namespace is empty).

Endpoints

Documents

A document has a string id, an optional numeric rank (used as the default sort — descending — when a query specifies no sort), a list of fields, and an optional list of facets. Fields are multi-valued and dynamic: two documents in the same index may carry different fields.

{
  "id": "f1",
  "rank": 12345,
  "fields": [
    { "name": "title",    "type": "text",   "value": "Up in the Air" },
    { "name": "genre",    "type": "atom",   "value": "drama" },
    { "name": "rating",   "type": "number", "value": 4 },
    { "name": "released", "type": "date",   "value": "2009-12-04" },
    { "name": "loc",      "type": "geo",    "value": { "lat": 37.77, "lng": -122.41 } }
  ],
  "facets": [
    { "name": "genre", "type": "atom",   "value": "drama" },
    { "name": "year",  "type": "number", "value": 2009 }
  ]
}

Field types

Put documents

Send up to 200 documents per request. Putting a document with an existing id replaces it. The response returns the ids written.

curl -X PUT https://api.altengine.net/v1/search/catalog/indexes/films/documents \
  -H "Authorization: Bearer $ALTENGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "documents": [ { "id": "f1", "fields": [ { "name": "title", "type": "text", "value": "Up in the Air" } ] } ] }'

# → { "ids": ["f1"] }

Get, list, and delete

# Get one document
GET /v1/search/catalog/indexes/films/documents/f1
# → { "document": { … } }

# List documents (id order). Params: start_id, include_start, limit, ids_only
GET /v1/search/catalog/indexes/films/documents?limit=50
# → { "documents": [ … ] }   (or { "ids": [ … ] } when ids_only=true)

# Batch delete by id (requires a full grant)
POST /v1/search/catalog/indexes/films/documents/delete
{ "ids": ["f1", "f2"] }
# → { "deleted": 2 }

Search

Post a search request to an index. Only query is required; an empty query matches all documents.

{
  "query": "genre:comedy rating > 3",
  "limit": 20,
  "offset": 0,
  "ids_only": false,
  "returned_fields": ["title", "rating"],
  "sort": [{ "expr": "rating", "desc": true, "default": 0 }],
  "facet_discover": 5,
  "facet_refinements": [{ "name": "genre", "value": "scifi" }],
  "total_hits_accuracy": 1000
}

Request fields

Response

{
  "total_hits": 42,
  "total_hits_exact": true,
  "returned": 1,
  "results": [
    {
      "id": "f1",
      "rank": 12345,
      "score": 1.7,
      "document": {
        "id": "f1",
        "fields": [
          { "name": "title", "type": "text", "value": "Up in the Air" }
        ]
      }
    }
  ],
  "cursor": "eyJvIjoyMH0",
  "facets": [
    {
      "name": "genre",
      "type": "atom",
      "values": [
        { "value": "drama",  "count": 12 },
        { "value": "comedy", "count": 8 }
      ]
    }
  ]
}

total_hits is the number of matches, counted exactly only up to total_hits_accuracy. When total_hits_exact is false, total_hits is a lower bound — render it as "N+". Pagination is independent of the count: a cursor is present whenever more pages remain, so keep following it until it is absent.

Query language

The query language mirrors App Engine's Search syntax. Terms are combined with implicit AND.

Facets

Attach facets to documents to enable faceted navigation. Set facet_discover in a search to have altengine return the most common facet values over the matches, then pass the ones a user picks back as facet_refinements to narrow the result set. Atom facets return value counts; number facets return half-open [min, max) ranges with counts.

Limits

Index and document ids must be printable ASCII, may not start with !, and may not use the reserved __*__ form.