Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/StarTrail-org/PixelRAG/llms.txt

Use this file to discover all available pages before exploring further.

The tile endpoints serve the screenshot chunk images that underlie every search hit. After a /search call, each Hit object contains article_id, tile_index, chunk_index, and path fields. Use those values with one of the two tile endpoints to fetch the corresponding image for display or downstream processing. Method: GET
Path: /tile/{article_id}/{tile_index}/{chunk_index} Fetch a chunk image by its three-part coordinate. This is the preferred approach because it does not expose server filesystem paths and works correctly with both flat and sharded tile layouts.

​
Path Parameters

​
article_id
integer
required
Sequential article position index from the search hit (hit.article_id).
​
tile_index
integer
required
Which 8192 px tile within the document (hit.tile_index).
​
chunk_index
integer
required
Which 1024 px chunk within the tile (hit.chunk_index).

​
Response

Returns the raw image file with Content-Type: image/jpeg or Content-Type: image/png depending on the stored file extension. Returns HTTP 404 if no file is found at the resolved path.

​
Example

# Fetch the chunk image for the first search hit
curl -o chunk.png \
  "https://api.pixelrag.ai/tile/30492/0/2"
Using coordinates directly from a /search hit: 
ARTICLE_ID=30492
TILE_INDEX=0
CHUNK_INDEX=2

curl -o chunk.png \
  "http://localhost:30001/tile/${ARTICLE_ID}/${TILE_INDEX}/${CHUNK_INDEX}"

​
Endpoint 2: By Path (Legacy)

Method: GET
Path: /tile?path=<relative-path> Fetch a tile image using the relative path returned in hit.path from a /search response. The path is resolved relative to the server’s tiles_dir. The server rejects any path that would escape the tiles directory with HTTP 403.
​
path
string
required
Relative file path to the chunk image, as returned in hit.path from /search.

​
Example

# hit.path from a /search response
HIT_PATH="30492.png.tiles/chunk_0000_02.png"

curl -o chunk.png \
  "http://localhost:30001/tile?path=${HIT_PATH}"
The path-based endpoint returns HTTP 403 if the resolved path falls outside tiles_dir. This prevents directory traversal. Use the ID-based endpoint whenever possible.

​
Tile File Layout

Tile images are stored under the server’s tiles_dir in this structure: 
tiles/
└── {article_id}.png.tiles/
    ├── tiles.json            # render manifest
    ├── chunks.json           # chunk manifest
    ├── tile_0000.jpg         # 8192 px source tile
    ├── chunk_0000_00.png     # 1024 px chunk 0
    ├── chunk_0000_01.png     # 1024 px chunk 1
    └── ...
The hit.path field in search results is the path of the chunk file relative to tiles_dir — for example, 30492.png.tiles/chunk_0000_02.png.

​
On-Demand Rendering

When the server is started with --render-on-demand, tile images are not read from a pre-materialized tiles/ directory. Instead they are rendered on the fly from a running kiwix-serve instance and cached locally. In this mode:
  • hit.article_pages is always null (no pre-existing files to inventory)
  • Tile images are cached after first render; subsequent requests for the same tile are served from cache
  • The --kiwix-url and optionally --zim-book flags configure the kiwix source
pixelrag serve \
  --index-dir ./index \
  --render-on-demand \
  --kiwix-url http://localhost:30900 \
  --port 30001

Build docs developers (and LLMs) love

Get started for freeTalk to us