Agree on a version once, then build freely.

api.teleon.dev is where every site and agent starts: one handshake call agrees on the API version and engine parameters, and returns a token that carries those choices on every later request.

api.teleon.devTHP v1.0httpsjson

Read the handshake guide Copy the agent prompt

A site's first call

files_siteHandshake: I speak v17, and I'd like 128-bit SimHash.POST /v1/handshake

api.teleon.devAgreed. Serving v20, translated to v17 for you. Here is your token.token issued

files_siteSearch for openapi to mcp server, with my token.translated both ways

One handshake, then every request carries the agreed version and settings.

What it does

One call to start

POST /v1/handshake names your surface, the version you want and any parameter overrides.

Versions cast both ways

Requests and responses are translated between your version and the current one.

Parameters you can tune

Search bits, sandbox tier and other settings, clamped to allowed ranges.

The contract

A handshake returns a signed token; the token selects the version and parameters for every call that follows.

CallPOST /v1/handshake

HeaderX-Teleon-Handshake-Token

VersionsDate-pinned, translated both ways

AccessRING-2 with a site key

Identifiers

X-Teleon-Surface-Id
teleon_surface_handshake_plan/v1
teleon_shared_backend_request/v1

Execution contracts

Request and responseCopy

POST /v1/handshake
{
  "client_surface_id": "files_site",
  "requested_api_version": "2026-07-15.v17",
  "engine_parameter_overrides": {"simhash_bits": 128, "sandbox_tier": "wasm_first"}
}

# Response
{
  "token": "X-Teleon-Handshake-Token: thp1.eyJ2Ijo...",
  "served_version": "2026-10-24.v20",
  "casting": "request_up, response_down",
  "clamped": {}
}

Endpoints

Method	Path	Access	What it does	Status
`POST`	`/v1/handshake`	RING-2	Agree on version and parameters	Listed
`GET`	`/v1/versions`	RING-3	List supported versions
`GET`	`/v1/parameters`	RING-3	List tunable parameters and their ranges

Listed paths appear in the service’s published files today. In the one-host plan every path here is served under api.teleon.dev/v1/api.

How it connects

Reads from

Identity and ringsteleon.dev/docs/auth

Feeds into

Searchteleon.dev/docs/search Queue brokerteleon.dev/docs/queues Content storeteleon.dev/docs/cas Schema lensesteleon.dev/docs/lenses

Queuesaq22 aq122

StoresS6 Versioned Schemas, Lineage, Scorecards and Private Vault

For agents

Give your agent the read-only guide first. It reports back before any write.

Agent prompt

Read https://api.teleon.dev/llms.txt and explain the handshake call. Read only: ask me before calling it.

Copy

llms.txt Agent card

Words on this page

Full glossary

Handshake: The first call a site or agent makes to agree on API version and settings for everything that follows.
THP: Teleon Handshake Protocol: how a site or agent negotiates API version and parameters with the backend.
Lens: A pair of functions that translate a request or response between two schema versions in both directions.
Access ring: One of four access levels. RING-0 is internal operations, RING-1 operators, RING-2 keyed agents and sites, RING-3 public reads.