# AutoSugges — Call the secret-key-authenticated control-plane API

You are integrating AutoSugges, a hosted autocomplete and list-of-values service. Everything you need is in this message; do not guess at anything it does not state, and do not fetch documentation to fill a gap — ask instead.

## Objective
A correct server-to-server call to /api/v1 under Authorization: Bearer <secret key>, honouring pagination, Idempotency-Key on writes and If-Match on updates, with every error handled by its typed code rather than by guessing from status alone.

## Environment
- Target framework/runtime: AutoSugges control-plane REST API (secret key).
- SDK package: `@autosugges/client`.
- Runtime HTTP API version: `v1`.
- Install: No install: plain HTTPS with a bearer token. Any HTTP client works.

## Prerequisites
- A secret key (sk_live_…) issued once from Dashboard → Applications and stored in your server’s secret manager — never in browser or mobile code.
- This API has no CORS policy and is never called from a browser: it is a server-to-server credential, full stop.
- A list your workspace OWNS to act on — a subscribed list is not writable through this API and most routes will not see it either.

## Values you must supply
- `secretKey` (required, SECRET — server-side only) — placeholder `YOUR_AUTOSUGGES_SECRET_KEY`. A tenant-level credential: it can read, edit and publish every list your workspace owns, with the rights of the data_steward role (list content and publishing — never keys, members, domains or billing), whoever issued it. Treat it like a root password. Revoke it from the dashboard the moment it may have leaked. Source: Dashboard → Applications, shown exactly once at issuance.
- `listId` (required, SECRET — server-side only) — placeholder `YOUR_LIST_ID`. Path segment on every per-list route below. Source: GET /api/v1/lists, or the dashboard.
- `idempotencyKey` (optional, SECRET — server-side only) — placeholder `YOUR_IDEMPOTENCY_KEY`. 1–255 printable ASCII characters. On the three POST routes, remembered per workspace for 24 hours: the identical key with the identical method, path and body replays the original response with Idempotent-Replayed: true instead of re-executing. Reusing it with a different body is refused (422); reusing it while the first call is still in flight is refused (409, retry after 1s). Never send it on a GET. Source: Generated by your own code — a UUID is fine.
- The base URL below is still the literal placeholder `YOUR_RUNTIME_BASE_URL`. Ask the developer for their environment's runtime origin and substitute it; do not invent an autosugges.com hostname.

## Request contract
The publishable key travels as a query parameter (or, for selection reports, a JSON body field) — NOT as an Authorization header. The Authorization header is reserved for the optional access token of a protected list.
- `GET /v1/bootstrap?key=<publishable key>` — Resolves the list identity, the active version hash and the effective query policy for this key. Call once per session before querying. Key placement: `key` query parameter. Headers: `x-request-id`: a per-request correlation id (the SDK mints one automatically); `authorization: Bearer <access token>`: optional, and only for a list whose policy requires a token.
- `GET /v1/query?key=<publishable key>&q=<text>&locale=<optional BCP-47 tag>` — Returns the pre-ranked suggestions for one query. Key placement: `key` query parameter. Headers: `x-request-id`: a per-request correlation id; `authorization: Bearer <access token>`: optional, as above.
- `POST /v1/selection` — Reports which suggestion the user chose, so ranking can improve. Optional: skipping it degrades ranking quality and nothing else. Key placement: `key` field of the JSON body, alongside `selectionId`, `queryRequestId`, `listId`, `itemId`, `query` and `position`. Headers: `content-type: application/json`; `x-request-id`.

## Policy that arrives from bootstrap — never hardcode these
- `requestId` (string) — Correlation id for this bootstrap call.
- `list.id` (string (UUID)) — The canonical list this key resolves to. Never supplied by the client.
- `activeVersionHash` (string) — The published version currently serving. Compare it to a stored hash to decide whether a cached local copy is stale.
- `queryPolicy.minQueryChars` (number) — Minimum characters before a query is legal. Never below 2, and never hardcoded — a shorter query is rejected and not billed.
- `queryPolicy.debounceMs` (number) — How long to wait after the last keystroke before issuing a query.
- `queryPolicy.defaultResultLimit` (number) — How many suggestions a list returns by default. Informational: the server already returns its ranked set, so the client does not send this back.
- `queryPolicy.rememberLastSelection` (boolean) — Tenant policy for prefilling a previously chosen item. Treat anything other than literal `true` as off.

## What one suggestion looks like
- `itemId` (string) — Stable identifier. Use it as the React/list key.
- `value` (string) — The canonical value — what you store.
- `displayValue` (string) — The locale-resolved label — what you render. Not the same field as `value`.
- `displayOrder` (number) — The owner's configured display order.
- `position` (number) — 1-based position in the returned ranking.
- `ancestors` (array, optional) — The precomputed hierarchy chain, root first, excluding the item itself — `{ itemId, value, displayValue, hierarchyLevel? }`. Use it to auto-fill parent form fields. Absent when the item has no ancestors; never an empty array.

