POST /v1/search/semantic — Atom Files Developers

← API referenceFile intelligence · API access unavailable

API REFERENCE / FILE INTELLIGENCE

`POST` /v1/search/semantic

Find relevant file segments across authorized content.

Request fields

Location	Field	Type	Required	Description
Header	`Authorization`	string	Yes	Credential scoped to the authorized resource.
Header	`Content-Type`	string (media type)	Yes	application/json.
Body	`query`	string	Yes	Natural-language query.
Body	`parent_id`	string	No	Limit matches to an authorized folder.
Body	`limit`	integer	No	Maximum number of matches to return.

Request example

Example request

POST /v1/search/semantic
Authorization: Bearer <scoped token>
Content-Type: application/json

{
  "query": "signed lease agreement",
  "parent_id": "folder_123",
  "limit": 10
}

HTTP status codes

Status	Meaning
`200 OK`	Success response shown below.
`400 Bad Request`	Invalid query, scope, or limit.
`401 Unauthorized`	Missing, expired, or invalid credential.
`403 Forbidden`	Credential is valid but lacks the required scope or role.
`429 Too Many Requests`	Rate limit reached; honor Retry-After when provided.
`503 Service Unavailable`	Service temporarily unavailable; retry safely.

Response fields

Field	Type	Example
`items`	object[]	[1 shown]
`items[].file_id`	string	file_789
`items[].version_id`	string	ver_012
`items[].artifact_id`	string	art_123
`items[].source_kind`	string (extensible)	page_ocr Examples · extensible`page_ocrcaptiondocumentframeaudio_segment`
`items[].page_number`	integer	1
`items[].snippet`	string	Lease agreement signed by both parties
`items[].score`	number	0.87
`items[].model_id`	string	atom-text-v1
`indexed_through`	string (date-time)	2026-10-20T18:03:00Z
`next_cursor`	string \| null	null

Response example

Example response

200 OK
Content-Type: application/json

{
  "items": [
    {
      "file_id": "file_789",
      "version_id": "ver_012",
      "artifact_id": "art_123",
      "source_kind": "page_ocr",
      "page_number": 1,
      "snippet": "Lease agreement signed by both parties",
      "score": 0.87,
      "model_id": "atom-text-v1"
    }
  ],
  "indexed_through": "2026-10-20T18:03:00Z",
  "next_cursor": null
}

How it works

Results are version-pinned and filtered by current access grants at query time. Report index freshness; incomplete processing means an incomplete result set. Search does not disclose content from revoked or trashed files.