openapi: 3.2.0 info: title: DomScan Domain Lifecycle API description: DomScan is a domain intelligence API providing domain analysis tools. version: 2.15.0 contact: name: DomScan Support url: https://domscan.net email: support@domscan.net termsOfService: https://domscan.net/legal/terms license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://domscan.net description: Production server security: - apiKey: [] tags: - name: Domain Lifecycle description: Registration lifecycle, expiry, renewal, and deletion timing signals paths: /v1/lifecycle: get: tags: - Domain Lifecycle summary: Domain lifecycle information description: Get domain lifecycle information including registration date, expiration date, age, days until expiry, and current lifecycle phase. Supports compound public suffix domains such as co.uk and com.au. Returns Fastly-style status flags. operationId: getDomainLifecycle parameters: - name: domain in: query required: true description: Domain to check lifecycle for schema: type: string example: bbc.co.uk responses: '200': description: Lifecycle information content: application/json: schema: $ref: '#/components/schemas/LifecycleResponse' example: domain: bbc.co.uk tld: co.uk registered: '1997-08-01T00:00:00Z' expires: '2026-08-01T00:00:00Z' updated: '2024-08-01T00:00:00Z' age_days: 10515 expires_in_days: 474 phase: active status_flags: - clientTransferProhibited - serverTransferProhibited status: clientTransferProhibited serverTransferProhibited events: - action: registration date: '1997-08-01T00:00:00Z' - action: last changed date: '2024-08-01T00:00:00Z' - action: expiration date: '2026-08-01T00:00:00Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '429': $ref: '#/components/responses/RateLimited' '502': description: RDAP provider returned an unreachable or invalid response content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: RDAP provider rate limited the request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-domscan-credits: model: per_request default: 2 components: responses: RateLimited: description: Rate limit exceeded. Free accounts can sustain 120 requests per minute per account with a burst capacity of 60. Free bulk traffic is additionally limited to 20 requests per minute per account across all bulk endpoints and 100 per minute per IPv4 address or IPv6 /56 network. Paid accounts can sustain 600 requests per minute with a burst capacity of 120. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying X-RateLimit-Plan: schema: type: string enum: - free - paid description: The account plan whose policy was applied. X-RateLimit-Limit: schema: type: integer description: The immediate burst capacity, or the active bulk fixed-window limit when a bulk-specific limit is exceeded. X-RateLimit-Remaining: schema: type: integer example: 0 description: Immediate burst tokens remaining, or requests remaining in the active bulk fixed window. X-RateLimit-Policy: schema: type: string description: Machine-readable summary of the active tier and limit policy. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMITED message: Rate limit exceeded. Please wait before making more requests. PaymentRequired: description: Insufficient credits for this request headers: X-Credits-Remaining: schema: type: integer description: Credits remaining on your API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INSUFFICIENT_CREDITS message: Insufficient credits. This endpoint costs 2 credits but you have 0. Purchase more at https://domscan.net/billing or wait for your monthly reset. credits_remaining: 0 credits_required: 2 purchase_url: https://domscan.net/billing Unauthorized: description: 'Authentication required. All API endpoints require a valid API key (x-api-key header or Authorization: Bearer) or an active session cookie.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: AUTH_REQUIRED message: 'Authentication required. Provide an API key via x-api-key header or Authorization: Bearer header.' docs: https://domscan.net/docs/authentication get_key: https://domscan.net/login BadRequest: description: Bad request - invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: Invalid domain format suggestion: Domain must be a valid format like example.com schemas: LifecycleResponse: type: object description: Domain lifecycle information properties: domain: type: string description: Domain checked tld: type: string description: Effective suffix or public suffix for the registrable domain registered: type: string format: date-time description: Registration date expires: type: string format: date-time description: Expiration date updated: type: string format: date-time description: Last updated date age_days: type: integer description: Domain age in days expires_in_days: type: integer description: Days until expiration phase: type: string enum: - available - active - expiring - deleting - reserved - unknown description: Current lifecycle phase status_flags: type: array items: type: string description: Fastly-style status flags from registry status: type: string description: Space-separated lifecycle flags events: type: array items: type: object properties: action: type: string date: type: string format: date-time description: Registry events timeline ErrorResponse: type: object description: Standard error response format properties: error: type: object properties: code: type: string description: Error code for programmatic handling example: INVALID_DOMAIN type: type: string enum: - authentication_error - credits_error - permission_error - not_found_error - conflict_error - rate_limit_error - timeout_error - validation_error - upstream_error - api_error - request_error description: Stable error category used by official SDK subclasses message: type: string description: Human-readable error message example: Invalid domain format status: type: integer minimum: 400 maximum: 599 description: HTTP status repeated in the JSON error for queue and log processors retryable: type: boolean description: Whether retrying can be appropriate after applying retry guidance request_id: type: string description: Request identifier matching the X-Request-Id response header suggestion: type: string description: Suggestion for fixing the error details: type: object description: Optional structured context for the error additionalProperties: true retry_after: type: integer minimum: 0 description: Seconds to wait before retrying when the error is temporary example: 300 docs_url: type: string description: Link to relevant documentation example: /docs#parameters required: - type - code - message - status - retryable - request_id - docs_url securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: 'API key for authentication. Get yours free at https://domscan.net. Also accepts Authorization: Bearer header.' sessionCookie: type: apiKey in: cookie name: session description: Active DomScan browser session. Used by account-management endpoints. externalDocs: description: Full API Documentation url: https://domscan.net/docs x-rapidapi-product: domscan x-domscan-rate-limits: free: general: scope: account sustained_requests_per_minute: 120 burst_capacity: 60 shared_across_api_keys_and_sessions: true bulk: scope: all bulk endpoints combined account_requests_per_minute: 20 network_requests_per_minute: 100 ipv6_network_prefix: 56 paid: general: scope: API key for key-authenticated requests; IP for browser sessions sustained_requests_per_minute: 600 burst_capacity: 120 free_bulk_budget_applies: false response: status: 429 retry_header: Retry-After headers_on_every_authenticated_response: - X-RateLimit-Plan - X-RateLimit-Limit - X-RateLimit-Remaining - X-RateLimit-Policy burst_headers: - X-RateLimit-Limit - X-RateLimit-Remaining policy_header: X-RateLimit-Policy x-domscan-response-metadata: compatibility: additive response headers; established JSON success bodies are unchanged headers: X-Request-Id: Unique request identifier for logs and support X-API-Version: DomScan API release version X-Response-Time: Server processing duration in milliseconds X-Credits-Requested: Credits requested before refund settlement X-Credits-Charged: Credits retained after settlement X-Credits-Refunded: Credits returned during settlement X-Credits-Remaining: Authenticated account balance after the request X-Data-Freshness: fresh, cached, stale, mixed, or unknown X-RateLimit-Limit: Active burst capacity X-RateLimit-Remaining: Remaining burst capacity X-RateLimit-Plan: Active plan, or not_applicable before authentication X-RateLimit-Policy: Machine-readable active rate policy