GET /v1/files/{file_id}/embeddings — Atom Files Developers

← API referenceFile intelligence · API access unavailable

API REFERENCE / FILE INTELLIGENCE

`GET` /v1/files/{file_id}/embeddings

Read version-pinned vector representations for authorized file segments.

Request fields

Location	Field	Type	Required	Description
Header	`Authorization`	string	Yes	Credential scoped to the authorized resource.
Path	`file_id`	string	Yes	Stable Atom file ID.
Query	`version_id`	string	Recommended	Pin vectors to an immutable content version.
Query	`model_id`	string	No	Select a compatible embedding model.
Query	`cursor`	string	No	Opaque pagination cursor.

Request example

Example request

GET /v1/files/file_789/embeddings?version_id=ver_012
Authorization: Bearer <embedding-scoped token>

HTTP status codes

Status	Meaning
`200 OK`	Success response shown below.
`400 Bad Request`	Invalid version, model, or cursor.
`401 Unauthorized`	Missing, expired, or invalid credential.
`403 Forbidden`	Credential is valid but lacks the required scope or role.
`404 Not Found`	File or version is not visible to this caller.
`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
`file_id`	string	file_789
`version_id`	string	ver_012
`items`	object[]	[1 shown]
`items[].id`	string	emb_123
`items[].artifact_id`	string	art_123
`items[].source_kind`	string (extensible)	page_ocr Examples · extensible`page_ocrcaptiondocumentframeaudio_segment`
`items[].page_number`	integer	1
`items[].model_id`	string	example-only-vector-4
`items[].dimensions`	integer	4
`items[].values`	number[]	[4 shown]
`items[].created_at`	string (date-time)	2026-10-20T18:02:10Z
`next_cursor`	string \| null	null

Response example

Example response

200 OK
Content-Type: application/json

{
  "file_id": "file_789",
  "version_id": "ver_012",
  "items": [
    {
      "id": "emb_123",
      "artifact_id": "art_123",
      "source_kind": "page_ocr",
      "page_number": 1,
      "model_id": "example-only-vector-4",
      "dimensions": 4,
      "values": [
        0.12,
        -0.04,
        0.31,
        0.07
      ],
      "created_at": "2026-10-20T18:02:10Z"
    }
  ],
  "next_cursor": null
}

How it works

Raw vectors need an additional embeddings.read grant; normal file-read permission is insufficient. Results identify model, dimensions, source artifact, and page or time segment. The four-dimensional vector shown is illustrative, not a production model.