> ## Documentation Index > Fetch the complete documentation index at: https://docs.urldna.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Scan > Initiates a new URL scan with customizable parameters. Returns a Scan object immediately with status PENDING. Processing typically completes within 30-60 seconds depending on system load. Poll the GET /v1/scan/ endpoint to retrieve full results once status is DONE. ## OpenAPI ````yaml POST /v1/scan openapi: 3.1.0 info: title: urlDNA API description: >- urlDNA API documentation. This API allows you to scan, analyze, and retrieve insights about URLs, helping to detect potential threats such as phishing, malware, and scams. version: 1.0.0 servers: - url: https://api.urldna.io security: [] paths: /v1/scan: post: tags: - Scan summary: Create scan description: |- Initiates a new URL scan with customizable parameters. Returns a Scan object immediately with status PENDING. Processing typically completes within 30-60 seconds depending on system load. Poll the GET /v1/scan/ endpoint to retrieve full results once status is DONE. operationId: create_scan_v1_scan_post parameters: - name: authorization in: header required: true schema: type: string title: Authorization requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScanRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Scan' '401': description: 'Unauthorized: API Key is missing or invalid.' content: application/json: schema: $ref: '#/components/schemas/APIError' '403': description: 'Forbidden: You do not have permission to access this resource.' content: application/json: schema: $ref: '#/components/schemas/APIError' '405': description: >- Method Not Allowed: The requested HTTP method is not supported for this endpoint. content: application/json: schema: $ref: '#/components/schemas/APIError' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: 'Too Many Requests: Rate limit exceeded.' content: application/json: schema: $ref: '#/components/schemas/APIError' '500': description: 'Internal Server Error: An unexpected error occurred.' content: application/json: schema: $ref: '#/components/schemas/APIError' components: schemas: ScanRequest: properties: submitted_url: type: string title: Submitted Url device: $ref: '#/components/schemas/DeviceEnum' default: DESKTOP user_agent: anyOf: - type: string - type: 'null' title: User Agent http_referer: anyOf: - type: string - type: 'null' title: Http Referer width: anyOf: - type: integer - type: 'null' title: Width height: anyOf: - type: integer - type: 'null' title: Height waiting_time: type: integer maximum: 15 minimum: 3 title: Waiting Time default: 5 scanned_from: type: string title: Scanned From default: DEFAULT private_scan: type: boolean title: Private Scan default: false submitter_tags: items: type: string type: array title: Submitter Tags origin: $ref: '#/components/schemas/OriginEnum' default: API type: object required: - submitted_url title: ScanRequest Scan: properties: id: type: string title: Id description: Unique auto-generated scan identifier. submitted_url: type: string title: Submitted Url description: Original URL submitted for scanning. domain: anyOf: - type: string - type: 'null' title: Domain description: Extracted domain from the submitted URL. target_url: anyOf: - type: string - type: 'null' title: Target Url description: Final destination URL after following all redirects. protocol: anyOf: - type: string - type: 'null' title: Protocol description: Protocol used (HTTP or HTTPS). device: $ref: '#/components/schemas/DeviceEnum' description: Device type used for the scan simulation (DESKTOP or MOBILE). user_agent: anyOf: - type: string - type: 'null' title: User Agent description: User agent string used to simulate the browser environment. http_referer: anyOf: - type: string - type: 'null' title: Http Referer description: >- HTTP Referer header value indicating the originating page for the request. nsfw: anyOf: - type: boolean - type: 'null' title: Nsfw description: >- Indicates whether the page contains Not Safe For Work (NSFW) content such as nudity or adult material. default: false scanned_from: type: string title: Scanned From description: >- Country code from which the scan was initiated. Available for PREMIUM users only. origin: $ref: '#/components/schemas/OriginEnum' description: >- Indicates whether the scan was submitted programmatically via API or manually by a user. width: type: integer title: Width description: Viewport width in pixels used during the scan. height: type: integer title: Height description: Viewport height in pixels used during the scan. private_scan: type: boolean title: Private Scan description: When true, scan results are only accessible to the submitting user. status: $ref: '#/components/schemas/StatusEnum' description: >- Current scan status. PENDING and RUNNING are transient states; DONE and ERROR are terminal states. submitted_date: type: string format: date-time title: Submitted Date description: ISO 8601 timestamp when the scan was submitted. submitter_tags: anyOf: - items: type: string type: array - type: 'null' title: Submitter Tags description: User-defined tags for organizing and categorizing scans. error_code: anyOf: - type: string - type: 'null' title: Error Code description: >- Error code when scan status is ERROR, indicating the reason for failure. type: object required: - id - submitted_url - device - user_agent - scanned_from - origin - width - height - private_scan - status - submitted_date title: Scan APIError: properties: detail: type: string title: Detail example: Error description message type: object required: - detail title: APIError HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError DeviceEnum: type: string enum: - DESKTOP - MOBILE title: DeviceEnum OriginEnum: type: string enum: - USER - API - TELEGRAM title: OriginEnum StatusEnum: type: string enum: - PENDING - RUNNING - DONE - ERROR - PAGE_NOT_AVAILABLE title: StatusEnum ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````