Getting Started with the FloQast v2 API

The FloQast v2 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:

curl "https://apix.floqast.app/v2/core/users" \
  -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:

{
  "data": { ... },
  "errors": [],
  "metadata": {
    "pagination": {
      "totalCount": 42,
      "limit": 25,
      "offset": 0,
      "hasMore": true
    },
    "links": {
      "self": "/v2/core/users?limit=25&offset=0",
      "next": "/v2/core/users?limit=25&offset=25",
      "prev": null
    }
  }
}

Field	Description
`data`	The response payload. Object for single resources, array for collections.
`errors`	Always empty on success. Contains structured error objects on failure.
`metadata`	Contains `pagination` and navigation `links`. Omitted when empty (e.g. single-resource responses).

Pagination

List endpoints use offset-based pagination via limit and offset query parameters:

Parameter	Default	Max	Description
`limit`	25	100	Number of items to return
`offset`	0	—	Number of items to skip

# Page 2 of results (items 26–50)
curl "https://apix.floqast.app/v2/core/users?limit=25&offset=25" \
  -H "x-api-key: <your-api-key>"

Use metadata.pagination.hasMore to determine if additional pages exist.

Error Handling

All error responses use { errors: [...] } — always an array, even for a single error:

{
  "errors": [
    {
      "id": "req_abc123",
      "title": "Not Found",
      "status": 404,
      "code": "resource_not_found",
      "detail": "User 64abc123 was not found in this tenant.",
      "instance": "/v2/core/users/64abc123"
    }
  ]
}

Field	Description
`id`	Request trace ID — include this when contacting support.
`title`	Short, stable summary of the error type (e.g. `Not Found`, `Bad Request`).
`status`	HTTP status code mirroring the response status.
`code`	Machine-readable error code (e.g. `resource_not_found`, `invalid_parameter`).
`detail`	Human-readable, occurrence-specific explanation.
`instance`	URI path of the request that produced this error.
`param`	The field or query parameter that caused the error (when applicable).

Rate Limiting

The API enforces rate limits. When exceeded, the response is 429 Too Many Requests with a Retry-After header indicating seconds to wait before retrying.