> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.adapter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search
> Search across connected data sources. Returns ranked results with source metadata.
## OpenAPI
````yaml POST /v1/knowledge/search
openapi: 3.1.0
info:
title: Adapter API
description: Connect and sync data from any SaaS tool.
version: 0.1.0
servers:
- url: https://api.adapter.com
security:
- ApiKeyAuth: []
tags:
- name: connections
description: Manage OAuth connections to data sources.
paths:
/v1/knowledge/search:
post:
tags:
- knowledge
summary: Search
description: >-
Search across connected data sources. Returns ranked results with source
metadata.
operationId: search
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicSearchRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationErrorModel'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionDeniedErrorModel'
description: Forbidden
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: >-
Rate limit exceeded for the caller's tier. RFC 9457 problem+json
body; IETF RateLimit-* headers and Retry-After are set.
headers:
Retry-After:
description: Seconds to wait before retrying (RFC 9110).
schema:
type: integer
RateLimit-Limit:
description: Requests allowed per window.
schema:
type: integer
RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
RateLimit-Reset:
description: Delta-seconds until the window resets.
schema:
type: integer
RateLimit-Policy:
description: Active policy, e.g. '5;w=60'.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RateLimitProblemDetail'
application/json:
schema:
$ref: '#/components/schemas/RateLimitProblemDetail'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorModel'
description: Internal Server Error
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailableErrorModel'
components:
schemas:
PublicSearchRequest:
properties:
q:
type: string
maxLength: 1000
minLength: 1
title: Q
examples:
- pricing discussions with enterprise customers
limit:
type: integer
maximum: 20
minimum: 1
title: Limit
default: 10
mode:
$ref: '#/components/schemas/SearchMode'
description: Search algorithm.
default: hybrid
sources:
anyOf:
- items:
type: string
type: array
maxItems: 20
- type: 'null'
title: Sources
description: >-
Filter by source types (e.g. `["email", "calendar_event"]`). Max 20
items.
metadata:
anyOf:
- additionalProperties:
type: string
type: object
maxProperties: 20
- type: 'null'
title: Metadata
description: >-
Restrict results to evidence whose `metadata` contains ALL the given
key/value pairs (AND-of-exact-match). Set via the custom-connector
ingest `metadata` field. Max 20 keys; string values only.
examples:
- env: staging
team: growth
date_from:
anyOf:
- type: string
- type: 'null'
title: Date From
description: >-
Inclusive lower bound on evidence timestamp. Accepts RFC 3339
datetime (`2026-01-15T00:00:00Z`) or `YYYY-MM-DD` (treated as
start-of-day UTC).
examples:
- '2026-01-15'
date_to:
anyOf:
- type: string
- type: 'null'
title: Date To
description: >-
Inclusive upper bound on evidence timestamp. `YYYY-MM-DD` treated as
end-of-day UTC.
examples:
- '2026-01-31'
group_by:
$ref: '#/components/schemas/SearchGroupBy'
description: >-
Group results by `document` (deduplicates chunks) or `chunk` (raw
chunk-level results).
default: document
include_evidence:
type: boolean
title: Include Evidence
description: >-
Include the full typed evidence object for each result. Requires a
database round-trip.
default: false
additionalProperties: false
type: object
required:
- q
title: PublicSearchRequest
SearchResponse:
properties:
count:
type: integer
minimum: 0
title: Count
description: Number of results returned in this response.
results:
items:
$ref: '#/components/schemas/SearchResultItem'
type: array
title: Results
type: object
required:
- count
- results
title: SearchResponse
AuthenticationErrorModel:
properties:
error_code:
type: string
const: authentication_error
title: Error Code
default: authentication_error
message:
type: string
title: Message
default: Invalid or missing credentials.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
title: AuthenticationErrorModel
PermissionDeniedErrorModel:
properties:
error_code:
type: string
const: permission_denied
title: Error Code
default: permission_denied
message:
type: string
title: Message
default: You do not have permission to perform this action.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
title: PermissionDeniedErrorModel
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
RateLimitProblemDetail:
properties:
type:
type: string
title: Type
description: >-
Stable problem-type URI, e.g.
'{api_base_url}/errors/rate_limit_exceeded'.
title:
type: string
const: Too Many Requests
title: Title
default: Too Many Requests
status:
type: integer
const: 429
title: Status
default: 429
detail:
type: string
title: Detail
description: Human-readable explanation, including the retry hint.
error_code:
type: string
const: rate_limit_exceeded
title: Error Code
default: rate_limit_exceeded
endpoint:
type: string
title: Endpoint
description: Logical endpoint the limit applies to (e.g. 'ask', 'search').
tier:
type: string
title: Tier
description: The caller's billing tier (e.g. 'free').
limit:
type: integer
title: Limit
description: Requests allowed per window for this tier + endpoint.
remaining:
type: integer
title: Remaining
description: Requests remaining in the current window (0 when blocked).
window_seconds:
type: integer
title: Window Seconds
description: Length of the fixed rate-limit window, in seconds.
retry_after:
type: integer
title: Retry After
description: Seconds to wait before retrying (mirrors the Retry-After header).
instance:
anyOf:
- type: string
- type: 'null'
title: Instance
description: The request path that was limited.
type: object
required:
- type
- detail
- endpoint
- tier
- limit
- remaining
- window_seconds
- retry_after
title: RateLimitProblemDetail
description: >-
The 429 response body, exactly as ``RateLimitError.problem_detail``
renders it —
RFC 9457 Problem Details, served as ``application/problem+json``
alongside the IETF
``RateLimit-*`` headers and ``Retry-After``. (Distinct from the legacy
``RateLimitErrorModel`` shape, which does not match what the handler
emits.)
InternalServerErrorModel:
properties:
error_code:
type: string
const: internal_server_error
title: Error Code
default: internal_server_error
message:
type: string
title: Message
default: An unexpected error occurred.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
title: InternalServerErrorModel
ServiceUnavailableErrorModel:
properties:
error_code:
type: string
const: service_unavailable
title: Error Code
default: service_unavailable
message:
type: string
title: Message
default: >-
The service is currently experiencing issues. Please try again
later.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
title: ServiceUnavailableErrorModel
SearchMode:
type: string
enum:
- semantic
- keyword
- hybrid
title: SearchMode
description: How results are matched and ranked.
SearchGroupBy:
type: string
enum:
- document
- chunk
title: SearchGroupBy
SearchResultItem:
properties:
evidence:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Evidence
description: >-
Full typed evidence object (only present when
`include_evidence=true`).
Discriminated by `evidence_type`, with the typed payload in `data`.
evidence_type:
type: string
title: Evidence Type
id:
type: string
title: Id
description: Opaque result identifier.
score:
type: number
title: Score
description: |-
Relevance score for ranking results against each other within this
response. Combines semantic and keyword matching with additional
signals such as recency. Higher means more relevant. The scale is
relative, not absolute — use it to order results, not as a fixed
confidence threshold or to compare scores across different queries.
snippet:
type: string
title: Snippet
description: Best-matching text snippet from the document.
timestamp:
anyOf:
- type: string
- type: 'null'
title: Timestamp
urn:
anyOf:
- type: string
- type: 'null'
title: Urn
description: >-
Stable URN of the source document (`l1_`). Pass it to
`GET /users/{user_id}/refs/{urn}` to fetch the full raw record.
`None`
for documents indexed before URNs were written to the chunk store.
type: object
required:
- evidence_type
- id
- score
- snippet
title: SearchResultItem
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
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: Pass your `pk_live_...` API key as a Bearer token.
````