> ## Documentation Index > Fetch the complete documentation index at: https://docs.techslayers.ca/llms.txt > Use this file to discover all available pages before exploring further. # Start scan > Scan keywords or a domain for breach data and create a stored DarkRecon result. # Start scan Creates a stored scan and returns the `scan_id` you will use for follow-up retrieval. The live API uses `keywords`. If you still send `queries`, your request will not match the current contract. ## Choose one input mode * `keywords`: send one or more search terms such as emails, phone numbers, usernames, IPs, passwords, car plates, social IDs, or composite strings. * `domain`: send a single domain to enumerate breached emails and scan the discovered addresses automatically. Do not send both in the same request. ## Keyword guidance * Each keyword is queried independently against the breach dataset. * Composite queries are supported when you want to correlate multiple terms inside a single search string. * Domain scans can return `discovered_emails` immediately in the `POST /scan` response. ## Response semantics * `scan_id` is the durable identifier for the stored scan. * `status` can be `success`, `no_results`, or `no_queries`. * `total_breaches` is the number of matched breach sources. * Full raw breach records are not returned by `POST /scan`; retrieve them with `GET /scan/{scan_id}`. ## Error behavior * `422`: request validation failed, including a missing `X-API-Key` header or malformed request structure. * `403`: the API key could not be validated. * `502`: the upstream breach-data provider returned an error. ## OpenAPI ````yaml openapi/darkrecon.json POST /scan openapi: 3.0.0 info: title: DarkRecon API description: >- API for scanning keywords or domains for breach data. Results are stored and retrievable via scan UUID. version: 2.2.0 servers: - url: https://darkrecon.1337807.xyz/ description: Production server security: - ApiKeyAuth: [] paths: /scan: post: tags: - Scan summary: Scan keywords or a domain for breach data description: >- Accepts either a list of keywords (emails, phone numbers, usernames, IPs, passwords, car plates, social account IDs, or composite queries) OR a domain name. When a domain is provided, emails are enumerated from breach data for that domain and scanned automatically. Provide one or the other, not both. Results are stored and retrievable via the scan UUID. Passwords in returned records are masked. operationId: scan requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScanRequest' examples: single_email: summary: Scan by email value: keywords: - user@example.com multiple_emails: summary: Scan multiple emails value: keywords: - user@example.com - other@example.com phone: summary: Scan by phone number value: keywords: - '+79002206090' username: summary: Scan by username value: keywords: - ShadowPlayer228 ip: summary: Scan by IP address value: keywords: - 127.0.0.1 composite: summary: Composite query value: keywords: - ShadowPlayer228 example@gmail.com domain: summary: Scan by domain value: domain: example.com responses: '200': description: Scan completed content: application/json: schema: $ref: '#/components/schemas/ScanResponse' examples: success: summary: Breaches found value: scan_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: success total_breaches: 3 domain_success: summary: Domain scan with discovered emails value: scan_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: success total_breaches: 125 discovered_emails: - user@example.com - admin@example.com no_results: summary: No breaches found value: scan_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: no_results total_breaches: 0 '403': description: Invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: Could not validate API key '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' example: detail: - type: missing loc: - header - x-api-key msg: Field required input: null '502': description: Upstream API error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ScanRequest: type: object description: Send exactly one of `keywords` or `domain`. properties: keywords: type: array items: type: string description: >- List of search terms — emails, phone numbers, usernames, IPs, passwords, car plates, social account IDs, or composite queries. Provide this OR domain, not both. example: - user@example.com domain: type: string description: >- Domain name to enumerate emails from and scan. Provide this OR keywords, not both. example: example.com ScanResponse: type: object description: >- Initial acknowledgement returned by `POST /scan`. Use `scan_id` with `GET /scan/{scan_id}` to retrieve full records. properties: scan_id: type: string format: uuid description: >- Unique identifier for retrieving scan results via GET /scan/{scan_id} status: type: string enum: - success - no_results - no_queries description: Scan result status total_breaches: type: integer description: Number of breach databases found minimum: 0 discovered_emails: type: array items: type: string description: >- Emails discovered from domain enumeration (only present when domain was provided) message: type: string description: Additional context (e.g. when no keywords were provided) Error: type: object properties: detail: type: string description: Error message required: - detail HTTPValidationError: type: object properties: detail: type: array items: $ref: '#/components/schemas/ValidationError' description: List of validation issues returned by the API framework. required: - detail ValidationError: type: object properties: loc: type: array description: Where the validation error occurred. items: oneOf: - type: string - type: integer msg: type: string description: Human-readable validation message. type: type: string description: Machine-readable validation error type. input: description: The offending input value when available. required: - loc - msg - type securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication. Create keys via the admin dashboard. ````