Monitor domains, read scan results and issue free certificates from your own code or an AI agent. Generated from the running code, so it matches what the API returns. Machine-readable: openapi.json.
https://tlsradar.com/api/v1.data: {"data": {...}} for one record, {"data": [...]} for a list.{"error": "..."} or {"errors": ["..."]} with a 4xx status. The full machine-readable spec is at /api/v1/openapi.json.Authorization: Bearer <token> on every authenticated request./api_keys) or with POST /api/v1/api_keys. A key is shown once. New keys get the read scope unless you choose more.read: Read access to scans, monitors, teams, and account.write: Create and modify monitors, teams, scans.admin: All read + write plus account-level operations.admin includes write and read. A request with too narrow a credential gets 403 with required_scope and your_scopes./info, /pricing, /features, /openapi.json): 100 requests per minute per IP address.POST /scan): 20 per hour per IP address, and 10 per hour for any one scanned domain.retry_after in seconds and a Retry-After header.retry_after when it is too soon). Paid plans have no cooldown. The team owner's plan sets it, whoever asks for the scan.Publicly accessible endpoints (no authentication required)
currency (string)tiers (array of object)Free SSL/TLS scanner - no authentication required
domain (string, required): Domain to scan (e.g., example.com)data.domain (string): Scanned domaindata.grade (string, one of A+/A/B/C/D/F, may be null): Overall SSL/TLS grade (null while pending)data.scan_status (string, one of pending/success/failed): Current scan status. Poll until not 'pending'.data.scanned_at (date-time)data.share_token (string): Token for sharing/polling this resultdata.share_url (uri): Shareable URL for this resultdata.pdf_url (uri, may be null): PDF report download URL (null while pending)data.expiration_date (date-time, may be null)data.issues (array of object)data.certificate (object)data.monitor_cta (object): Call-to-action for continuous monitoring signupdata.domain (string): Scanned domaindata.grade (string, one of A+/A/B/C/D/F, may be null): Overall SSL/TLS grade (null while pending)data.scan_status (string, one of pending/success/failed): Current scan status. Poll until not 'pending'.data.scanned_at (date-time)data.share_token (string): Token for sharing/polling this resultdata.share_url (uri): Shareable URL for this resultdata.pdf_url (uri, may be null): PDF report download URL (null while pending)data.expiration_date (date-time, may be null)data.issues (array of object)data.certificate (object)data.monitor_cta (object): Call-to-action for continuous monitoring signupshare_token (string, required): Unique share token from a scan resultdata.domain (string): Scanned domaindata.grade (string, one of A+/A/B/C/D/F, may be null): Overall SSL/TLS grade (null while pending)data.scan_status (string, one of pending/success/failed): Current scan status. Poll until not 'pending'.data.scanned_at (date-time)data.share_token (string): Token for sharing/polling this resultdata.share_url (uri): Shareable URL for this resultdata.pdf_url (uri, may be null): PDF report download URL (null while pending)data.expiration_date (date-time, may be null)data.issues (array of object)data.certificate (object)data.monitor_cta (object): Call-to-action for continuous monitoring signupshare_token (string, required): Unique share token from a scan resultshare_token (string, required): Unique share token from a scan resultemail (email, required): Recipient email addressdata.message (string)data.domain (string)data.email (email)share_token (string, required): Unique share token from a scan resultemail (email, required): Recipient email addressdata.message (string)data.domain (string)data.email (email)Team management operations
read scope.data[].id (uuid)data[].name (string)data[].status (string, one of active/disabled)data[].owner_id (uuid)data[].created_at (date-time)data[].updated_at (date-time)data[].stats (object)write scope.team.name (string, required): Team namedata.id (uuid)data.name (string)data.status (string, one of active/disabled)data.owner_id (uuid)data.created_at (date-time)data.updated_at (date-time)data.stats (object)read scope. Any accepted member of the team (owner, admin or guest).team_id (uuid, required): Team UUIDdata.id (uuid)data.name (string)data.status (string, one of active/disabled)data.owner_id (uuid)data.created_at (date-time)data.updated_at (date-time)data.stats (object)data.members (array of object): Accepted members onlydata.scan_groups (array of object)write scope. Team owner or admin. Guests have read-only access and get 403.team_id (uuid, required): Team UUIDteam.name (string)data.id (uuid)data.name (string)data.status (string, one of active/disabled)data.owner_id (uuid)data.created_at (date-time)data.updated_at (date-time)data.stats (object)write scope. Team owner only.team_id (uuid, required): Team UUIDDomain monitoring group operations
read scope. Any accepted member of the team (owner, admin or guest).team_id (uuid, required): Team UUIDdata[].id (uuid)data[].name (string)data[].scan_port (integer)data[].status (string, one of active/disabled)data[].hosts_count (integer)data[].created_at (date-time)data[].updated_at (date-time)hosts in one request. This is the way to add many domains at once; to add one domain to an existing group, use POST /teams/{team_id}/scan_groups/{scan_group_id}/hosts. Requires the write scope. Team owner or admin. Guests have read-only access and get 403. Every address in hosts counts against the team owner's domain limit; a list that would exceed it is rejected with 422 and nothing is created. Creating a group also starts a scan unless the caller's scan cooldown is active.team_id (uuid, required): Team UUIDscan_group.friendly_name (string, required): Name for the scan groupscan_group.scan_port (integer): Port to scanscan_group.hosts (string): Comma or space-separated list of domains to monitor, all added in this requestdata.id (uuid)data.name (string)data.scan_port (integer)data.status (string, one of active/disabled)data.hosts_count (integer)data.created_at (date-time)data.updated_at (date-time)read scope. Any accepted member of the team (owner, admin or guest).team_id (uuid, required): Team UUIDid (uuid, required): Resource UUIDdata.id (uuid)data.name (string)data.scan_port (integer)data.status (string, one of active/disabled)data.hosts_count (integer)data.created_at (date-time)data.updated_at (date-time)data.hosts (array of object)data.schedule (object): Present when the group has a schedulewrite scope. Team owner or admin. Guests have read-only access and get 403. hosts replaces the group's list: addresses not listed are removed, new ones added (and counted against the owner's domain limit).team_id (uuid, required): Team UUIDid (uuid, required): Resource UUIDdata.id (uuid)data.name (string)data.scan_port (integer)data.status (string, one of active/disabled)data.hosts_count (integer)data.created_at (date-time)data.updated_at (date-time)write scope. Team owner or admin. Guests have read-only access and get 403.team_id (uuid, required): Team UUIDid (uuid, required): Resource UUIDIndividual domain/host operations
read scope. Any accepted member of the team (owner, admin or guest).team_id (uuid, required): Team UUIDscan_group_id (uuid, required): Scan group UUIDdata[].id (uuid)data[].address (string): Domain name (e.g., example.com)data[].status (string, one of active/disabled)data[].last_scan_status (string, may be null)data[].last_scanned_at (date-time, may be null)data[].expiration_date (date-time, may be null)data[].expiring_soon (boolean): True if the certificate is unexpired and inside its expiry-warning window. The window opens shortly after an automated client should have renewed (a third of the lifetime left) and is never longer than 30 days: 28 days for a 90-day certificate, 19 for a 64-day onedata[].created_at (date-time)data[].updated_at (date-time)write scope. Team owner or admin. Guests have read-only access and get 403. 402 when the team owner's plan has no domain left (the body says which plan and how to upgrade).team_id (uuid, required): Team UUIDscan_group_id (uuid, required): Scan group UUIDhost.address (string, required): Domain name (e.g., example.com)data.id (uuid)data.address (string): Domain name (e.g., example.com)data.status (string, one of active/disabled)data.last_scan_status (string, may be null)data.last_scanned_at (date-time, may be null)data.expiration_date (date-time, may be null)data.expiring_soon (boolean): True if the certificate is unexpired and inside its expiry-warning window. The window opens shortly after an automated client should have renewed (a third of the lifetime left) and is never longer than 30 days: 28 days for a 90-day certificate, 19 for a 64-day onedata.created_at (date-time)data.updated_at (date-time)read scope. Any accepted member of the team (owner, admin or guest).team_id (uuid, required): Team UUIDscan_group_id (uuid, required): Scan group UUIDid (uuid, required): Resource UUIDdata.id (uuid)data.address (string): Domain name (e.g., example.com)data.status (string, one of active/disabled)data.last_scan_status (string, may be null)data.last_scanned_at (date-time, may be null)data.expiration_date (date-time, may be null)data.expiring_soon (boolean): True if the certificate is unexpired and inside its expiry-warning window. The window opens shortly after an automated client should have renewed (a third of the lifetime left) and is never longer than 30 days: 28 days for a 90-day certificate, 19 for a 64-day onedata.created_at (date-time)data.updated_at (date-time)data.latest_scan (object): Present once the host has been scannedwrite scope. Team owner or admin. Guests have read-only access and get 403.team_id (uuid, required): Team UUIDscan_group_id (uuid, required): Scan group UUIDid (uuid, required): Resource UUIDScan operations and results
write scope. Team owner or admin. Guests have read-only access and get 403.team_id (uuid, required): Team UUIDid (uuid, required): Resource UUIDmessage (string)scan_group_id (uuid): Scan group scans onlydomains_scanned (integer): Scan group scans onlyhost_id (uuid): Host scans onlyaddress (string): Host scans onlywrite scope. Team owner or admin. Guests have read-only access and get 403.team_id (uuid, required): Team UUIDscan_group_id (uuid, required): Scan group UUIDid (uuid, required): Resource UUIDmessage (string)scan_group_id (uuid): Scan group scans onlydomains_scanned (integer): Scan group scans onlyhost_id (uuid): Host scans onlyaddress (string): Host scans onlyread scope. Any accepted member of the team (owner, admin or guest). The 50 most recent results, newest first. scan_data is only in the single-result view.team_id (uuid, required): Team UUIDscan_group_id (uuid, required): Scan group UUIDhost_id (uuid, required): Host UUIDdata[].id (uuid)data[].scanned_at (date-time)data[].status (string)data[].host_address (string)data[].expiration_date (date-time, may be null)data[].elapsed_time_seconds (number, may be null)read scope. Any accepted member of the team (owner, admin or guest).team_id (uuid, required): Team UUIDscan_group_id (uuid, required): Scan group UUIDhost_id (uuid, required): Host UUIDid (uuid, required): Resource UUIDdata.id (uuid)data.scanned_at (date-time)data.status (string)data.host_address (string)data.expiration_date (date-time, may be null)data.elapsed_time_seconds (number, may be null)data.scan_data (object): The full scanner output: certificates, protocols, cipher suites and vulnerability checksAPI key management
read scope.data[].id (uuid)data[].name (string)data[].key_prefix (string): The key's first 8 characters followed by asterisksdata[].scopes (array of string)data[].status (string, one of active/revoked)data[].team_id (uuid, may be null)data[].last_used_at (date-time, may be null)data[].expires_at (date-time, may be null)data[].created_at (date-time)admin scope.api_key.name (string, required): Name for the API keyapi_key.scopes (array of string, one of read/write/admin)api_key.team_id (uuid): Scope key to specific teamapi_key.expires_at (date-time): Expiration datedata.id (uuid)data.name (string)data.key_prefix (string): The key's first 8 characters followed by asterisksdata.scopes (array of string)data.status (string, one of active/revoked)data.team_id (uuid, may be null)data.last_used_at (date-time, may be null)data.expires_at (date-time, may be null)data.created_at (date-time)raw_key (string): The full key. Shown once; store it now.warning (string)read scope.id (uuid, required): Resource UUIDdata.id (uuid)data.name (string)data.key_prefix (string): The key's first 8 characters followed by asterisksdata.scopes (array of string)data.status (string, one of active/revoked)data.team_id (uuid, may be null)data.last_used_at (date-time, may be null)data.expires_at (date-time, may be null)data.created_at (date-time)admin scope.id (uuid, required): Resource UUIDCurrent user information
read scope.data.id (uuid)data.email (email)data.name (string)data.first_name (string, may be null)data.last_name (string, may be null)data.status (string)data.email_confirmed (boolean)data.created_at (date-time)data.teams_count (integer)data.api_access (boolean)data.subscription (object, may be null)data.plan (object)data.limits (object): null means no cap. Accounts with a scan cooldown (free plan, trial) are limited by it, not by scans_per_day; manual_scans states the rule that appliesdata.usage (object)Convenience: certificates expiring within a window
read scope.within (integer): Days from now to look aheaddata[].host_id (uuid)data[].address (string)data[].expiration_date (date-time)data[].days_until_expiration (integer)data[].last_scanned_at (date-time)data[].scan_group (object)data[].team (object)meta (object)Model Context Protocol (JSON-RPC 2.0) transport for AI agents
jsonrpc (string, one of 2.0, required)id (object): JSON-RPC request id (number, string, or null)method (string, required)params (object)The same account and certificate actions as tools for AI agents, at POST /api/v1/mcp (JSON-RPC 2.0). Certificate tools issue free Let's Encrypt certificates through Beacon; monitoring tools act on your TLS Radar account.
domain (string, required): Hostname to scan (e.g. example.com). No scheme, no path.client_id (string): Optional anonymous install id from ~/.config/tlsradar/install_id. Pass it for funnel attribution. If you omit it, the response's install_id is a fresh one to save there.challenge: "dns-01" (default; publish a TXT record; covers apex + www) or "http-01" (serve a file over HTTP on port 80; issues the exact domain only). dns-01 with a DNS-provider API token is the most automatable; http-01 suits a server you control on port 80. Returns an order_id plus either dns_records (dns-01) or http_files (http-01) to put in place. Next: poll check_certificate_propagation until all_found, then call finalize_certificate. Strongly prefer the CSR path at finalize (the private key never leaves the user's machine). Issuing automatically offers the user ongoing monitoring by email once it completes - don't add a monitor manually afterward.domain (string, required): Apex domain, no scheme/www (e.g. example.com).email (string, required): Contact email for Let's Encrypt expiry notices and the monitoring handoff.challenge (string, one of dns-01/http-01): Validation method: dns-01 (default) or http-01.marketing_consent (boolean): Only true if the user explicitly opts in to a free account + reminder email. Default false.client_id (string): Optional anonymous install id from ~/.config/tlsradar/install_id (funnel attribution). If omitted, the response's install_id is a fresh one to save there.order_id (string, required): The order_id from create_certificate.handoff object - relay handoff.message to the user and do NOT separately call add_monitor; the cert→monitoring handoff is automatic and server-side.order_id (string, required): The order_id from create_certificate.csr_pem (string): PEM CERTIFICATE REQUEST covering exactly {domain, www.domain}. Preferred - key stays local.passphrase (string): Fallback only: ≥8 chars, protects a returned PKCS#12 bundle. Omit when using csr_pem.max_wait_seconds (integer): How long to wait for validation server-side. Default 60, capped at 75.resume_token (string): Optional. The resume_token from create_certificate; pass it to finalize an order whose row Beacon already purged (~24h).order_id (string, required): The order_id from create_certificate.order_id (string, required): The original order_id to clone. If you don't have one, use create_certificate instead.nudge object, the user is at their monitor cap - surface it casually ONCE (lead with nudge.recommended_upgrade, mention nudge.also_available in one closing line); don't force it if it doesn't fit the conversation.recommended_upgrade (it carries the plan name and price), mention also_available tiers in a single closing line, and offer removing an existing monitor as the free alternative. Don't dump a full tier comparison; that's choice paralysis at the moment of action.write scope, and an owner or admin role in the team it changes.domain (string, required): Hostname to monitor (e.g. example.com). No scheme, no path.write scope, and an owner or admin role in the team it changes.domains (array of string, required): List of hostnames to monitorwrite scope, and an owner or admin role in the team it changes.domain (string): Domain to stop monitoringhost_id (string): UUID of the host (alternative to domain)nudge object, the user is watching enough soon-to-expire certs to benefit from a higher tier - mention it casually ONCE (lead with nudge.recommended_upgrade); skip it if it doesn't fit.within (integer): Days from now to look aheaddomain (string, required): Domain name as it appears in list_monitorslimit (integer): Max results to returnexport). Skips domains the user is already monitoring; honors the plan's domain limit. Returns a per-domain status.write scope, and an owner or admin role in the team it changes.payload (object, required): Export payload, version 1.0. Use the export tool to generate one.write scope, and the team owner.email (string, required): Email address of the person to inviteteam_id (string): Team UUID; defaults to the current teamrole (string, one of guest/admin): Invitee role: guest or admin. Defaults to guest.