# Flowtivity API — Agent Integration Guide

> Machine-readable API reference for Flowtivity's scanning, analysis, and directory services.

---

## Base URL

```
https://flowtivity.ai
```

## Authentication

All authenticated endpoints require an API key via the `x-mcp-api-key` header.

```
GET /api/insights/scan/{id}/results
x-mcp-api-key: your-api-key
```

Free tier: Trigger scans and get results without an API key. Rate limited to 10 scans/day.

Get an API key: https://flowtivity.ai/developers/

---

## Core Endpoints

### Trigger a Scan
```
POST /api/insights/scan
Content-Type: application/json

{
  "url": "example.com",
  "email": "user@example.com",     // optional
  "scanType": "basic"              // light | basic | full
}
```

Response: `{ "scanId": "uuid", "status": "pending" }`

### Check Scan Status
```
GET /api/insights/scan/{scanId}/status
```

Response: `{ "status": "analyzing", "progress": 65 }`

### Get Scan Results
```
GET /api/insights/scan/{scanId}/results
```

Returns: readiness score, AEO score, workflows, opportunities, key findings.

### Get Comprehensive Results
```
GET /api/insights/scan/{scanId}/comprehensive
```

Returns: Full results + playbook, AEO boost, directory listing, challenges.

### List Scans
```
GET /api/insights/scans?limit=20&status=complete&cursor=xxx
```

### Get Playbook
```
GET /api/insights/playbook/{scanId}?include_skills=true
```

---

## Directory Endpoints

```
GET /api/directory?industry=technology&limit=20&offset=0
GET /api/directory/{slug}
```

---

## Error Responses

All errors return JSON:
```json
{
  "error": "not_found",
  "code": "SCAN_NOT_FOUND",
  "message": "Scan not found. Check the scan ID and try again."
}
```

---

## Streaming

Long-running scans support SSE status updates:
```
GET /api/insights/scan/{scanId}/stream
Accept: text/event-stream
```

---

## Webhooks

Subscribe to scan completion events:
```
POST /api/webhooks/subscribe
Content-Type: application/json

{
  "url": "https://your-app.com/webhook",
  "events": ["scan.complete", "scan.error"]
}
```

---

## MCP Integration

MCP server: https://flowtivity.ai/.well-known/mcp
Server card: https://flowtivity.ai/.well-known/mcp/server-card.json
Transport: Streamable HTTP

---

## OpenAPI Spec

https://flowtivity.ai/openapi.json

---

*Last updated: May 2026*