Scanopy API
Network topology discovery and visualization API.
Authentication
Two authentication methods are supported:
| Method | Header | Use Case |
|---|---|---|
| User API key | Authorization: Bearer scp_u_... | Programmatic access, integrations |
| Session cookie | Cookie: session_id=... | Web UI (via /api/auth/login) |
User API keys require your organization to have API access enabled. Create keys at Platform > API Keys.
Rate Limiting
Limit: 300 requests/minute
Burst: 150
Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
When rate limited, you'll receive HTTP 429 Too Many Requests with a Retry-After header.
Pagination
List endpoints support pagination via query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Maximum results to return (1-1000). Use 0 for no limit. |
offset | integer | 0 | Number of results to skip |
Example: GET /api/v1/hosts?limit=10&offset=20
Response Format
All responses use a standard envelope:
{
"success": true,
"data": { ... },
"meta": {
"api_version": 1,
"server_version": "0.16.0"
}
}Paginated list responses include pagination metadata:
{
"success": true,
"data": [ ... ],
"meta": {
"api_version": 1,
"server_version": "0.16.0",
"pagination": {
"total_count": 142,
"limit": 50,
"offset": 0,
"has_more": true
}
}
}| Field | Description |
|---|---|
total_count | Total items matching your query (ignoring pagination) |
limit | Applied limit (your request or default) |
offset | Applied offset |
has_more | true if more results exist beyond this page |
Error responses include an error field instead of data:
{
"success": false,
"error": "Resource not found",
"meta": { ... }
}Common status codes: 400 validation error, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 429 rate limited.
Versioning
Endpoints are prefixed with /api/v1/. The API version is an integer (api_version: 1) returned in every response, versioned independently from the application. Check GET /api/version for current versions.
While Scanopy is pre-v1.0 (current: 0.16.0), the API should be considered unstable. Breaking changes may be introduced in any release without incrementing the API version. We recommend pinning to a specific Scanopy release if you depend on API stability, and reviewing the changelog before upgrading. After Scanopy reaches v1.0, breaking API changes will only occur with an API version increment.
Multi-Tenancy
Resources are scoped to your organization and network(s):
- You can only access entities within your organization
- Network-level entities (hosts, services, etc.) are filtered to networks you have access to
- Use
?network_id=<UUID>to filter list endpoints to a specific network - API keys can be scoped to a subset of your accessible networks