# IPTO

Passage-level search over private multimodal data - audio, video, images and
documents. Search returns the matching text, so most questions are answered
without downloading anything. Default ranking mode here: keyword.

## Machine-readable

- OpenAPI 3.1: https://api.staging.ipto.ai/openapi.json
- MCP tool schemas: https://api.staging.ipto.ai/mcp/tools.json
- MCP endpoint: https://api.staging.ipto.ai/mcp

## Guides

- https://api.staging.ipto.ai/docs/search-recipes.md - worked examples, and what each call costs

## Auth

Send `x-api-key: ipto_...`, or `Authorization: Bearer ipto_...` - both work,
on REST and on MCP. A key is required: every endpoint except this page and
the schemas above answers 401 without one.

## MCP

Streamable HTTP at https://api.staging.ipto.ai/mcp. Protocol versions 2024-11-05 through
2026-07-28 are negotiated; offer yours and the server answers with what it
picked. The endpoint is stateless, so no session has to be kept alive.

## Cost

A search is metered against your plan's monthly allowance. Reading the text
it returns is not - get_asset is free, and is how you read a document end to
end without paying for bytes.

Downloads are PREPAID from a credit balance, in cents, and are charged PER
DOWNLOAD - there is no perpetual licence, so fetching the same asset twice
costs twice. Price scales with bytes and modality: a gigabyte of text costs
50x a gigabyte of video, because the text is worth more per byte. Pass a
hit's start_ms/end_ms to fetch only that moment of audio or video instead of
the whole file, and pay only for the chunk.

request_download tells you the price and your balance before you spend
anything. Too little credit is an ordinary tool error naming what it needed;
it does not close the connection, and it does not consume the download.

## Visibility

An asset is `private` (owner only), `unlisted` (retrievable by id, absent
from search) or `listed` (in the marketplace). Listed and unlisted assets may
separately have their bytes withdrawn from sale, in which case the passages
stay readable and request_download refuses. None of this is a licence: paying
for a download buys that download.

## Tools

- `search` - Search the private-data passage index.
- `get_asset` - Get an asset's metadata and its full list of passages (with timecodes/pages).
- `list_assets` - Walk the calling tenant's own catalogue, newest first.
- `request_download` - Mint a one-time, short-lived download URL for an asset's media.