> ## Documentation Index
> Fetch the complete documentation index at: https://docs.realtycrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Search agents
> Proposed interface. Enable only for documented and verified source/country capabilities. Dedicated source search contract; no blanket platform support
This operation is defined in the API contract but is not currently enabled.
Check [live capabilities](https://realtycrawl.dev/v1/meta/capabilities) before calling this operation. A documented contract does not imply active coverage for every source or country.
## OpenAPI
````yaml POST /v1/agents/search
openapi: 3.1.0
info:
title: RealtyCrawl proposed unified API
version: 0.1.0
description: >-
Research draft dated 2026-10-13. No production server or enabled platform
coverage is implied. Country and operation capabilities must be checked.
servers:
- url: https://realtycrawl.dev
security:
- ApiKeyAuth: []
externalDocs:
url: https://docs.realtycrawl.dev
paths:
/v1/agents/search:
post:
tags:
- agents
summary: Search agents
description: >-
Proposed interface. Enable only for documented and verified
source/country capabilities. Dedicated source search contract; no
blanket platform support
operationId: searchAgents
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EntitySearchRequest'
responses:
'200':
description: Successful response; meta discloses source completeness
content:
application/json:
schema:
$ref: '#/components/schemas/searchAgentsResponse'
default:
description: Typed error response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
EntitySearchRequest:
type: object
properties:
platforms:
type: array
items:
type: string
minItems: 1
maxItems: 5
query:
type: string
location:
$ref: '#/components/schemas/LocationSelector'
limit:
type: integer
minimum: 1
maximum: 100
default: 20
cursor:
type: string
required:
- platforms
additionalProperties: false
anyOf:
- required:
- query
- required:
- location
searchAgentsResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Agent'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
additionalProperties: false
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
retryable:
type: boolean
details:
type: array
items:
$ref: '#/components/schemas/SourceOutcome'
required:
- code
- message
- retryable
additionalProperties: false
request_id:
type: string
required:
- error
- request_id
additionalProperties: false
LocationSelector:
oneOf:
- type: object
properties:
kind:
const: text
query:
type: string
country:
type: string
required:
- kind
- query
- country
additionalProperties: false
- type: object
properties:
kind:
const: postal_code
postal_code:
type: string
country:
type: string
required:
- kind
- postal_code
- country
additionalProperties: false
- type: object
properties:
kind:
const: bbox
bbox:
type: array
items:
type: number
minItems: 4
maxItems: 4
required:
- kind
- bbox
additionalProperties: false
description: >-
west,south,east,north in WGS84; bounds and antimeridian handling
validated at runtime.
- type: object
properties:
kind:
const: radius
latitude:
type: number
minimum: -90
maximum: 90
longitude:
type: number
minimum: -180
maximum: 180
radius_meters:
type: number
exclusiveMinimum: 0
maximum: 100000
required:
- kind
- latitude
- longitude
- radius_meters
additionalProperties: false
- type: object
properties:
kind:
const: polygon
geometry:
type: object
properties:
type:
const: Polygon
coordinates:
type: array
items:
type: array
minItems: 4
items:
type: array
items:
type: number
minItems: 2
maxItems: 2
required:
- type
- coordinates
additionalProperties: false
required:
- kind
- geometry
additionalProperties: false
description: >-
GeoJSON WGS84 polygon with closed rings. Ring closure and coordinate
bounds validated at runtime.
- type: object
properties:
kind:
const: source_region
platform:
type: string
region_id:
type: string
country:
type: string
required:
- kind
- platform
- region_id
- country
additionalProperties: false
Agent:
type: object
properties:
id:
type: string
source:
$ref: '#/components/schemas/Source'
name:
anyOf:
- type: string
- type: 'null'
agency_id:
anyOf:
- type: string
- type: 'null'
profile_url:
anyOf:
- type: string
- type: 'null'
professional_contacts:
type: array
items:
type: object
properties:
kind:
type: string
enum:
- business_phone
- business_email
- website
value:
type: string
required:
- kind
- value
additionalProperties: false
extensions:
type: object
properties: {}
required: []
additionalProperties: true
required:
- id
- source
additionalProperties: false
Meta:
type: object
properties:
request_id:
type: string
schema_version:
type: string
generated_at:
type: string
format: date-time
completeness:
type: string
enum:
- complete
- partial
- unknown
sources:
type: array
items:
$ref: '#/components/schemas/SourceOutcome'
warnings:
type: array
items:
type: object
properties:
code:
type: string
message:
type: string
field:
type: string
required:
- code
- message
additionalProperties: false
pagination:
type: object
properties:
next_cursor:
anyOf:
- type: string
- type: 'null'
has_more:
type: boolean
returned:
type: integer
total:
anyOf:
- type: integer
- type: 'null'
total_relation:
type: string
enum:
- exact
- lower_bound
- unknown
required:
- next_cursor
- has_more
- returned
- total
- total_relation
additionalProperties: false
property_groups:
type: array
items:
$ref: '#/components/schemas/PropertyGroup'
required:
- request_id
- schema_version
- generated_at
- completeness
- sources
additionalProperties: false
SourceOutcome:
type: object
properties:
platform:
type: string
provider:
anyOf:
- type: string
- type: 'null'
status:
type: string
enum:
- success
- partial
- failed
- unsupported
error_code:
anyOf:
- type: string
- type: 'null'
truncated:
type: boolean
observed_at:
anyOf:
- type: string
format: date-time
- type: 'null'
required:
- platform
- status
additionalProperties: false
Source:
type: object
properties:
platform:
type: string
country:
type: string
native_id:
anyOf:
- type: string
- type: 'null'
url:
anyOf:
- type: string
format: uri
- type: 'null'
provider:
type: string
observed_at:
type: string
format: date-time
source_updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
access_class:
type: string
enum:
- public_portal
- licensed_feed
- public_record
- modeled
retrieved_at:
type: string
format: date-time
required:
- platform
- provider
- observed_at
- access_class
additionalProperties: false
PropertyGroup:
type: object
properties:
property_id:
anyOf:
- type: string
- type: 'null'
listing_ids:
type: array
items:
type: string
match_method:
type: string
confidence:
anyOf:
- type: number
- type: 'null'
status:
type: string
enum:
- matched
- ambiguous
required:
- property_id
- listing_ids
- match_method
- status
additionalProperties: false
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.