Interfaces & API

indx exposes one set of strict Pydantic contracts through three interfaces: the in-process Python facade, the CLI, and a synchronous HTTP API.

Operations

Operation	Purpose
capabilities / GET /v1/capabilities	Return the current capability and embedding-space snapshot.
plan / POST /v1/plan	Inspect a deterministic processing decision without executing it.
encode / POST /v1/encode	Execute a supplied or newly created plan into blocks and embeddings.
embed / POST /v1/embed	Encode a text or image query into a named embedding space.

Python

from indx import EncodeRequest, Indx, RequestId, UriSource

result = Indx().encode(
    EncodeRequest(
        request_id=RequestId("encode-1"),
        source=UriSource(uri="file:///absolute/path/report.pdf"),
        embedding_space_ids=("default-text",),
    )
)

for block in result.blocks:
    print(block.kind, block.status, block.text)

The top-level indx package also exports module-level capabilities(), plan(), encode(), and embed() functions backed by a lazily created default service.

CLI

uv run indx capabilities
uv run indx plan file:///absolute/path/report.pdf
uv run indx encode file:///absolute/path/report.pdf
uv run indx embed --space default-text "annual recurring revenue"
uv run indx serve --host 127.0.0.1 --port 8000

The CLI emits the same contract as formatted JSON. It is intentionally small. Use Python or HTTP when you need the full request surface, including constraints and document embedding spaces.

HTTP

JSON requests accept URI or base64-inline sources. Planning, encoding, and image embedding also accept multipart uploads with a JSON request part and binary file part.

curl -s http://127.0.0.1:8000/v1/capabilities

Every response carries an X-Request-ID correlation header. Failures use one typed envelope:

{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "Input should be a valid string",
    "param": "source.uri.uri",
    "request_id": "request-from-your-body"
  }
}

Run just demo::server and open local Swagger for the interactive contract.

Reference

• API contract
• Committed OpenAPI document
• Python facade