> ## 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.

# Discovery

> Retrieve the latest AI platform discovery scan results and detected platforms.

```
GET /api/v1/discovery
```

Returns the most recent completed discovery scan for your organization along with the platforms detected during that scan. If no scan has been completed, `scan` is `null` and `platforms` is an empty array.

**Required scope:** `discovery:read`

## Request

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

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

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

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

## Query parameters

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

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

Pagination applies to the `platforms` array only. The `scan` object is always returned in full.

## Response

```json theme={null}
{
  "scan": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "domain": "example.com",
    "started_at": "2026-03-15T14:00:00Z",
    "completed_at": "2026-03-15T14:30:00Z",
    "summary": {
      "platforms_discovered": 14,
      "shadow_ai_count": 3,
      "overall_risk_score": 65
    }
  },
  "platforms": [
    {
      "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
      "platform_name": "ChatGPT",
      "platform_type": "llm_chat",
      "url": "https://chat.openai.com",
      "confidence": 0.95,
      "metadata": {
        "vendor": "OpenAI",
        "category": "LLM Chat"
      },
      "created_at": "2026-03-15T14:15:00Z"
    },
    {
      "id": "e7b1f3a0-4c2d-4b8e-9f1a-2d3c4e5f6a7b",
      "platform_name": "GitHub Copilot",
      "platform_type": "code_assistant",
      "url": "https://github.com/features/copilot",
      "confidence": 0.88,
      "metadata": {
        "vendor": "GitHub",
        "category": "Code Assistant"
      },
      "created_at": "2026-03-15T14:18:00Z"
    }
  ]
}
```

## Response fields

<ResponseField name="scan" type="object | null" required>
  The most recent completed discovery scan, or `null` if no scan has been completed.

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

    <ResponseField name="organization_id" type="string" required>
      UUID of the organization that owns this scan.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Scan status. Always `completed` in API responses (only completed scans are returned).
    </ResponseField>

    <ResponseField name="domain" type="string" required>
      The domain that was scanned.
    </ResponseField>

    <ResponseField name="started_at" type="string" required>
      ISO 8601 UTC timestamp of when the scan started.
    </ResponseField>

    <ResponseField name="completed_at" type="string" required>
      ISO 8601 UTC timestamp of when the scan finished.
    </ResponseField>

    <ResponseField name="summary" type="object" required>
      Aggregated scan results.

      <Expandable title="Summary fields">
        <ResponseField name="platforms_discovered" type="integer" required>
          Total number of AI platforms detected.
        </ResponseField>

        <ResponseField name="shadow_ai_count" type="integer" required>
          Number of detected platforms that are not on the organization's approved list.
        </ResponseField>

        <ResponseField name="overall_risk_score" type="integer" required>
          Aggregate risk score from 0 to 100 based on the discovered platforms.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="platforms" type="array" required>
  Platforms detected during the scan, sorted by confidence score (highest first).

  <Expandable title="Platform object fields">
    <ResponseField name="id" type="string" required>
      Unique identifier (UUID) for the detected platform record.
    </ResponseField>

    <ResponseField name="platform_name" type="string" required>
      Name of the detected platform (e.g., "ChatGPT", "GitHub Copilot").
    </ResponseField>

    <ResponseField name="platform_type" type="string" required>
      Classification of the platform (e.g., `llm_chat`, `code_assistant`, `image_generation`).
    </ResponseField>

    <ResponseField name="url" type="string" required>
      URL associated with the detected platform.
    </ResponseField>

    <ResponseField name="confidence" type="number" required>
      Detection confidence score from 0.0 to 1.0. Higher values indicate stronger evidence of platform usage.
    </ResponseField>

    <ResponseField name="metadata" type="object" required>
      Additional platform details. Contents vary by platform but typically include `vendor` and `category`.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 UTC timestamp of when this platform was detected.
    </ResponseField>
  </Expandable>
</ResponseField>

## No scan completed

If your organization has not completed a discovery scan, the response is:

```json theme={null}
{
  "scan": null,
  "platforms": []
}
```

## Notes

* Only the most recent completed scan is returned. Historical scans are not available through the API.
* The `metadata` object structure varies by platform and may include additional fields beyond `vendor` and `category` in future versions.
* Platforms are sorted by `confidence` descending. Use pagination to retrieve large result sets.