# LoopEngine — Agent Integration Guide (Ingest) Self-contained instructions for coding agents integrating LoopEngine into a user's application. Site: https://loopengine.dev/ API: https://api.loopengine.dev Docs: https://loopengine.dev/docs/ingest.md OpenAPI: https://loopengine.dev/openapi-ingest.yaml llms.txt: https://loopengine.dev/llms.txt ## What LoopEngine is LoopEngine is an API-first feedback collection platform. Client apps send schema-validated feedback via a public HMAC-signed HTTP endpoint. Sentiment/topic analysis (on eligible plans) runs asynchronously after ingest and never blocks the ingest response. ## What you need from the user (credentials) Create a project in the LoopEngine dashboard (https://loopengine.dev/). From the project page, copy: | Value | Prefix | Sent how | |-------|--------|----------| | `project_id` | `proj_…` | JSON body field | | `project_key` | `pk_live_…` | Header `X-Project-Key` (public) | | `project_secret` | `psk_live_…` | HMAC key only — never send on the wire | Ask the user for these three values before writing production code. Do not invent credentials. ## Scope: client ingest only Use: `POST https://api.loopengine.dev/feedback` Do NOT use for third-party apps: - `POST /collect-feedback` — LoopEngine dashboard/landing dogfooding only (CORS allowlist + server-side secrets) Admin APIs (`/projects/*`, `/feedbacks/*`, `/users/*`) require Cognito JWT. They are not required to send feedback from a client app. ## Request Method: POST URL: https://api.loopengine.dev/feedback Content-Type: application/json Headers (all required): - Content-Type: application/json - X-Project-Key: - X-Timestamp: - X-Signature: v1= Timestamp skew allowed: ±300 seconds from server time. Max JSON body size: 4096 bytes. ### Body rules - Required top-level field: `project_id` (string) - Optional reserved top-level fields (stripped from schema/fields): `geo_lat`, `geo_lon` (numbers; both required for client geo) - All other keys become feedback `fields` (values coerced to strings) - Per-project `payload_schema` may enforce allowed/required fields and constraints; violations → HTTP 400 `invalid_payload` Minimal example body: ```json {"project_id":"proj_…","message":"Great UX!"} ``` With optional device geo: ```json {"project_id":"proj_…","message":"Great UX!","geo_lat":40.7128,"geo_lon":-74.006} ``` Sign the exact raw body bytes you send. If you serialize JSON yourself, use stable compact encoding (no insignificant whitespace), e.g. Python `json.dumps(..., separators=(',', ':'))`. ## Signature algorithm (authoritative) 1. body_hash = lowercase hex encoding of SHA-256(raw_body_bytes) 2. canonical = METHOD + "\n" + PATH + "\n" + timestamp + "\n" + body_hash - METHOD is always `POST` - PATH is always `/feedback` (API path, not full URL) - timestamp is the same string as `X-Timestamp` 3. raw_mac = HMAC-SHA256(key=project_secret, message=canonical_utf8_bytes) 4. X-Signature = "v1=" + base64url(raw_mac) with padding `=` characters removed Pseudocode (Python): ```python import base64, hashlib, hmac, json, time, urllib.request PROJECT_KEY = "pk_live_…" PROJECT_SECRET = "psk_live_…" API_URL = "https://api.loopengine.dev/feedback" body = {"project_id": "proj_…", "message": "Great UX!"} body_bytes = json.dumps(body, separators=(",", ":")).encode() timestamp = str(int(time.time())) body_hash = hashlib.sha256(body_bytes).hexdigest() canonical = f"POST\n/feedback\n{timestamp}\n{body_hash}" sig = base64.urlsafe_b64encode( hmac.new(PROJECT_SECRET.encode(), canonical.encode(), hashlib.sha256).digest() ).rstrip(b"=").decode() req = urllib.request.Request( API_URL, data=body_bytes, method="POST", headers={ "Content-Type": "application/json", "X-Project-Key": PROJECT_KEY, "X-Timestamp": timestamp, "X-Signature": f"v1={sig}", }, ) with urllib.request.urlopen(req) as resp: print(resp.status, resp.read().decode()) ``` ## Responses All responses are JSON. Success (HTTP 201): ```json {"data":{"id":"fb_…","created_at":"2026-11-08T12:00:00Z","status":"accepted"}} ``` Paused project (HTTP 200) — feedback discarded; signature may be skipped when `feedback_active` is false: ```json {"data":{"id":"","created_at":"","status":"discarded"}} ``` (Exact empty fields may vary; check `status === "discarded"`.) Error envelope: ```json {"error":{"code":401,"message":"invalid_signature"}} ``` Common ingest errors: - 400 invalid_payload — bad JSON, missing project_id, schema violation, body too large, bad/expired timestamp - 401 invalid_signature — wrong key or HMAC - 429 monthly_limit_exceeded — plan quota - 400 unsupported_content_type — wrong Content-Type for the request shape After a successful 201, AI analysis (if on an eligible plan) runs asynchronously. Do not expect sentiment/topics in the ingest response. ## Official SDKs (signing handled inside) - JS/TS: npm `@loopengine/sdk` — https://www.npmjs.com/package/@loopengine/sdk - Python: PyPI `loopengine` — https://pypi.org/project/loopengine/ - Go: `github.com/LoopEngine-dev/loopengine-go` - Rust: crates.io `loopengine` — https://crates.io/crates/loopengine Prefer an SDK when the user's language matches; otherwise implement raw HTTP HMAC as above. ## Optional: audio ingest (Teams plan) Same path `POST /feedback` with `Content-Type: multipart/form-data`. HMAC is computed over the raw multipart body with the same canonical format. Form fields include `project_id` and an `audio` file. See product docs / dashboard snippets for MIME limits. JSON ingest above is enough for most agent setups. ## Agent checklist 1. Obtain `project_id`, `project_key`, `project_secret` from the user (dashboard). 2. Choose SDK or raw HMAC for the user's stack. 3. Implement `POST /feedback` with the four headers and signed body. 4. Verify a 201 `data.status === "accepted"` response in a dry run. 5. Store the secret securely (env var / secret manager); never embed in public client bundles if the runtime is untrusted — prefer a backend that signs requests. 6. Do not call `/collect-feedback`. ## Support support@loopengine.dev