> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ayliea.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recommendations

> Retrieve prioritized remediation recommendations for your organization.

```
GET /api/v1/recommendations
```

Returns recommendations across all completed assessments for your organization, sorted by priority (highest first) and then by creation date (newest first).

**Required scope:** `recommendations:read`

## Request

<CodeGroup>
  ```bash curl theme={null}
  curl "https://assess.ayliea.com/api/v1/recommendations?limit=25" \
    -H "X-API-Key: ayliea_pk_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://assess.ayliea.com/api/v1/recommendations",
      headers={"X-API-Key": "ayliea_pk_YOUR_API_KEY"},
      params={"limit": 25}
  )
  recommendations = response.json()["recommendations"]
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://assess.ayliea.com/api/v1/recommendations?limit=25",
    { headers: { "X-API-Key": "ayliea_pk_YOUR_API_KEY" } }
  );
  const { recommendations } = await response.json();
  ```
</CodeGroup>

## Query parameters

<ParamField query="limit" type="integer" default="100">
  Maximum number of results to return. Must be between 1 and 100.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip. Must be 0 or greater.
</ParamField>

## Response

```json theme={null}
{
  "recommendations": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "title": "Enable multi-factor authentication for all users",
      "priority": 1,
      "status": "open",
      "framework_id": "nist-csf-2",
      "category": "Access Control"
    },
    {
      "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
      "title": "Implement network segmentation between production and development",
      "priority": 2,
      "status": "in_progress",
      "framework_id": "cis-v8",
      "category": "Network Security"
    }
  ]
}
```

## Response fields

<ResponseField name="recommendations" type="array" required>
  Array of recommendation objects.

  <Expandable title="Recommendation object fields">
    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for the recommendation.
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Short description of the recommended action.
    </ResponseField>

    <ResponseField name="priority" type="integer" required>
      Priority ranking. Lower numbers indicate higher priority (1 is the highest).
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Current status of the recommendation. One of: `open`, `in_progress`, `completed`, `dismissed`.
    </ResponseField>

    <ResponseField name="framework_id" type="string" required>
      The framework this recommendation is associated with (e.g., `nist-csf-2`, `hipaa`).
    </ResponseField>

    <ResponseField name="category" type="string" required>
      The assessment category this recommendation falls under (e.g., "Access Control", "Network Security").
    </ResponseField>
  </Expandable>
</ResponseField>

## Sorting

Results are sorted by:

1. `priority` ascending (highest priority first)
2. `created_at` descending (newest first within the same priority)

This sort order is fixed and cannot be changed via query parameters.

## Notes

* Recommendations span all completed assessments — they are not filtered by framework. To filter client-side, use the `framework_id` field.
* If no assessments have been completed, the `recommendations` array is empty.
* Status changes made in the Ayliea web or mobile app are reflected immediately in API responses.