Skip to Content
AeroSearch Docs
Quickstarts

Go quickstart

Call Collection search from Go stdlib; sdk-go is planned post-v1.

Goal: issue POST /v1/collections/{collection}/search with the Go standard library and receive HTTP 200 in under five minutes. The public sdk-go package is planned post-v1; the wire contract is stable today.

Create a Collection in the Console. Choose public for anonymous search or private to grant nobody access until each Document supplies an ACL. Set AEROSEARCH_BASE_URL to the Cell search host and AEROSEARCH_COLLECTION to its id. Set AEROSEARCH_INGEST_URL to the ingest-api host and AEROSEARCH_ADMIN_KEY to an admin-scoped key in your server environment. documents:batch currently requires admin scope; ingest-scoped keys await WP-13. Never expose this key in a browser.

Ingest and search use separate URLs until WP-15 provides one public edge.

# generated-from-contract: contracts/openapi/v1.yaml
curl --fail-with-body "$AEROSEARCH_INGEST_URL/v1/collections/$AEROSEARCH_COLLECTION/documents:batch" -H "Authorization: Bearer $AEROSEARCH_ADMIN_KEY" -H 'Content-Type: application/x-ndjson' --data-binary '{"op":"upsert","doc":{"external_id":"hello","title":"Hello search","body":[{"type":"paragraph","text":"Your first imported Document."}]}}'

The Collection already has accepted Schema, Index Profile and Ranking Profile versions. Poll GET $AEROSEARCH_INGEST_URL/v1/collections/$AEROSEARCH_COLLECTION/syncs/{sync_id} using the returned sync_id and AEROSEARCH_ADMIN_KEY. accepted means intake succeeded; wait for completed and stats.searchable: 1 before searching. A failed Sync names each failed external_id and error_class; follow errors_cursor.next with ?errors_cursor=… for more errors. Check visibility_warnings if a private Document grants nobody access.

Set AEROSEARCH_API_KEY to a search-scoped key before querying.

# generated-from-contract: contracts/openapi/v1.yaml
curl --fail-with-body "$AEROSEARCH_BASE_URL/v1/collections/$AEROSEARCH_COLLECTION/search" -H "Authorization: Bearer $AEROSEARCH_API_KEY" -H 'Content-Type: application/json' -d '{"query":"Hello search"}'

A Document can override the Collection choice with "acl":{"allow_anonymous":true}, or a private ACL such as "acl":{"allow_users":["idn_…"]}. Principal ids come from the Identity Graph; search keys alone only see anonymous Documents. An explicit "acl":{} grants nobody access, even on a public Collection.

Sample

// generated-from-contract: contracts/openapi/v1.yaml
// Go stdlib — searchCollectionPost
// POST /v1/collections/col_help/search  (SearchRequest from contracts/openapi/v1.yaml)
// packages/sdk-go is planned post-v1; the wire contract is stable today.

package main

import (
	"bytes"
	"fmt"
	"io"
	"encoding/json"
	"strings"
	"net/url"
	"net/http"
	"os"
)

func main() {
	base := os.Getenv("AEROSEARCH_BASE_URL")
	if base == "" {
		base = "https://api.aerosearch.team"
	}
	key := os.Getenv("AEROSEARCH_API_KEY")
	if key == "" {
		key = "ask_YOUR_PROJECT_SEARCH_KEY"
	}
	collection := os.Getenv("AEROSEARCH_COLLECTION")
	if collection == "" { collection = "col_help" }
	base = strings.TrimSuffix(strings.TrimRight(base, "/"), "/v1")
	body := []byte(`{"query":"reset password","limit":10}`)
	req, _ := http.NewRequest("POST", base+"/v1/collections/"+url.PathEscape(collection)+"/search", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+key)
	req.Header.Set("Content-Type", "application/json")
	if endUser := os.Getenv("AEROSEARCH_END_USER_TOKEN"); endUser != "" {
		req.Header.Set("X-AeroSearch-End-User-Token", endUser)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != 200 {
        var problem struct { Code string `json:"code"` }
        _ = json.NewDecoder(res.Body).Decode(&problem)
        fmt.Fprintf(os.Stderr, "AEROSEARCH_FAILURE {\"status\":%d,\"code\":%q}\n", res.StatusCode, problem.Code)
        panic("Search failed")
    }
	if _, err := io.Copy(os.Stdout, res.Body); err != nil { panic(err) }
}

Verify

From this repository, the local double verification executes the generated sample:

AEROSEARCH_BASE_URL=http://127.0.0.1:4418 AEROSEARCH_API_KEY=ask_search AEROSEARCH_COLLECTION=col_quickstart \
node tests/harness/quickstarts-daily/run.mjs go

On this page