# Getting Started with the FloQast API

The FloQast API follows consistent patterns across all endpoints. This page covers the concepts you need before making your first request.

## Authentication

All FloQast API requests require a valid API key passed in the `X-API-Key` header:


```bash
curl "https://api.floqast.com/api/users/v1/me" \
  -H "X-API-Key: <your-api-key>"
```

Contact your administrator to generate API keys. Each key has scoped permissions — use the minimum required scopes for your integration.

## Response Envelope

Every response — success or error — uses the same `{ data, errors, metadata }` envelope:


```json
{
  "data": { ... },
  "errors": [],
  "metadata": {
    "flags": [{ "name": "hasError", "value": false }],
    "links": [{ "rel": "self", "href": "/api/users/v1/users/abc123" }]
  }
}
```

| Field | Description |
|  --- | --- |
| `data` | The response payload. Object for single resources, array for collections, `null` for deletes. |
| `errors` | Always empty on success. Contains structured error objects on failure. |
| `metadata` | Contains `flags` and HATEOAS `links`. |


## Optimistic Concurrency (ETag / If-Match)

`PATCH` and `DELETE` requests require the `If-Match` header to prevent lost updates:

1. `GET` a resource — the response includes an `ETag` header (e.g., `"a1b2c3d4"`).
2. Include that value in `If-Match` on your `PATCH` or `DELETE`.
3. If the resource changed since your GET, the server returns `412 Precondition Failed` — re-fetch and retry.
4. If `If-Match` is omitted entirely, the server returns `428 Precondition Required`.



```bash
# Step 1: Fetch
curl "https://api.floqast.com/api/users/v1/users/63ebc28f60431f00109e0642" \
  -H "X-API-Key: <your-api-key>"
# Note the ETag from the response header: ETag: "a1b2c3d4"

# Step 2: Update with If-Match
curl -X PATCH "https://api.floqast.com/api/users/v1/users/63ebc28f60431f00109e0642" \
  -H "X-API-Key: <your-api-key>" \
  -H "If-Match: \"a1b2c3d4\"" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Alice"}'
```