> ## 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 Search
> Queue a new search task and optionally configure a webhook callback.
`Domain Name` and `IP Address` still work in this endpoint, but they will soon stop being supported in the Search API. Their replacements for new lookups are [Domain Intelligence](/tools-reference/domain-intelligence) and [IP Intelligence](/tools-reference/ip-intelligence). No cutoff date has been announced. The website's free previews are not available through this endpoint.
## Enable CrossSearch
CrossSearch follows profile links found in result cards and runs compatible modules within the same search. For example, a Linktree result can lead to a YouTube or Instagram result when a matching module accepts the detected link.
**CrossSearch is disabled by default in the API.** Set `features.crosssearch` to `true` in each search request to enable it. Omitting the option or setting it to `false` leaves it disabled.
```bash theme={null}
curl --request POST 'https://api.osint.ly/search' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"query": {
"type": "Pseudonym",
"value": "mike"
},
"modules": {
"mode": "all"
},
"features": {
"crosssearch": true,
"registered_accounts": "exclude"
}
}'
```
The discovered results arrive through the existing search stream. CrossSearch follows one hop from the initial result cards; its discovered cards do not trigger further hops.
In the Osintly app, CrossSearch is available on **Pro and Ultimate**, including those organization plans. It is enabled by default for eligible app searches and can be disabled in search settings. App subscriptions and [API subscriptions](/api-reference/quick-start) are separate; API searches require the explicit option above.
## Run a temporary search
To run a search without Osintly storing it or its results, send the same body to `POST /search/temporary`. The response is a Server-Sent Events stream instead of a JSON body, and the search cannot be fetched afterwards. Delivery webhooks and BYOK are not available in this mode.
This endpoint does not accept a `temporary` field: it returns `400 USE_TEMPORARY_ENDPOINT` and starts no search.
See [Temporary Searches](/api-reference/temporary-searches) for the stream format and limits.
## OpenAPI
````yaml 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. Domain Name and IP Address remain accepted for now, but
will soon stop being supported in the Search API.
operationId: createSearch
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchCreateRequest'
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:
crosssearch:
type: boolean
default: false
description: >-
Automatically run compatible modules on profile links found in
result cards. Disabled by default; set features.crosssearch to true
to enable it for this search. Results use the same search stream and
include their source provenance.
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
description: >-
Currently accepted Search API types. Domain Name and IP Address will
soon stop being supported here; migrate those lookups to the
corresponding intelligence tools. No cutoff date has been announced.
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
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.