## Implementation steps
1. Send the secret key as a bearer token — Authorization: Bearer <secret key> on every request. A missing, wrong or revoked key, or a disabled workspace, is 401 invalid_key with a WWW-Authenticate: Bearer header — never call this from code you cannot keep secret.
2. Paginate every collection GET — limit (1-100, default 50) and cursor are query parameters; the body is { data, nextCursor, requestId }. Follow nextCursor until it is null — treat a non-null nextCursor as "more pages exist", nothing else.
3. Send Idempotency-Key on every write you might retry — POST /lists, POST /lists/{id}/items and POST /lists/{id}/versions all accept it. Without it, a retried POST after a dropped response can create a duplicate.
4. Send If-Match when you update a list you last read — PATCH /lists/{id} accepts an optional If-Match: <etag> from a prior GET/POST/PATCH response’s ETag header. A stale or mismatched value is refused with 412 and the current ETag, rather than silently overwriting a change you never saw.
5. Publish and read the outcome, not just the status — POST /lists/{id}/versions returns 200 once validation/compile/activation has resolved (state is either active or back to draft with validationErrors listing why), or 202 if it was queued — poll GET /lists/{id}/versions/{versionNumber} in that case.
6. Handle every error by its typed code — The response body is always { code, message, requestId, details?, docsUrl, remediation, retryAfter? }. Switch on code — 401 invalid_key, 404 invalid_list (never 403, even for a list that exists but is not yours), 400 invalid_request with details.fields, 429 rate_limited with a retry-after header.

## Code — `list-and-publish.sh`
```bash
# 1. List the lists your workspace owns.
curl -sS 'YOUR_AUTOSUGGES_APP_ORIGIN/api/v1/lists?limit=50' \
  -H "Authorization: Bearer $AUTOSUGGES_SECRET_KEY"

# 2. Add an item, with an idempotency key so a retried request never double-writes.
curl -sS -X POST 'YOUR_AUTOSUGGES_APP_ORIGIN/api/v1/lists/YOUR_LIST_ID/items' \
  -H "Authorization: Bearer $AUTOSUGGES_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
  -d '{"value": "san-francisco", "displayValue": "San Francisco"}'

# 3. Publish — validates, compiles and activates a new version.
curl -sS -X POST 'YOUR_AUTOSUGGES_APP_ORIGIN/api/v1/lists/YOUR_LIST_ID/versions' \
  -H "Authorization: Bearer $AUTOSUGGES_SECRET_KEY" \
  -H 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY'
```

## Security requirements
- A publishable key is public by design. It is safe in client-side JavaScript, in a mobile bundle, and in a page a search engine can read. It is not a secret and does not need a proxy.
- A publishable key is not a substitute for origin control: keys are bound to an allow-list of origins, and a request from an origin the tenant has not allowed is refused with `origin_not_allowed` and is not billed. Add the deploying site’s origin in the AutoSugges dashboard before going live.
- Never place a secret key, a signing key, a service-role credential or a database URL in client code, in an environment variable prefixed for browser exposure, or in a prompt. Nothing in an AutoSugges browser or mobile integration needs one.
- An access token (`authorization: Bearer …`) is only for a list whose policy requires one. It is short-lived, and it is minted by your own server from your own AutoSugges credentials — never in the browser, never hardcoded, never committed.
- Do not log the raw query text or the response body. Log the typed error `code` and the `requestId`.
- A secret key is a tenant-level credential, not scoped to a role or a single list: it can read and change every list your workspace owns. It is never sent from a browser or mobile app and carries no CORS allowance — if a generated integration adds one, delete it.
- Revoking a secret key from the dashboard takes effect immediately on the next request; there is no grace period the way a minted access token has.
- This is a different credential from a publishable key and from the access token POST /api/v1/token mints — a secret key never appears in client code, ever, and is not the same call as that token exchange (see the "token" API reference topic).

## Expected result
Every call answers with the documented resource and an echoed or generated x-request-id; a stale conditional write is rejected with the current ETag rather than lost; a retried write with the same Idempotency-Key never double-creates.

## Validation — do these before reporting success
1. Check 1 — Call GET /lists with no Authorization header and confirm 401 invalid_key with a WWW-Authenticate: Bearer header.
2. Check 2 — Call GET /lists/{id} for a list your workspace does not own and confirm 404 invalid_list, never 403.
3. Check 3 — POST the same body twice with the same Idempotency-Key and confirm the second response carries Idempotent-Replayed: true and is byte-identical to the first.
4. Check 4 — PATCH a list with a stale If-Match and confirm 412 with details.reason "precondition_failed" and a current ETag header — not a silently applied write.
5. Check 5 — Exceed 60 requests in a minute on one key and confirm 429 rate_limited with a retry-after header.

