@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Rumble API (deprecated)
@base https://console.rumble.run/api/v1.0
@version 2.15.0
@auth Bearer bearer
@endpoints 116
@hint download_for_search
@toc releases(3), export(19), org(48), account(46)

@group releases
@endpoint GET /releases/agent/version
@desc Returns latest agent version
@returns(200) {id: str(string), version: str(string)} # component version

@endpoint GET /releases/scanner/version
@desc Returns latest scanner version
@returns(200) {id: str(string), version: str(string)} # component version

@endpoint GET /releases/platform/version
@desc Returns latest platform version
@returns(200) {id: str(string), version: str(string)} # component version

@endgroup

@group export
@endpoint GET /export/org/assets.json
@desc Exports the asset inventory
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated}
@returns(200) filtered asset results
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/assets.jsonl
@desc Asset inventory as JSON line-delimited
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated}
@returns(200) filtered asset results
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/assets.csv
@desc Asset inventory as CSV
@optional {search: str # an optional search string for filtering results}
@returns(200) filtered asset results
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/assets.nmap.xml
@desc Asset inventory as Nmap-style XML
@optional {search: str # an optional search string for filtering results}
@returns(200) filtered asset results
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/services.json
@desc Service inventory as JSON
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated}
@returns(200) filtered service results
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/services.jsonl
@desc Service inventory as JSON line-delimited
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated}
@returns(200) filtered service results
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/services.csv
@desc Service inventory as CSV
@optional {search: str # an optional search string for filtering results}
@returns(200) filtered service results
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/sites.json
@desc Export all sites
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated}
@returns(200) all sites
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/sites.jsonl
@desc Site list as JSON line-delimited
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated}
@returns(200) all sites
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/sites.csv
@desc Site list as CSV
@returns(200) all sites
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/wireless.json
@desc Wireless inventory as JSON
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated}
@returns(200) filtered wireless results
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/wireless.jsonl
@desc Wireless inventory as JSON line-delimited
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated}
@returns(200) filtered wireless results
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/wireless.csv
@desc Wireless inventory as CSV
@optional {search: str # an optional search string for filtering results}
@returns(200) filtered wireless results
@errors {401: Access token is missing or invalid}

@endgroup

@group org
@endpoint GET /org/assets/top.types.csv
@desc Top asset types as CSV
@returns(200) top asset types and counts as csv
@errors {401: Access token is missing or invalid}

@endpoint GET /org/assets/top.os.csv
@desc Top asset operating systems as CSV
@returns(200) top operating systems and counts as csv
@errors {401: Access token is missing or invalid}

@endpoint GET /org/assets/top.hw.csv
@desc Top asset hardware products as CSV
@returns(200) top asset hardware platforms and counts as csv
@errors {401: Access token is missing or invalid}

@endpoint GET /org/assets/top.tags.csv
@desc Top asset tags as CSV
@returns(200) top asset tags and counts as csv
@errors {401: Access token is missing or invalid}

@endpoint GET /org/services/top.tcp.csv
@desc Top TCP services as CSV
@returns(200) top TCP services and counts as csv
@errors {401: Access token is missing or invalid}

@endpoint GET /org/services/top.udp.csv
@desc Top UDP services as CSV
@returns(200) top UDP services and counts as csv
@errors {401: Access token is missing or invalid}

@endpoint GET /org/services/top.protocols.csv
@desc Top service protocols as CSV
@returns(200) top service protocols and counts as csv
@errors {401: Access token is missing or invalid}

@endpoint GET /org/services/top.products.csv
@desc Top service products as CSV
@returns(200) top service products and counts as csv
@errors {401: Access token is missing or invalid}

@endpoint GET /org/services/subnet.stats.csv
@desc Subnet utilization statistics as as CSV
@optional {mask: str # an optional subnet mask size (ex:24)}
@returns(200) subnet utilization stats as csv
@errors {401: Access token is missing or invalid}

@endpoint GET /org
@desc Get organization details
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), client_id: str(uuid), download_token: str, download_token_created_at: int(int64), permanent: bool, name: str, description: str, inactive: bool, deactivated_at: int(int64), service_count: int(int64), service_count_tcp: int(int64), service_count_udp: int(int64), service_count_arp: int(int64), service_count_icmp: int(int64), asset_count: int(int64), export_token: str, export_token_created_at: int(int64), export_token_last_used_at: int(int64), export_token_last_used_by: str, export_token_counter: int(int64), project: bool, parent_id: str(uuid), expiration_assets_stale: int(int64), expiration_assets_offline: int(int64), expiration_scans: int(int64)} # organization details
@errors {401: Access token is missing or invalid}

