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.
Import and search
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