## Error codes you must handle
Every failure arrives as a typed code in the response body (and, through the SDK, as an `AutosuggesError` with that `code`). Switch on the code; never match on a message string. The codes most likely on this surface are: `invalid_key`, `invalid_list`, `invalid_request`, `rate_limited`. The complete vocabulary:
- `invalid_key` (HTTP 401, not retryable) — The publishable key is wrong, revoked or rotated. Check the key in the AutoSugges dashboard. Do not retry with the same key.
- `origin_not_allowed` (HTTP 403, not retryable) — The requesting origin is not on this key's allow-list. Add the origin in the dashboard. Not billed.
- `invalid_list` (HTTP 404, not retryable) — The key resolves to no list, or the list was deleted. Nothing to retry.
- `subscription_required` (HTTP 403, not retryable) — The list is shared and this consumer has no active subscription to it. Subscribe, or use a list you own.
- `list_not_published` (HTTP 409, not retryable) — The list exists but has never been published, so there is no artifact to serve. Publish it once from the dashboard.
- `token_expired` (HTTP 401, not retryable) — The access token is past its expiry. Mint a fresh one on your server and retry once. Never extend expiry on the client.
- `invalid_token` (HTTP 401, not retryable) — The access token failed signature or scope verification. Mint a new one; do not retry the same token.
- `quota_exceeded` (HTTP 200, not retryable) — The allowance for this billing scope is spent. `details.scope` says which allowance — `subscription` or `key`. The response carries no items at all, real or synthetic: render an upgrade path, and do not feed it into selection analytics. It clears at the next billing period.
- `query_too_short` (HTTP 200, not retryable) — The query is below the list's `minQueryChars` (`details.minQueryChars`). Do not issue the request at all until the input reaches it. Not billed.
- `query_too_long` (HTTP 400, not retryable) — The query exceeds the server maximum (`details.maxQueryChars`). Trim the input before sending; this is a malformed request, not something a user types.
- `invalid_request` (HTTP 400, not retryable) — The request is malformed — a missing parameter or an unusable value. `details` names what. Fix the call; retrying unchanged cannot help.
- `rate_limited` (HTTP 429, retryable) — Too many requests for this key, subscription or IP. Honour the `retryAfter` seconds in the body before retrying, and check that the input is actually debounced.
- `challenge_failed` (HTTP 403, not retryable) — A bot challenge was not satisfied on a session-establishing surface. Re-present the challenge. Not billed.
- `publish_validation_failed` (HTTP 422, not retryable) — A publish was rejected by validation (duplicates, an unresolved parent, a hierarchy cycle). The previously active version keeps serving. Fix the data and publish again.
- `compile_failed` (HTTP 500, retryable) — Compilation of a new version failed. The previously active version keeps serving; nothing at runtime changed. Retry the publish after fixing the reported cause.
- `artifact_unavailable` (HTTP 503, retryable) — A published artifact could not be read at this edge, usually mid-propagation. Retryable: wait the `retryAfter` seconds and retry once. Do not render a partial or stale result set alongside a fresh one.
- `resource_removed` (HTTP 404, not retryable) — The resource was deleted. Stop requesting it; there is nothing to retry.
- `invalid_domain` (HTTP 400, not retryable) — The submitted domain or slug is not valid or is reserved. Choose another.
- `domain_validation_failed` (HTTP 409, not retryable) — A custom-domain DNS or TLS validation did not complete. Re-check the DNS records shown in the dashboard, then revalidate.
- `forbidden` (HTTP 403, not retryable) — Your account is signed in but your workspace role does not permit this action. Ask an owner or admin to change your role, or use an account that has it.
- `internal_error` (HTTP 500, retryable) — An unexpected server-side failure. Report the `requestId` from the response. Retry at most once, with backoff.

## Notes
- The If-Match check is compare-then-write in the API layer, not a database-level conditional update — two writers racing within the same few milliseconds can both pass it. Send If-Match on every update to catch every realistic lost update; it is not a distributed lock.
- PATCH /lists/{id} accepts the same fields the dashboard’s own list-settings form writes: name, visibility, status, queryPolicy, displayOrder — nothing this API can change that the dashboard cannot, and vice versa.
- v1 only ever grows additively — an existing field is never renamed or removed under this path.

## Reference
- API reference index: https://staging.docs.autosugges.com/api-reference
- Mint an access token: https://staging.docs.autosugges.com/api-reference/token
- Error codes: https://staging.docs.autosugges.com/api-reference/errors

---
Canonical page: https://staging.docs.autosugges.com/api-reference/control-plane
