> ## Documentation Index > Fetch the complete documentation index at: https://docs.osint.ly/llms.txt > Use this file to discover all available pages before exploring further. # Create a new search > Queue a new OSINT search with optional module selection, leak sources, account features, delivery settings, cache mode, and BYOK provider configuration. ## OpenAPI ````yaml /api-reference/openapi.json post /search openapi: 3.1.0 info: title: Osintly API version: 1.0.0 description: OpenAPI specification for the Osintly API service. contact: name: Osintly url: https://docs.osint.ly/api-reference/quick-start servers: - url: https://api.osint.ly description: Production security: [] tags: - name: System description: Health and service checks - name: Auth description: Authorization validation - name: Search description: Create, monitor and retrieve search results - name: Usage description: Rate limit and usage information - name: Radar description: Breach intelligence endpoints (free with API key) - name: Webhooks description: Webhook callback payloads configured from search creation paths: /search: post: tags: - Search summary: Create a new search description: >- Queue a new OSINT search with optional module selection, leak sources, account features, delivery settings, cache mode, and BYOK provider configuration. operationId: createSearch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchCreateRequest' examples: email_search: summary: Email search with selected modules, webhook and BYOK value: query: type: Email Address value: target@example.com modules: mode: selected ids: - 4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f leaks: mode: selected custom_mapping: true sources: - Leak Check - Snusbase features: breached_accounts: true registered_accounts: include cache: mode: prefer delivery: webhook: url: https://client.example/webhooks/osintly secret: super-secret-webhook-key byok: mode: default osint_industries: api_key: oi_xxx timeout: 80 exact_match: true premium: false premium_modules_only: false sherlockeye: api_key: se_xxx additional_modules: - digital_accounts_expansion responses: '200': description: Search queued content: application/json: schema: $ref: '#/components/schemas/SearchCreateResponse' examples: queued: value: data: search: id: d290f1ee-6c54-4b01-90e6-d701748f0851 status: pending query: type: Email Address value: target@example.com created_at: '2026-05-27T12:00:00.000Z' execution: run_id: run_1234567890 cache_mode: prefer links: self: >- https://api.osint.ly/search/d290f1ee-6c54-4b01-90e6-d701748f0851 stream: >- https://api.osint.ly/search/d290f1ee-6c54-4b01-90e6-d701748f0851/stream results: >- https://api.osint.ly/search/d290f1ee-6c54-4b01-90e6-d701748f0851/results leaks: >- https://api.osint.ly/search/d290f1ee-6c54-4b01-90e6-d701748f0851/results/leaks meta: environment: production timestamp: '2026-05-27T12:00:00.000Z' '400': $ref: '#/components/responses/SearchApiError' '401': $ref: '#/components/responses/UnauthorizedError' '429': $ref: '#/components/responses/SearchApiError' '500': $ref: '#/components/responses/SearchApiError' '503': $ref: '#/components/responses/SearchApiError' security: - bearerAuth: [] components: schemas: SearchCreateRequest: type: object required: - query properties: query: $ref: '#/components/schemas/SearchQuery' modules: $ref: '#/components/schemas/SearchModules' leaks: $ref: '#/components/schemas/SearchLeaks' features: $ref: '#/components/schemas/SearchFeatures' cache: $ref: '#/components/schemas/SearchCache' delivery: $ref: '#/components/schemas/SearchDelivery' byok: $ref: '#/components/schemas/SearchByok' additionalProperties: false SearchCreateResponse: type: object required: - data - meta properties: data: type: object required: - search - execution - links properties: search: type: object required: - id - status - query - created_at properties: id: type: string format: uuid status: type: string enum: - pending - processing - finished - failed query: $ref: '#/components/schemas/SearchQuery' created_at: type: string format: date-time execution: type: object required: - run_id - cache_mode properties: run_id: type: string cache_mode: type: string enum: - prefer - bypass links: $ref: '#/components/schemas/SearchLinks' meta: $ref: '#/components/schemas/ResponseMeta' SearchQuery: type: object required: - type - value properties: type: $ref: '#/components/schemas/SearchType' value: type: string additionalProperties: false SearchModules: type: object properties: mode: type: string enum: - all - selected default: all ids: type: array items: type: string format: uuid additionalProperties: false SearchLeaks: type: object properties: mode: type: string enum: - default - selected - none default: default custom_mapping: type: boolean default: false description: Enable Osintly custom leak mapping. Disabled by default. sources: type: array items: $ref: '#/components/schemas/LeakSourceValue' additionalProperties: false SearchFeatures: type: object properties: breached_accounts: type: boolean default: false registered_accounts: type: string enum: - exclude - include - only default: include additionalProperties: false SearchCache: type: object properties: mode: type: string enum: - prefer - bypass default: prefer additionalProperties: false SearchDelivery: type: object properties: webhook: $ref: '#/components/schemas/WebhookConfig' additionalProperties: false SearchByok: type: object properties: mode: type: string enum: - default - only default: default description: >- Use BYOK providers in addition to the standard pipeline, or exclusively when set to only. osint_industries: $ref: '#/components/schemas/SearchByokOsintIndustriesProvider' sherlockeye: $ref: '#/components/schemas/SearchByokSherlockeyeProvider' description: Bring your own external OSINT provider API keys for this search. additionalProperties: false minProperties: 1 SearchLinks: type: object required: - self - stream - results - byok - leaks properties: self: type: string format: uri stream: type: string format: uri results: type: string format: uri byok: type: string format: uri leaks: type: string format: uri ResponseMeta: type: object required: - timestamp properties: environment: type: string timestamp: type: string format: date-time SearchApiErrorResponse: type: object required: - error - meta properties: error: type: object required: - code - message properties: code: type: string message: type: string details: oneOf: - type: string - type: array items: $ref: '#/components/schemas/ValidationIssue' meta: $ref: '#/components/schemas/ResponseMeta' BasicErrorResponse: type: object required: - success - message properties: success: type: boolean enum: - false message: type: string additionalProperties: true SearchType: type: string enum: - Pseudonym - Email Address - Domain Name - Cryptocurrency - IP Address LeakSourceValue: type: string enum: - Hudson Rock - Leak Check - Snusbase - Breach Base - Leak Osint WebhookConfig: type: object required: - url properties: url: type: string format: uri secret: type: string minLength: 8 maxLength: 256 additionalProperties: false SearchByokOsintIndustriesProvider: type: object required: - api_key properties: api_key: type: string minLength: 1 maxLength: 512 description: >- External provider API key sent with the search request and not returned by the API. timeout: type: integer minimum: 25 maximum: 80 description: >- OSINT Industries execution timeout in seconds. type and query are derived from the search and cannot be overridden. exact_match: type: boolean description: >- Forwarded to OSINT Industries when supported by the selected query type. premium: type: boolean description: Enable premium OSINT Industries modules. premium_modules_only: type: boolean description: Only run premium OSINT Industries modules. additionalProperties: false SearchByokSherlockeyeProvider: type: object required: - api_key properties: api_key: type: string minLength: 1 maxLength: 512 description: >- External provider API key sent with the search request and not returned by the API. additional_modules: type: array items: type: string minItems: 1 description: >- Optional Sherlockeye async search modules to request in addition to the default search. type and value are derived from the Osintly search and cannot be overridden. additionalProperties: false ValidationIssue: type: object required: - path - message properties: path: type: string message: type: string responses: SearchApiError: description: Search API error content: application/json: schema: $ref: '#/components/schemas/SearchApiErrorResponse' examples: validation_error: value: error: code: VALIDATION_ERROR message: Invalid request parameters details: - path: query.value message: query.value must be a valid email meta: timestamp: '2026-05-27T12:00:00.000Z' rate_limited: value: error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded details: API usage limits have been reached meta: environment: production timestamp: '2026-05-27T12:00:00.000Z' run_not_found: value: error: code: RUN_NOT_FOUND message: Search run not available details: No active run is associated with this search meta: environment: production timestamp: '2026-05-27T12:00:00.000Z' leak_source_not_found: value: error: code: LEAK_SOURCE_NOT_FOUND message: Leak source not found details: No leaked results source matches 'unknown-source' meta: environment: production timestamp: '2026-05-27T12:00:00.000Z' UnauthorizedError: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' examples: unauthorized: value: success: false message: Unauthorized securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key ````