Search Graph Documents

post/v1/graphs/{graph_id}/search

Part of Search.

Shared repositories require a subscription; subscription plan determines search rate limits.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Request body

Required, application/json.

Field	Type	Description
`query`required	string	Search query Constraints: 1–500 characters
`entity`optional	string	Filter by CIK (exactly one filer), ticker, or entity name. A name, or a ticker that is also a word, is a loose word match that can include other filers
`form_type`optional	string	Filter by SEC form type (10-K, 10-Q)
`section`optional	string	Filter by section ID: an Item (item_1, item_1a, item_7, ...) or, for iXBRL disclosures, the element qname (us-gaap:GoodwillDisclosureTextBlock)
`element`optional	string	Filter by XBRL element qname (e.g., us-gaap:Goodwill)
`source_type`optional	string	Filter by source type (xbrl_textblock, narrative_section, ixbrl_disclosure, uploaded_doc, connection_doc)
`fiscal_year`optional	integer	Filter by fiscal year
`date_from`optional	string	Filter filings on or after date (YYYY-MM-DD) Constraints: matches `^\d{4}-\d{2}-\d{2}$`
`date_to`optional	string	Filter filings on or before date (YYYY-MM-DD) Constraints: matches `^\d{4}-\d{2}-\d{2}$`
`semantic`optional	boolean	Enable hybrid semantic search (BM25 + KNN). Default is BM25-only for speed. Default: `false`
`group`optional	boolean	Fold hits from successive filings of the same filer and section into the best-ranked one; also_in_filings counts the others. Ignored when entity is set, where a filer's filing history is the point. A grouped page is drawn from the first 100 hits. Default: `false`
`size`optional	integer	Max results to return Default: `10` Constraints: 1–50
`offset`optional	integer	Pagination offset Default: `0` Constraints: at least 0
`snippet_chars`optional	integer	Approximate snippet budget per hit in characters; the default is three highlight fragments of about 200 Constraints: 80–1500

Example request

curl

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/search" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "string"
}'

Responses

200 Successful Response

Field Type Description

totalrequired

integer

Matching documents before any grouping, as OpenSearch counts them (it stops counting at 10,000). Not the number of distinct results a grouped search can page through.

hitsrequired

SearchHit[]

A single search result with snippet. A long SEC section (an MD&A, a commitments note) is indexed in parts, each a document of its own: part of part_count, parent_document_id shared by the section's parts, next_document_id to read on. On a grouped search, also_in_filings counts the other filings of the same filer whose same section (and part) matched and were folded into this hit.

SearchHit fields

Field	Type	Description
`document_id`required	string
`score`required	number
`source_type`required	string
`parent_document_id`optional	string
`part`optional	integer	Default: `1`
`part_count`optional	integer	Default: `1`
`next_document_id`optional	string
`entity_ticker`optional	string
`entity_name`optional	string
`section_label`optional	string
`section_id`optional	string
`element_qname`optional	string
`filing_date`optional	string
`fiscal_year`optional	integer
`form_type`optional	string
`accession_number`optional	string
`xbrl_elements`optional	string[]
`snippet`required	string
`content_length`optional	integer	Default: `0`
`content_url`optional	string
`document_title`optional	string
`tags`optional	string[]
`folder`optional	string
`also_in_filings`optional	integer

queryrequired string

graph_idrequired string

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
422	Validation Error
429	Rate limit exceeded
500	Internal server error
503	Text search not available