@endpoint PATCH /org
@desc Update organization details
@optional {name: str, description: str, export_token: str, project: str(boolean), parent_id: str(uuid), expiration_assets_stale: str(number), expiration_assets_offline: str(number), expiration_scans: str(number)}
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), client_id: str(uuid), download_token: str, download_token_created_at: int(int64), permanent: bool, name: str, description: str, inactive: bool, deactivated_at: int(int64), service_count: int(int64), service_count_tcp: int(int64), service_count_udp: int(int64), service_count_arp: int(int64), service_count_icmp: int(int64), asset_count: int(int64), export_token: str, export_token_created_at: int(int64), export_token_last_used_at: int(int64), export_token_last_used_by: str, export_token_counter: int(int64), project: bool, parent_id: str(uuid), expiration_assets_stale: int(int64), expiration_assets_offline: int(int64), expiration_scans: int(int64)} # organization details
@errors {401: Access token is missing or invalid}

@endpoint GET /org/key
@desc Get API key details
@returns(200) {id: str(uuid), client_id: str(uuid), organization_id: str(uuid), created_at: int(int64), created_by: str(email), comment: str, last_used_at: int(int64), last_used_ip: str, last_used_ua: str, counter: int(int64), usage_today: int(int64), usage_limit: int(int64), token: str, inactive: bool, type: str} # api key details
@errors {401: Access token is missing or invalid}

@endpoint DELETE /org/key
@desc Remove the current API key
@returns(204) empty response
@errors {401: Access token is missing or invalid}

@endpoint PATCH /org/key/rotate
@desc Rotate the API key secret and return the updated key
@returns(200) {id: str(uuid), client_id: str(uuid), organization_id: str(uuid), created_at: int(int64), created_by: str(email), comment: str, last_used_at: int(int64), last_used_ip: str, last_used_ua: str, counter: int(int64), usage_today: int(int64), usage_limit: int(int64), token: str, inactive: bool, type: str} # api key details
@errors {401: Access token is missing or invalid}

@endpoint GET /org/agents
@desc Get all agents
@returns(200) array of agents
@errors {401: Access token is missing or invalid}

