diff --git a/lib/towerops_web/controllers/api_docs_html/index.html.heex b/lib/towerops_web/controllers/api_docs_html/index.html.heex index 5ec51b0d..35ca220a 100644 --- a/lib/towerops_web/controllers/api_docs_html/index.html.heex +++ b/lib/towerops_web/controllers/api_docs_html/index.html.heex @@ -1420,6 +1420,1588 @@ Content-Disposition: attachment; filename="towerops-data-{user_id}-{timestamp}.j
+ Alerts represent monitoring events triggered when a device check fails or recovers. You can list, view, acknowledge, and resolve alerts. +
+ + ++ Returns all alerts for the authenticated organization. +
+Request
+<%= raw("""
+curl -G https://towerops.net/api/v1/alerts \\
+ -H "Authorization: Bearer #{@sample_token}" \\
+ -d status=active
+""") %>
+ Response
+<%= raw("""
+{
+ "data": [
+ {
+ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+ "alert_type": "ping_down",
+ "message": "Device is not responding to ping",
+ "triggered_at": "2026-02-14T10:30:00Z",
+ "acknowledged_at": null,
+ "resolved_at": null,
+ "device_id": "550e8400-e29b-41d4-a716-446655440000",
+ "device_name": "Core Router",
+ "acknowledged_by_email": null,
+ "gaiia_impact": "High - affects 12 downstream devices",
+ "inserted_at": "2026-02-14T10:30:00Z"
+ }
+ ]
+}
+""") %>
+ Retrieves a single alert by its ID.
+Request
+<%= raw("""
+curl https://towerops.net/api/v1/alerts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ + Marks an alert as acknowledged. The acknowledging user is recorded automatically. +
+Request
+<%= raw("""
+curl -X POST https://towerops.net/api/v1/alerts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/acknowledge \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response
+<%= raw("""
+{
+ "data": {
+ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+ "alert_type": "ping_down",
+ "message": "Device is not responding to ping",
+ "triggered_at": "2026-02-14T10:30:00Z",
+ "acknowledged_at": "2026-02-14T11:00:00Z",
+ "resolved_at": null,
+ "device_id": "550e8400-e29b-41d4-a716-446655440000",
+ "device_name": "Core Router",
+ "acknowledged_by_email": "admin@example.com",
+ "gaiia_impact": "High - affects 12 downstream devices",
+ "inserted_at": "2026-02-14T10:30:00Z"
+ }
+}
+""") %>
+ + Manually resolves an alert. Alerts may also be resolved automatically when the underlying condition clears. +
+Request
+<%= raw("""
+curl -X POST https://towerops.net/api/v1/alerts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/resolve \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ + Agents are lightweight monitoring agents that run on your infrastructure to collect device data. Each agent has a token used for authentication. +
+ + +Returns all agent tokens for the authenticated organization.
+Request
+<%= raw("""
+curl -G https://towerops.net/api/v1/agents \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response
+<%= raw("""
+{
+ "data": [
+ {
+ "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+ "name": "datacenter-agent-01",
+ "enabled": true,
+ "last_seen_at": "2026-02-14T11:00:00Z",
+ "last_ip": "10.0.1.50",
+ "metadata": {"version": "1.4.2", "os": "linux"},
+ "inserted_at": "2026-01-10T08:00:00Z"
+ }
+ ]
+}
+""") %>
+ + Creates a new agent token. The raw token is returned only once in the response — store it securely. +
+Request
+<%= raw("""
+curl -X POST https://towerops.net/api/v1/agents \\
+ -H "Authorization: Bearer #{@sample_token}" \\
+ -H "Content-Type: application/json" \\
+ -d '{"name": "new-site-agent"}'
+""") %>
+ Response (201 Created)
+<%= raw("""
+{
+ "data": {
+ "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
+ "name": "new-site-agent",
+ "enabled": true,
+ "last_seen_at": null,
+ "last_ip": null,
+ "metadata": null,
+ "inserted_at": "2026-02-14T11:10:00Z",
+ "token": "tow_agent_abc123..."
+ }
+}
+""") %>
+ Retrieves a single agent by ID. Includes a count of assigned devices.
+Request
+<%= raw("""
+curl https://towerops.net/api/v1/agents/b2c3d4e5-f6a7-8901-bcde-f12345678901 \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response
+<%= raw("""
+{
+ "data": {
+ "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+ "name": "datacenter-agent-01",
+ "enabled": true,
+ "last_seen_at": "2026-02-14T11:00:00Z",
+ "last_ip": "10.0.1.50",
+ "metadata": {"version": "1.4.2", "os": "linux"},
+ "inserted_at": "2026-01-10T08:00:00Z",
+ "device_count": 24
+ }
+}
+""") %>
+ Permanently deletes an agent token. Devices assigned to this agent will need to be reassigned.
+Request
+<%= raw("""
+curl -X DELETE https://towerops.net/api/v1/agents/b2c3d4e5-f6a7-8901-bcde-f12345678901 \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response (204 No Content)
+<%= raw("""
+(empty response body)
+""") %>
+ + Retrieve and update settings for the authenticated organization, including SNMP defaults, MikroTik configuration, and general preferences. +
+ + +Returns the full settings for the authenticated organization.
+Request
+<%= raw("""
+curl https://towerops.net/api/v1/organization \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response
+<%= raw("""
+{
+ "data": {
+ "id": "org-uuid-here",
+ "name": "Acme Networks",
+ "slug": "acme-networks",
+ "subscription_plan": "pro",
+ "use_sites": true,
+ "snmp_version": "v2c",
+ "snmp_community": "public",
+ "snmp_port": 161,
+ "snmp_transport": "udp",
+ "snmpv3_security_level": null,
+ "snmpv3_username": null,
+ "snmpv3_auth_protocol": null,
+ "snmpv3_priv_protocol": null,
+ "mikrotik_enabled": false,
+ "mikrotik_username": null,
+ "mikrotik_port": null,
+ "mikrotik_ssh_port": null,
+ "mikrotik_use_ssl": false,
+ "default_agent_token_id": null,
+ "inserted_at": "2025-06-01T00:00:00Z",
+ "updated_at": "2026-02-14T10:00:00Z"
+ }
+}
+""") %>
+ + Updates organization settings. Only the provided fields are changed. +
+Request
+<%= raw("""
+curl -X PATCH https://towerops.net/api/v1/organization \\
+ -H "Authorization: Bearer #{@sample_token}" \\
+ -H "Content-Type: application/json" \\
+ -d '{"organization": {"name": "Acme Networks LLC", "snmp_community": "private"}}'
+""") %>
+ + Manage the users who belong to your organization. You can list members, change roles, and remove members. +
+ + +Returns all members of the authenticated organization.
+Request
+<%= raw("""
+curl -G https://towerops.net/api/v1/members \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response
+<%= raw("""
+{
+ "data": [
+ {
+ "id": "user-uuid-1",
+ "email": "admin@example.com",
+ "role": "owner",
+ "inserted_at": "2025-06-01T00:00:00Z"
+ },
+ {
+ "id": "user-uuid-2",
+ "email": "tech@example.com",
+ "role": "admin",
+ "inserted_at": "2025-08-15T00:00:00Z"
+ }
+ ]
+}
+""") %>
+ Updates a member's role. Cannot change the owner's role.
+Request
+<%= raw("""
+curl -X PATCH https://towerops.net/api/v1/members/user-uuid-2 \\
+ -H "Authorization: Bearer #{@sample_token}" \\
+ -H "Content-Type: application/json" \\
+ -d '{"role": "member"}'
+""") %>
+ Removes a member from the organization. The organization owner cannot be removed.
+Request
+<%= raw("""
+curl -X DELETE https://towerops.net/api/v1/members/user-uuid-2 \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ + Invite new users to your organization. Invitations expire after 7 days. +
+ + +Returns all pending invitations for the organization.
+Request
+<%= raw("""
+curl -G https://towerops.net/api/v1/invitations \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response
+<%= raw("""
+{
+ "data": [
+ {
+ "id": "inv-uuid-1",
+ "email": "newuser@example.com",
+ "role": "member",
+ "expires_at": "2026-02-21T11:00:00Z",
+ "invited_by_email": "admin@example.com",
+ "inserted_at": "2026-02-14T11:00:00Z"
+ }
+ ]
+}
+""") %>
+ Sends an invitation to join the organization.
+Request
+<%= raw("""
+curl -X POST https://towerops.net/api/v1/invitations \\
+ -H "Authorization: Bearer #{@sample_token}" \\
+ -H "Content-Type: application/json" \\
+ -d '{"email": "newuser@example.com", "role": "member"}'
+""") %>
+ Cancels a pending invitation.
+Request
+<%= raw("""
+curl -X DELETE https://towerops.net/api/v1/invitations/inv-uuid-1 \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ + Manage third-party integrations for your organization, such as notification providers and external monitoring systems. +
+ + +Returns all integrations for the organization.
+Request
+<%= raw("""
+curl -G https://towerops.net/api/v1/integrations \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response
+<%= raw("""
+{
+ "data": [
+ {
+ "id": "intg-uuid-1",
+ "provider": "slack",
+ "enabled": true,
+ "sync_interval_minutes": 5,
+ "last_synced_at": "2026-02-14T11:00:00Z",
+ "last_sync_status": "success",
+ "inserted_at": "2025-12-01T00:00:00Z",
+ "updated_at": "2026-02-14T11:00:00Z"
+ }
+ ]
+}
+""") %>
+ Creates a new integration.
+Request
+<%= raw("""
+curl -X POST https://towerops.net/api/v1/integrations \\
+ -H "Authorization: Bearer #{@sample_token}" \\
+ -H "Content-Type: application/json" \\
+ -d '{"integration": {"provider": "slack", "enabled": true, "sync_interval_minutes": 5}}'
+""") %>
+ Retrieves a single integration by ID.
+Request
+<%= raw("""
+curl https://towerops.net/api/v1/integrations/intg-uuid-1 \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Updates an integration's settings.
+Request
+<%= raw("""
+curl -X PATCH https://towerops.net/api/v1/integrations/intg-uuid-1 \\
+ -H "Authorization: Bearer #{@sample_token}" \\
+ -H "Content-Type: application/json" \\
+ -d '{"integration": {"enabled": false}}'
+""") %>
+ Permanently deletes an integration.
+Request
+<%= raw("""
+curl -X DELETE https://towerops.net/api/v1/integrations/intg-uuid-1 \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Tests the connection for an integration to verify it's properly configured.
+Request
+<%= raw("""
+curl -X POST https://towerops.net/api/v1/integrations/intg-uuid-1/test \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response
+<%= raw("""
+{
+ "data": {
+ "status": "ok",
+ "provider": "slack"
+ }
+}
+""") %>
+ + Access monitoring check results, historical metrics, and SNMP interface data for your devices. +
+ +Returns all monitoring checks configured for a device, including the latest result for each check.
+Request
+<%= raw("""
+curl -G https://towerops.net/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/checks \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response
+<%= raw("""
+{
+ "data": [
+ {
+ "id": "check-uuid-1",
+ "name": "ICMP Ping",
+ "check_type": "ping",
+ "enabled": true,
+ "interval_seconds": 60,
+ "latest_status": "ok",
+ "latest_value": 12.5,
+ "latest_checked_at": "2026-02-14T11:10:00Z"
+ }
+ ]
+}
+""") %>
+ Returns historical check results for a device, useful for graphing and trend analysis.
+Request
+<%= raw("""
+curl -G https://towerops.net/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/metrics \\
+ -H "Authorization: Bearer #{@sample_token}" \\
+ -d hours=48 \\
+ -d check_type=ping
+""") %>
+ Response
+<%= raw("""
+{
+ "data": [
+ {
+ "check_id": "check-uuid-1",
+ "check_name": "ICMP Ping",
+ "check_type": "ping",
+ "data": [
+ {"timestamp": "2026-02-14T10:00:00Z", "value": 11.2, "status": "ok"},
+ {"timestamp": "2026-02-14T10:01:00Z", "value": 13.8, "status": "ok"},
+ {"timestamp": "2026-02-14T10:02:00Z", "value": null, "status": "timeout"}
+ ]
+ }
+ ]
+}
+""") %>
+ Returns SNMP-discovered network interfaces for a device.
+Request
+<%= raw("""
+curl -G https://towerops.net/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/interfaces \\
+ -H "Authorization: Bearer #{@sample_token}"
+""") %>
+ Response
+<%= raw("""
+{
+ "data": [
+ {
+ "id": "iface-uuid-1",
+ "if_index": 1,
+ "if_name": "GigabitEthernet0/0",
+ "if_descr": "GigabitEthernet0/0",
+ "if_alias": "Uplink to ISP",
+ "if_speed": 1000000000,
+ "if_admin_status": "up",
+ "if_oper_status": "up",
+ "monitored": true
+ }
+ ]
+}
+""") %>
+ + View a chronological feed of actions and events across your organization. +
+ +Returns recent activity events for the organization.
+Request
+<%= raw("""
+curl -G https://towerops.net/api/v1/activity \\
+ -H "Authorization: Bearer #{@sample_token}" \\
+ -d limit=20
+""") %>
+ Response
+<%= raw("""
+{
+ "data": [
+ {
+ "type": "device_created",
+ "message": "Device 'Core Router' was added",
+ "user_email": "admin@example.com",
+ "inserted_at": "2026-02-14T10:30:00Z"
+ },
+ {
+ "type": "alert_triggered",
+ "message": "Alert triggered: ping_down on Core Router",
+ "user_email": null,
+ "inserted_at": "2026-02-14T10:35:00Z"
+ }
+ ]
+}
+""") %>
+