# LoopEngine Ingest API

API-first, HMAC-signed feedback collection. Use this guide to wire `POST /feedback` into an application.

| | |
|---|---|
| **Site** | https://loopengine.dev/ |
| **API base** | https://api.loopengine.dev |
| **Agent index** | https://loopengine.dev/llms.txt |
| **Full agent guide** | https://loopengine.dev/llms-full.txt |
| **OpenAPI** | https://loopengine.dev/openapi-ingest.yaml |

## Credentials (from the dashboard)

Create a project at [loopengine.dev](https://loopengine.dev/). From the project page, copy:

| Value | Prefix | How it is used |
|-------|--------|----------------|
| `project_id` | `proj_…` | JSON body field |
| `project_key` | `pk_live_…` | Header `X-Project-Key` (public) |
| `project_secret` | `psk_live_…` | HMAC key only — **never** sent on the wire |

## Endpoint

```http
POST https://api.loopengine.dev/feedback
Content-Type: application/json
```

This is the only endpoint you need for client ingest. Admin routes (`/projects/*`, `/feedbacks/*`, `/users/*`) require Cognito JWT and are not used for sending feedback.

**Do not** call `POST /collect-feedback` from third-party apps — that route is for LoopEngine’s own dashboard/landing form.

## Headers

| Header | Required | Description |
|--------|----------|-------------|
| `Content-Type` | yes | `application/json` |
| `X-Project-Key` | yes | Public project key (`pk_live_…`) |
| `X-Timestamp` | yes | Unix seconds as a decimal string (±300s skew) |
| `X-Signature` | yes | `v1=` + base64url HMAC (no padding) |

Max JSON body size: **4096** bytes.

## Body

- **Required:** `project_id` (string)
- **Optional reserved:** `geo_lat`, `geo_lon` (numbers; both required for client geo). Stripped from schema/fields.
- **Everything else** becomes feedback `fields` (values coerced to strings).
- Per-project `payload_schema` may enforce allowed/required fields and constraints.

```json
{"project_id":"proj_…","message":"Great UX!"}
```

Sign the **exact raw body bytes** you send. Prefer compact JSON with no insignificant whitespace.

## Signature algorithm

```
body_hash = hex(sha256(raw_body))          # lowercase hex
canonical = "POST\n/feedback\n" + timestamp + "\n" + body_hash
raw_mac   = HMAC-SHA256(project_secret, canonical)
X-Signature = "v1=" + base64url(raw_mac)   # no '=' padding
```

- `METHOD` is always `POST`
- `PATH` is always `/feedback` (not the full URL)
- `timestamp` must match the `X-Timestamp` header exactly

### Python example

```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())
```

### curl / bash sketch

```bash
TIMESTAMP=$(date +%s)
BODY='{"project_id":"proj_…","message":"Great UX!"}'
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $2}')
CANONICAL=$(printf 'POST\n/feedback\n%s\n%s' "$TIMESTAMP" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" \
  | openssl dgst -sha256 -hmac "$PROJECT_SECRET" -binary \
  | base64 | tr -d '\n' | tr '+/' '-_' | tr -d '=')

curl -X POST "https://api.loopengine.dev/feedback" \
  -H "Content-Type: application/json" \
  -H "X-Project-Key: $PROJECT_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: v1=$SIGNATURE" \
  -d "$BODY"
```

## Responses

All responses are JSON.

### Success — `201 Created`

```json
{
  "data": {
    "id": "fb_…",
    "created_at": "2026-11-08T12:00:00Z",
    "status": "accepted"
  }
}
```

AI analysis (eligible plans) runs **asynchronously** after ingest. Sentiment/topics are not in this response.

### Paused project — `200 OK`

When `feedback_active` is false, ingest returns discarded status (signature may be skipped):

```json
{"data":{"status":"discarded"}}
```

### Errors

```json
{"error":{"code":401,"message":"invalid_signature"}}
```

| Status | Message | Typical cause |
|--------|---------|---------------|
| 400 | `invalid_payload` | Bad JSON, missing `project_id`, schema violation, body > 4 KB, bad/expired timestamp |
| 401 | `invalid_signature` | Wrong key or HMAC |
| 429 | `rate_limited` | Per-IP or per-project request rate exceeded (or temporary IP penalty) |
| 429 | `monthly_limit_exceeded` | Plan monthly feedback quota |
| 400 | `unsupported_content_type` | Wrong `Content-Type` |

### Rate limits and backoff

Ingest is protected by layered limits:

- Shared API Gateway throttle on `POST /feedback`
- Per-IP request budget (abuse net) with progressive temporary blocks after repeated denials
- Per-project request budget scaled by plan (`max_ingest_per_minute`)
- Monthly plan quota (`max_feedback_per_month`)

On `429`, honor `Retry-After` (seconds), then use bounded exponential backoff with jitter. Also inspect:

| Header | Meaning |
|--------|---------|
| `Retry-After` | Seconds to wait before retrying |
| `RateLimit-Limit` / `X-RateLimit-Limit` | Window budget |
| `RateLimit-Remaining` / `X-RateLimit-Remaining` | Remaining requests in the window |
| `RateLimit-Reset` / `X-RateLimit-Reset` | Unix time when the window resets |

Do not blindly retry successful non-idempotent writes. Treat `monthly_limit_exceeded` as a hard ceiling until the monthly reset (or a plan upgrade)—backoff will not help.

## Official SDKs

Signing is handled inside the SDK:

| Language | Package |
|----------|---------|
| JavaScript / TypeScript | [`@loopengine/sdk`](https://www.npmjs.com/package/@loopengine/sdk) |
| Python | [`loopengine`](https://pypi.org/project/loopengine/) |
| Go | [`github.com/LoopEngine-dev/loopengine-go`](https://github.com/LoopEngine-dev/loopengine-go) |
| Rust | [`loopengine`](https://crates.io/crates/loopengine) |

## Security note

Prefer signing on a **trusted backend**. Never ship `project_secret` in a public browser or mobile binary if the runtime can be inspected.

## Support

support@loopengine.dev