@endpoint GET /org/agents/{agent_id}
@desc Get details for a single agent
@required {agent_id: str(uuid) # UUID of the agent}
@returns(200) {id: str(uuid), client_id: str(uuid), organization_id: str(uuid), created_at: int(int64), updated_at: int(int64), host_id: str, hub_id: str(uuid), name: str(hostname), site_id: str(uuid), last_checkin: int(int64), os: str, arch: str, version: str, external_ip: str, internal_ip: str, system_info: map, connected: bool, inactive: bool, deactivated_at: int(int64)} # agent details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint DELETE /org/agents/{agent_id}
@desc Remove and uninstall an agent
@required {agent_id: str(uuid) # UUID of the agent to remove}
@returns(204) empty response
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint PATCH /org/agents/{agent_id}
@desc Update the site associated with agent
@required {agent_id: str(uuid) # UUID of the agent to update, site_id: str(uuid)}
@returns(200) {id: str(uuid), client_id: str(uuid), organization_id: str(uuid), created_at: int(int64), updated_at: int(int64), host_id: str, hub_id: str(uuid), name: str(hostname), site_id: str(uuid), last_checkin: int(int64), os: str, arch: str, version: str, external_ip: str, internal_ip: str, system_info: map, connected: bool, inactive: bool, deactivated_at: int(int64)} # agent details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint POST /org/agents/{agent_id}/update
@desc Force an agent to update and restart
@required {agent_id: str(uuid) # UUID of the agent to update}
@returns(204) empty response
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /org/sites
@desc Get all sites
@returns(200) array of sites
@errors {401: Access token is missing or invalid}

@endpoint PUT /org/sites
@desc Create a new site
@required {name: str}
@optional {description: str, scope: str, excludes: str}
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), permanent: bool, name: str, description: str, scope: str, excludes: str, subnets: map} # site details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /org/sites/{site_id}
@desc Get site details
@required {site_id: str(uuid) # UUID or name of the site}
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), permanent: bool, name: str, description: str, scope: str, excludes: str, subnets: map} # site details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint DELETE /org/sites/{site_id}
@desc Remove a site and associated assets
@required {site_id: str(uuid) # UUID or name of the site to remove}
@returns(204) empty response
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint PATCH /org/sites/{site_id}
@desc Update a site definition
@required {site_id: str(uuid) # UUID or name of the site to update, name: str}
@optional {description: str, scope: str, excludes: str}
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), permanent: bool, name: str, description: str, scope: str, excludes: str, subnets: map} # site details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint PUT /org/sites/{site_id}/import
@desc Import a scan data file into a site
@required {site_id: str(uuid) # UUID or name of the site to import scan data into}
@returns(200) {id: str(uuid), name: str, description: str, template_id: str(uuid), client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid)} # import task
@errors {401: Access token is missing or invalid, 403: License has expired, 404: Resource not found, 500: Request could not be processed}

@endpoint PUT /org/sites/{site_id}/import/nessus
@desc Import a Nessus scan data file into a site
@required {site_id: str(uuid) # UUID or name of the site to import Nessus scan data into}
@returns(200) {id: str(uuid), name: str, description: str, template_id: str(uuid), client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid)} # import task
@errors {401: Access token is missing or invalid, 403: License has expired, 404: Resource not found, 500: Request could not be processed}

@endpoint PUT /org/sites/{site_id}/scan
@desc Create a scan task for a given site
@required {site_id: str(uuid) # UUID or name of the site to scan}
@returns(200) {id: str(uuid), name: str, description: str, template_id: str(uuid), client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid)} # a created scan task
@errors {401: Access token is missing or invalid, 403: License has expired, 404: Resource not found, 500: Request could not be processed}

@endpoint GET /org/assets
@desc Get all assets
@optional {search: str # an optional search string for filtering results}
@returns(200) array of assets
@errors {401: Access token is missing or invalid}

@endpoint GET /org/assets/{asset_id}
@desc Get asset details
@required {asset_id: str(uuid) # UUID of the asset to retrieve}
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), organization_id: str(uuid), site_id: str(uuid), alive: bool, first_seen: int(int64), last_seen: int(int64), detected_by: str, type: str, os: str, os_version: str, hw: str, addresses: [str], addresses_extra: [str], macs: [str(mac)], mac_vendors: [str], names: [str], domains: [str], service_count: int(int64), service_count_tcp: int(int64), service_count_udp: int(int64), service_count_arp: int(int64), service_count_icmp: int(int64), lowest_ttl: int(int64), lowest_rtt: int(int64), last_agent_id: str(uuid), last_task_id: str(uuid), newest_mac: str(mac), newest_mac_vendor: str, newest_mac_age: int(int64), comments: str, service_ports_tcp: [str(port)], service_ports_udp: [str(port)], service_ports_protocols: [str], service_ports_products: [str], org_name: str, site_name: str, agent_name: str, tags: map, services: map, rtts: map, credentials: map, attributes: map} # asset details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint DELETE /org/assets/{asset_id}
@desc Remove an asset
@required {asset_id: str(uuid) # UUID of the asset to remove}
@returns(204) empty response
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint PATCH /org/assets/{asset_id}/comments
@desc Update asset comments
@required {asset_id: str(uuid) # UUID of the asset to update, comments: str}
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), organization_id: str(uuid), site_id: str(uuid), alive: bool, first_seen: int(int64), last_seen: int(int64), detected_by: str, type: str, os: str, os_version: str, hw: str, addresses: [str], addresses_extra: [str], macs: [str(mac)], mac_vendors: [str], names: [str], domains: [str], service_count: int(int64), service_count_tcp: int(int64), service_count_udp: int(int64), service_count_arp: int(int64), service_count_icmp: int(int64), lowest_ttl: int(int64), lowest_rtt: int(int64), last_agent_id: str(uuid), last_task_id: str(uuid), newest_mac: str(mac), newest_mac_vendor: str, newest_mac_age: int(int64), comments: str, service_ports_tcp: [str(port)], service_ports_udp: [str(port)], service_ports_protocols: [str], service_ports_products: [str], org_name: str, site_name: str, agent_name: str, tags: map, services: map, rtts: map, credentials: map, attributes: map} # asset details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint PATCH /org/assets/{asset_id}/tags
@desc Update asset tags
@required {asset_id: str(uuid) # UUID of the asset to update, tags: str}
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), organization_id: str(uuid), site_id: str(uuid), alive: bool, first_seen: int(int64), last_seen: int(int64), detected_by: str, type: str, os: str, os_version: str, hw: str, addresses: [str], addresses_extra: [str], macs: [str(mac)], mac_vendors: [str], names: [str], domains: [str], service_count: int(int64), service_count_tcp: int(int64), service_count_udp: int(int64), service_count_arp: int(int64), service_count_icmp: int(int64), lowest_ttl: int(int64), lowest_rtt: int(int64), last_agent_id: str(uuid), last_task_id: str(uuid), newest_mac: str(mac), newest_mac_vendor: str, newest_mac_age: int(int64), comments: str, service_ports_tcp: [str(port)], service_ports_udp: [str(port)], service_ports_protocols: [str], service_ports_products: [str], org_name: str, site_name: str, agent_name: str, tags: map, services: map, rtts: map, credentials: map, attributes: map} # asset details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint PATCH /org/assets/bulk/tags
@desc Update tags across multiple assets based on a search query
@required {tags: str, search: str}
@returns(200) status message
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint POST /org/assets/bulk/clearTags
@desc Clear all tags across multiple assets based on a search query
@required {search: str}
@returns(200) status message
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /org/services
@desc Get all services
@optional {search: str # an optional search string for filtering results}
@returns(200) array of services
@errors {401: Access token is missing or invalid}

@endpoint GET /org/services/{service_id}
@desc Get service details
@required {service_id: str(uuid) # UUID of the service to retrieve}
@returns(200) {service_id: str(uuid), service_asset_id: str(uuid), service_created_at: int(int64), service_updated_at: int(int64), service_address: str, service_transport: str, service_vhost: str, service_port: str(port), service_data: map, service_protocol: str, service_summary: str, service_screenshot_link: str, service_link: str, id: str(uuid), created_at: int(int64), updated_at: int(int64), organization_id: str(uuid), site_id: str(uuid), alive: bool, first_seen: int(int64), last_seen: int(int64), detected_by: str, type: str, os: str, os_version: str, hw: str, addresses: [str], addresses_extra: [str], macs: [str(mac)], mac_vendors: [str], names: [str], domains: [str], service_count: int(int64), service_count_tcp: int(int64), service_count_udp: int(int64), service_count_arp: int(int64), service_count_icmp: int(int64), lowest_ttl: int(int64), lowest_rtt: int(int64), last_agent_id: str(uuid), last_task_id: str(uuid), newest_mac: str(mac), newest_mac_vendor: str, newest_mac_age: int(int64), comments: str, service_ports_tcp: [str(port)], service_ports_udp: [str(port)], service_ports_protocols: [str], service_ports_products: [str], org_name: str, site_name: str, agent_name: str, tags: map, services: map, rtts: map, credentials: map, attributes: map} # service details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint DELETE /org/services/{service_id}
@desc Remove a service
@required {service_id: str(uuid) # UUID of the service to remove}
@returns(204) empty response
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /org/wireless
@desc Get all wireless LANs
@optional {search: str # an optional search string for filtering results}
@returns(200) array of wireless LANs
@errors {401: Access token is missing or invalid}

@endpoint GET /org/wireless/{wireless_id}
@desc Get wireless LAN details
@required {wireless_id: str(uuid) # UUID of the wireless LAN to retrieve}
@returns(200) {id: str(uuid), created_at: int(int64), last_seen: int(int64), organization_id: str(uuid), site_id: str(uuid), last_agent_id: str(uuid), last_task_id: str(uuid), essid: str(uuid), bssid: str(mac), type: str, authentication: str, encryption: str, signal: int, channels: str, interface: str, vendor: str, family: str, data: map, org_name: str, site_name: str, agent_name: str} # wireless details
@errors {401: Access token is missing or invalid}

@endpoint DELETE /org/wireless/{wireless_id}
@desc Remove a wireless LAN
@required {wireless_id: str(uuid) # UUID of the wireless LAN to remove}
@returns(204) empty response
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /org/tasks
@desc Get all tasks (last 1000)
@optional {status: str # an optional status string for filtering results, search: str # an optional search string for filtering results}
@returns(200) array of tasks
@errors {401: Access token is missing or invalid}

@endpoint GET /org/tasks/{task_id}
@desc Get task details
@required {task_id: str(uuid) # UUID of the task to retrieve}
@returns(200) {id: str(uuid), name: str, description: str, template_id: str(uuid), client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid)} # task details
@errors {401: Access token is missing or invalid}

@endpoint PATCH /org/tasks/{task_id}
@desc Update task parameters
@required {task_id: str(uuid) # UUID of the task to update, id: str(uuid)}
@optional {name: str, description: str, template_id: str(uuid), client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid)}
@returns(200) {id: str(uuid), name: str, description: str, template_id: str(uuid), client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid)} # task details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /org/tasks/{task_id}/data
@desc Returns a temporary task scan data url
@required {task_id: str(uuid) # UUID of the task}
@returns(200) A URL to a resource
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /org/tasks/{task_id}/changes
@desc Returns a temporary task change report data url
@required {task_id: str(uuid) # UUID of the task}
@returns(200) A URL to a resource
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /org/tasks/{task_id}/log
@desc Returns a temporary task log data url
@required {task_id: str(uuid) # UUID of the task}
@returns(200) A URL to a resource
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint POST /org/tasks/{task_id}/stop
@desc Signal that a task should be stopped or canceledThis will also remove recurring and scheduled tasks
@required {task_id: str(uuid) # UUID of the task to stop}
@returns(200)
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint POST /org/tasks/{task_id}/hide
@desc Signal that a completed task should be hidden
@required {task_id: str(uuid) # UUID of the task to hide}
@returns(200)
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endgroup

@group account
@endpoint GET /account/orgs
@desc Get all organization details
@optional {search: str # an optional search string for filtering results}
@returns(200) array of organizations
@errors {401: Access token is missing or invalid}

@endpoint PUT /account/orgs
@desc Create a new organization
@optional {name: str, description: str, export_token: str, project: str(boolean), parent_id: str(uuid), expiration_assets_stale: str(number), expiration_assets_offline: str(number), expiration_scans: str(number)}
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), client_id: str(uuid), download_token: str, download_token_created_at: int(int64), permanent: bool, name: str, description: str, inactive: bool, deactivated_at: int(int64), service_count: int(int64), service_count_tcp: int(int64), service_count_udp: int(int64), service_count_arp: int(int64), service_count_icmp: int(int64), asset_count: int(int64), export_token: str, export_token_created_at: int(int64), export_token_last_used_at: int(int64), export_token_last_used_by: str, export_token_counter: int(int64), project: bool, parent_id: str(uuid), expiration_assets_stale: int(int64), expiration_assets_offline: int(int64), expiration_scans: int(int64)} # organization details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /account/orgs/{org_id}
@desc Get organization details
@required {org_id: str(uuid) # UUID of the organization to retrieve}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint PATCH /account/orgs/{org_id}
@desc Update organization details
@required {org_id: str(uuid) # UUID of the organization to retrieve}
@optional {name: str, description: str, export_token: str, project: str(boolean), parent_id: str(uuid), expiration_assets_stale: str(number), expiration_assets_offline: str(number), expiration_scans: str(number)}
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), client_id: str(uuid), download_token: str, download_token_created_at: int(int64), permanent: bool, name: str, description: str, inactive: bool, deactivated_at: int(int64), service_count: int(int64), service_count_tcp: int(int64), service_count_udp: int(int64), service_count_arp: int(int64), service_count_icmp: int(int64), asset_count: int(int64), export_token: str, export_token_created_at: int(int64), export_token_last_used_at: int(int64), export_token_last_used_by: str, export_token_counter: int(int64), project: bool, parent_id: str(uuid), expiration_assets_stale: int(int64), expiration_assets_offline: int(int64), expiration_scans: int(int64)} # organization details
@errors {401: Access token is missing or invalid}

@endpoint DELETE /account/orgs/{org_id}
@desc Remove this organization
@required {org_id: str(uuid) # UUID of the organization to retrieve}
@returns(204) empty response
@errors {401: Access token is missing or invalid}

@endpoint DELETE /account/orgs/{org_id}/exportToken
@desc Removes the export token from the specified organization
@required {org_id: str(uuid) # UUID of the organization to retrieve}
@returns(204) empty response
@errors {401: Access token is missing or invalid}

@endpoint PATCH /account/orgs/{org_id}/exportToken/rotate
@desc Rotates the organization export token and returns the updated organization
@required {org_id: str(uuid) # UUID of the organization to retrieve}
@returns(200) {id: str(uuid), created_at: int(int64), updated_at: int(int64), client_id: str(uuid), download_token: str, download_token_created_at: int(int64), permanent: bool, name: str, description: str, inactive: bool, deactivated_at: int(int64), service_count: int(int64), service_count_tcp: int(int64), service_count_udp: int(int64), service_count_arp: int(int64), service_count_icmp: int(int64), asset_count: int(int64), export_token: str, export_token_created_at: int(int64), export_token_last_used_at: int(int64), export_token_last_used_by: str, export_token_counter: int(int64), project: bool, parent_id: str(uuid), expiration_assets_stale: int(int64), expiration_assets_offline: int(int64), expiration_scans: int(int64)} # organization details
@errors {401: Access token is missing or invalid}

@endpoint GET /account/license
@desc Get license details
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint GET /account/sites
@desc Get all sites details across all organizations
@optional {search: str # an optional search string for filtering results}
@returns(200) array of sites
@errors {401: Access token is missing or invalid}

@endpoint GET /account/credentials
@desc Get all account credentials
@optional {search: str # an optional search string for filtering results}
@returns(200) array of credentials
@errors {401: Access token is missing or invalid}

@endpoint PUT /account/credentials
@desc Create a new credential
@optional {name: str, type: str(miradore_api_key_v1/aws_access_secret), acl: map, global: bool, cidrs: str, secret: any}
@returns(200) {id: str(uuid), client_id: str(uuid), name: str, type: str, created_at: int(int64), created_by_id: str(uuid), created_by_email: str(email), acl: map, global: bool, cidrs: [str], last_used_at: int(int64), last_used_by_id: str(uuid)} # credential details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /account/credentials/{credential_id}
@desc Get credential details
@required {credential_id: str(uuid) # UUID of the credential to retrieve}
@returns(200) {id: str(uuid), client_id: str(uuid), name: str, type: str, created_at: int(int64), created_by_id: str(uuid), created_by_email: str(email), acl: map, global: bool, cidrs: [str], last_used_at: int(int64), last_used_by_id: str(uuid)} # credential details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint DELETE /account/credentials/{credential_id}
@desc Remove this credential
@required {credential_id: str(uuid) # UUID of the credential to delete}
@returns(204) empty response
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /account/keys
@desc Get all active API keys
@returns(200) array of keys
@errors {401: Access token is missing or invalid}

@endpoint PUT /account/keys
@desc Create a new key
@optional {comment: str, organization_id: str(uuid)}
@returns(200) {id: str(uuid), client_id: str(uuid), organization_id: str(uuid), created_at: int(int64), created_by: str(email), comment: str, last_used_at: int(int64), last_used_ip: str, last_used_ua: str, counter: int(int64), usage_today: int(int64), usage_limit: int(int64), token: str, inactive: bool, type: str} # key details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /account/keys/{key_id}
@desc Get key details
@required {key_id: str(uuid) # UUID of the key to retrieve}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint DELETE /account/keys/{key_id}
@desc Remove this key
@required {key_id: str(uuid) # UUID of the key to retrieve}
@returns(204) empty response
@errors {401: Access token is missing or invalid}

@endpoint PATCH /account/keys/{key_id}/rotate
@desc Rotates the key secret
@required {key_id: str(uuid) # UUID of the key to retrieve}
@returns(200) {id: str(uuid), client_id: str(uuid), organization_id: str(uuid), created_at: int(int64), created_by: str(email), comment: str, last_used_at: int(int64), last_used_ip: str, last_used_ua: str, counter: int(int64), usage_today: int(int64), usage_limit: int(int64), token: str, inactive: bool, type: str} # key details
@errors {401: Access token is missing or invalid}

@endpoint GET /account/events.json
@desc System event log as JSON
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated}
@returns(200) filtered event results
@errors {401: Access token is missing or invalid}

@endpoint GET /account/events.jsonl
@desc System event log as JSON line-delimited
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated}
@returns(200) filtered event results
@errors {401: Access token is missing or invalid}

@endpoint GET /account/tasks
@desc Get all task details across all organizations (up to 1000)
@optional {search: str # an optional search string for filtering results}
@returns(200) array of tasks
@errors {401: Access token is missing or invalid}

@endpoint GET /account/tasks/templates
@desc Get all scan templates across all organizations (up to 1000)
@optional {search: str # an optional search string for filtering results}
@returns(200) array of scan templates
@errors {401: Access token is missing or invalid, 422: failed to parse search string}

@endpoint POST /account/tasks/templates
@desc Create a new scan template
@required {name: str, global: bool, acl: map}
@optional {description: str, params: map}
@returns(200) {id: str(uuid), client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid), name: str, description: str, grace_period: str, source_id: str, template_id: str(uuid), size_site: int(int64), size_data: int(int64), size_results: int(int64), hosted_zone_id: str(uuid), linked_task_count: int(int32), global: bool, acl: map} # scan template
@errors {400: invalid request body, 401: Access token is missing or invalid, 422: invalid request body}

@endpoint PUT /account/tasks/templates
@desc Update scan template
@required {id: str(uuid), global: bool, acl: map}
@optional {client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid), name: str, description: str, grace_period: str, source_id: str, template_id: str(uuid), size_site: int(int64), size_data: int(int64), size_results: int(int64), hosted_zone_id: str(uuid), linked_task_count: int(int32)}
@returns(200) {id: str(uuid), client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid), name: str, description: str, grace_period: str, source_id: str, template_id: str(uuid), size_site: int(int64), size_data: int(int64), size_results: int(int64), hosted_zone_id: str(uuid), linked_task_count: int(int32), global: bool, acl: map} # scan template
@errors {400: invalid request body, 401: Access token is missing or invalid, 404: scan template or permissions not found, 422: invalid request body}

@endpoint GET /account/tasks/templates/{scan_template_id}
@desc Get scan template details
@required {scan_template_id: str(uuid) # UUID of the scan template to retrieve}
@returns(200) {id: str(uuid), client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid), name: str, description: str, grace_period: str, source_id: str, template_id: str(uuid), size_site: int(int64), size_data: int(int64), size_results: int(int64), hosted_zone_id: str(uuid), linked_task_count: int(int32), global: bool, acl: map} # scan template
@errors {401: Access token is missing or invalid, 404: scan template not found, 422: invalid scan template id}

@endpoint DELETE /account/tasks/templates/{scan_template_id}
@desc Remove scan template
@required {scan_template_id: str(uuid) # UUID of the scan template to remove}
@returns(200) {id: str(uuid), client_id: str(uuid), organization_id: str(uuid), agent_id: str(uuid), site_id: str(uuid), cruncher_id: str(uuid), created_at: int(int64), created_by: str(email), created_by_user_id: str(uuid), updated_at: int(int64), type: str, status: str, error: str, params: map, stats: map, hidden: bool, parent_id: str(uuid), recur: bool, recur_frequency: str, start_time: int(int64), recur_last: int(int64), recur_next: int(int64), recur_last_task_id: str(uuid), name: str, description: str, grace_period: str, source_id: str, template_id: str(uuid), size_site: int(int64), size_data: int(int64), size_results: int(int64), hosted_zone_id: str(uuid), linked_task_count: int(int32), global: bool, acl: map} # scan template
@errors {401: Access token is missing or invalid, 404: scan template not found, 422: invalid request}

@endpoint GET /account/agents
@desc Get all agents across all organizations
@optional {search: str # an optional search string for filtering results}
@returns(200) array of tasks
@errors {401: Access token is missing or invalid}

@endpoint GET /account/users
@desc Get all users
@returns(200) array of users
@errors {401: Access token is missing or invalid}

@endpoint PUT /account/users
@desc Create a new user account
@optional {first_name: str, last_name: str, email: str, client_admin: bool, org_default_role: str, org_roles: map}
@returns(200) {id: str(uuid), client_id: str(uuid), created_at: int(int64), updated_at: int(int64), first_name: str, last_name: str, email: str, client_admin: bool, org_default_role: str, org_roles: map, reset_token_expiration: int(int64), invite_token_expiration: int(int64), last_login_ip: str, last_login_at: int(int64), last_login_ua: str, sso_only: bool, login_failures: int(int64)} # key details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint PUT /account/users/invite
@desc Create a new user account and send an email invite
@optional {first_name: str, last_name: str, email: str, client_admin: bool, org_default_role: str, org_roles: map, subject: str, message: str}
@returns(200) {id: str(uuid), client_id: str(uuid), created_at: int(int64), updated_at: int(int64), first_name: str, last_name: str, email: str, client_admin: bool, org_default_role: str, org_roles: map, reset_token_expiration: int(int64), invite_token_expiration: int(int64), last_login_ip: str, last_login_at: int(int64), last_login_ua: str, sso_only: bool, login_failures: int(int64)} # key details
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint GET /account/users/{user_id}
@desc Get user details
@required {user_id: str(uuid) # UUID of the user to retrieve}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint DELETE /account/users/{user_id}
@desc Remove this user
@required {user_id: str(uuid) # UUID of the user to delete}
@returns(204) empty response
@errors {401: Access token is missing or invalid}

@endpoint PATCH /account/users/{user_id}
@desc Update a user's details
@required {user_id: str(uuid) # UUID of the user to retrieve}
@optional {first_name: str, last_name: str, email: str, client_admin: bool, org_default_role: str, org_roles: map}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint PATCH /account/users/{user_id}/resetMFA
@desc Resets the user's MFA tokens
@required {user_id: str(uuid) # UUID of the user to retrieve}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint PATCH /account/users/{user_id}/resetLockout
@desc Resets the user's lockout status
@required {user_id: str(uuid) # UUID of the user to retrieve}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint PATCH /account/users/{user_id}/resetPassword
@desc Sends the user a password reset email
@required {user_id: str(uuid) # UUID of the user to retrieve}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint GET /account/groups
@desc Get all groups
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint POST /account/groups
@desc Create a new group
@optional {description: str, name: str, expires_at: int(int64), org_default_role: str, org_roles: map}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint PUT /account/groups
@desc Update an existing group
@optional {id: str(uuid), description: str, name: str, expires_at: int(int64), org_default_role: str, org_roles: map}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint GET /account/groups/{group_id}
@desc Get group details
@returns(200)
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint DELETE /account/groups/{group_id}
@desc Remove this group
@returns(204) empty response
@errors {401: Access token is missing or invalid}

@endpoint GET /account/sso/groups
@desc Get all SSO group mappings
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint POST /account/sso/groups
@desc Create a new SSO group mapping
@required {id: str(uuid), group_id: str(uuid), sso_attribute: str, sso_value: str}
@optional {group_name: str, description: str, created_by_email: str, created_at: int(int64), updated_at: int(int64)}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint PUT /account/sso/groups
@desc Update an existing SSO group mapping
@required {id: str(uuid), group_id: str(uuid), sso_attribute: str, sso_value: str}
@optional {group_name: str, description: str, created_by_email: str, created_at: int(int64), updated_at: int(int64)}
@returns(200)
@errors {401: Access token is missing or invalid}

@endpoint GET /account/sso/groups/{group_mapping_id}
@desc Get SSO group mapping details
@returns(200)
@errors {401: Access token is missing or invalid, 404: Resource not found}

@endpoint DELETE /account/sso/groups/{group_mapping_id}
@desc Remove this SSO group mapping
@returns(204) empty response
@errors {401: Access token is missing or invalid}

@endgroup

@group export
@endpoint GET /export/org/assets/sync/created/assets.json
@desc Exports the asset inventory in a sync-friendly manner using created_at as a checkpoint. Requires the Splunk entitlement.
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated, since: int(int64) # an optional unix timestamp to use as a checkpoint}
@returns(200) {since: int(int64), assets: [map]} # filtered asset results with a checkpoint wrapper
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/assets/sync/updated/assets.json
@desc Exports the asset inventory in a sync-friendly manner using updated_at as a checkpoint. Requires the Splunk entitlement.
@optional {search: str # an optional search string for filtering results, fields: str # an optional list of fields to export, comma-separated, since: int(int64) # an optional unix timestamp to use as a checkpoint}
@returns(200) {since: int(int64), assets: [map]} # filtered asset results with a checkpoint wrapper
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/assets.servicenow.csv
@desc Export an asset inventory as CSV for ServiceNow integration
@returns(200) asset export
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/assets.servicenow.json
@desc Exports the asset inventory as JSON
@returns(200) filtered asset results
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/services.servicenow.csv
@desc Export a service inventory as CSV for ServiceNow integration
@returns(200) services export
@errors {401: Access token is missing or invalid}

@endpoint GET /export/org/assets.cisco.csv
@desc Cisco serial number and model name export for Cisco Smart Net Total Care Service.
@optional {search: str # an optional search string for filtering results}
@returns(200) filtered asset results
@errors {401: Access token is missing or invalid}

@endgroup

@end