The full reference. Getting Started gets you from API key to first query in ten minutes -- this is the addendum for everything after that: every connector, full tier/rate-limit behaviour, every error code, and the REST reference for non-Python clients.
connect() infers the connector from the URL scheme where it can, or accepts connector= explicitly. Every connector calls back into the same local pipeline (profiler > classifier > accumulator > detector) described in Getting Started -- only the resulting episodes leave your device.
| Connector | Scheme / trigger | Key arguments |
|---|---|---|
| HTTPConnector | http://, https:// | interval_s=1.0, headers=None, timeout_s=10.0 |
| WebSocketConnector | ws://, wss:// | url only |
| MQTTConnector | mqtt:// | host, topic, port=1883, username=None, password=None |
| FileConnector | .jsonl/.csv/.json path, or file:// | format="auto", replay_rate_hz=0.0 (0 = as fast as possible) |
| GeneratorConnector | connector="generator" | source (iterable or callable), interval_s=0.0 |
| DataFrameConnector | connector="dataframe" | df (pandas DataFrame), timestamp_column=None, replay_rate_hz=0.0 |
| PipeConnector | connector="pipe" | stream=None (defaults to stdin) |
Calling connect() again on an already-connected client stops the previous connector first -- you can re-point a running client at a new source without creating a second one.
HiveMind calls the standard query endpoint once per registered device and merges the results client-side: de-duplicated by episode ID (keeping the higher-scoring copy if the same episode surfaces from more than one device), sorted by score, then truncated to k. If a specific device errors -- unreachable, revoked key, etc. -- that device is skipped rather than failing the whole query. Check fleet.devices to confirm what's currently registered. Calling query() before adding any devices falls back to your account's default device.
Getting Started covers the basic encode/ingest/retrieve flow. Here's the honest state of each modality, so you know what to validate before depending on it operationally:
checkpoints={"imu": "path/to/imu_weights.pt"}. Check ac.encoders["imu"].weights_loaded -- it's False until a real checkpoint is loaded, and embeddings aren't meaningful for retrieval before that.ac.retrieve()) needs the resolver's /ac/query endpoint, backed by a flat cosine-similarity index, v1 scope: no cross-device search yet. That endpoint exists in the current server source but its rollout to any given resolver deployment can lag the client SDK. Don't assume it's live -- call retrieve() and check: a clean result means it's available on your resolver; a vaasx.ac.RetrievalNotAvailable exception (rather than a silent failure) means it isn't there yet. encode(), ingest(), and outcome() don't have this caveat -- they route through the same production episode pipeline Bootstrap itself uses.Only the encoders you actually call encode(...) with are loaded -- passing just text= never touches torch/torchvision at all.
| Tier | Burst limit | Daily query cap |
|---|---|---|
| Free | 10/min | 500/day, resets midnight UTC |
| Developer | 60/min | Unlimited |
| Professional | 300/min | Unlimited |
| Enterprise | 600/min | Unlimited |
Burst limit is a per-key requests-per-minute cap checked on every ingest/query/ac/* call -- exceeding it returns 429 burst_rate_limited. Hitting the Free-tier daily query cap returns a structured 429 that includes the limit, reset time, and an upgrade link, rather than a bare error. There's also a global rate limit across the whole service (independent of tier) -- if you ever see 503 global_rate_limited with capacity left on your own key, that's whole-platform load, not something specific to your account.
| Status | detail | Meaning |
|---|---|---|
| 400 | query_required | Empty query string passed to query() |
| 400 | no_valid_items | ingest() called with an empty/invalid items list |
| 401 | missing_api_key / invalid_api_key | No key, or key not recognised |
| 403 | key_inactive_subscription_lapsed_or_cancelled | Key exists but the subscription behind it isn't active |
| 429 | burst_rate_limited | Per-key requests/minute exceeded |
| 429 | <tier>_tier_daily_query_limit_reached | Free-tier daily query cap hit |
| 502 | shard_query_failed / shard_ingest_failed / shard_outcome_failed | Reached your device's shard but the call itself failed -- usually transient, safe to retry with backoff |
| 503 | global_rate_limited | Whole-service rate limit, not specific to your key |
A VaasxAPIError with status_code=0 means the request never reached the server at all -- network error, DNS failure, or timeout. Check e.detail for the underlying message.
Base URL https://api.vaasx.com. All authenticated endpoints expect Authorization: Bearer <api_key>.
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /health | none | Liveness check |
| POST | /free-signup | none | {"email": "..."} -- issues a Free-tier key |
| POST | /ingest | key | {"device_id": ..., "items": [...]} |
| GET | /query | key | ?q=...&k=10&device_id=...&include_episode=true&prefer_success=true |
| POST | /outcome | key | {"id": ..., "device_id": ..., "success": bool, "delta": 0.0, "error_type": null} |
| POST | /ac/ingest | key, Professional+ | {"device_id": ..., "embedding": [...], "metadata": {...}} |
| POST | /ac/query | key, Professional+ | {"device_id": ..., "embedding": [...], "k": 10} |
/ingest and /query are the only two endpoints most non-Python integrations need -- the SDK is a thin wrapper around exactly these calls plus the local edge pipeline, which has no server-side equivalent since it runs client-side by design. Subscription management (upgrading, downgrading, billing details) isn't part of this table -- handle that via the pricing page's own Stripe checkout and billing portal, not by calling the resolver directly.
/ingest responds with {"status": "ok", "ingested": <count>, "episode_ids": [...]} -- episode_ids is index-aligned with the items you sent (null for any item that was skipped), so you can zip them back together to know exactly which item got which id. If an item omits episode_id, one is generated server-side and returned; you only need to supply your own if you want a specific, predictable id.
The retrieval, indexing, and encryption internals are proprietary and stay server-side or ship compiled -- a deliberate IP-protection choice, not an attempt to hide anything from you. Everything you actually interact with -- client methods, request/response shapes, connectors, error handling -- is documented on this page and is exactly what you get.
Wheel coverage is broadest on Linux x86_64 (Python 3.10-3.14). If your platform/Python combination isn't covered yet, email hello@vaasx.com rather than assuming it's a local problem -- it may just not be built yet.
Most common cause is querying before you've ingested anything for that device_id -- episodes are scoped per device unless you're using HiveMind. Check device_id matches between your ingest() and query() calls.
No -- it's optional. Episodes without a recorded outcome are still retrievable by similarity; they just don't benefit from prefer_success=True ranking. If you already know the outcome at ingest time (typical for an agent that acts and immediately observes the result), skip the separate call entirely and ingest a complete state/action/outcome item instead -- see Getting Started, section 5b.
Not fully documented in this version of the SDK/API. If you expect to approach a tier's episode cap, contact hello@vaasx.com before you get there rather than finding out by hitting it.
hello@vaasx.com for general questions, support@vaasx.com for existing-customer support, sales@vaasx.com for Enterprise/contract questions.
Quick start: Getting Started. Architecture and benchmarks: Core Platform Guide.