Tilekit

Tilekit provides REST APIs for integrating Tiles into local clients and custom UIs. The endpoints run in the Tiles daemon under /v1/tilekit/ and cover inference server controls, the Pi agent, sessions, accounts, and ATproto.

REST API

Use the Tiles daemon’s local REST API to integrate sessions, inference, and accounts into your client. Expand an endpoint to see its request fields, curl example, and response details.

Base URL


http://127.0.0.1:1729/v1/tilekit

Run the Tiles daemon first. For chat, start the inference server, create a session, then send a prompt with the returned session ID. The endpoints below follow the current daemon source; availability depends on your installed Tiles version.

Responses

JSON success responses use {"status":"success","data":...}. Application errors use {"status":"failed","reason":"..."} with an HTTP error status. Malformed requests may be rejected before reaching a handler. The prompt endpoint returns an SSE stream.

Server

Manage the local inference server. Source.

GET/server/startStart server

Start the inference server in the background.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/server/start"

Response

Returns a status message in data.message.

GET/server/stopStop server

Stop the inference server.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/server/stop"

Response

Returns a status message in data.message.

GET/server/pingCheck server health

Check whether the inference server is responding.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/server/ping"

Response

Returns the health-check message in data.message.

Agent

Work directly with the Pi agent. Create a session before sending prompts. Source.

GET/agent/startStart agent

Start the Pi agent if it is not already running.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/agent/start"

Response

Returns data.message indicating whether the agent started or was already running.

GET/agent/stateGet agent state

Read the running agent’s current state.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/agent/state"

Response

Returns the Pi agent state in data. An agent must already be running.

POST/agent/promptSend a prompt

Send a message to the running agent. The response streams Server-Sent Events (SSE).

JSON body

Field	Type	Required	Description
`message`	string	Required	Prompt to send to the agent.
`session_id`	string	Optional	Session ID used to record the turn for sharing.

Example request


curl -N -X POST "http://127.0.0.1:1729/v1/tilekit/agent/prompt" \
  -H 'Content-Type: application/json' \
  -d '{
  "message": "Hello!",
  "session_id": "YOUR_SESSION_ID"
}'

Response

Returns text/event-stream, rather than the JSON success envelope. curl -N displays events without buffering. Omitting session_id runs the turn without recording a session snapshot.

GET/agent/end_sessionEnd session

End the current agent session gracefully.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/agent/end_session"

Response

Returns a confirmation in data.message.

GET/agent/reloadReload agent

Restart the agent using its current configuration.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/agent/reload"

Response

Returns a confirmation in data.message.

Session

Create sessions and work with locally stored chats. Source.

POST/session/newCreate session

Create a new session, starting the Pi agent if needed. Start the inference server before sending prompts.

Request body: None.

Example request


curl -X POST "http://127.0.0.1:1729/v1/tilekit/session/new"

Response

Returns the session ID in data.id. Pass this value as session_id when sending a prompt.

GET/session/listList sessions

List sessions stored in the local chat database.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/session/list"

Response

Returns the stored sessions in data.

GET/session/{session_id}/chatsGet session chats

Fetch the stored chats for a session.

Path parameter

session_id · string · required. Replace YOUR_SESSION_ID in the example with the session ID.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/session/YOUR_SESSION_ID/chats"

Response

Returns the session chat data in data.

POST/session/chatSave a chat

Save a message to the local chat database. The user ID must identify an existing local user.

JSON body

Field	Type	Required	Description
`text`	string	Required	Message content.
`session_id`	string	Required	Session to save the message in.
`role`	string	Required	One of `system`, `user`, `assistant`, `developer`, or `toolResult`.
`user_id`	string	Required	Existing local user ID.
`model_used`	string	Required	Model associated with the message.
`parent_chat_id`	string	Optional	Parent message ID.

Example request


curl -X POST "http://127.0.0.1:1729/v1/tilekit/session/chat" \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Hello!",
  "session_id": "YOUR_SESSION_ID",
  "role": "user",
  "user_id": "YOUR_USER_ID",
  "model_used": "YOUR_MODEL"
}'

Response

Returns the saved chat in data. A user message can create a stored session when that session does not yet exist.

Account

Create and inspect the local Tiles account. Source.

POST/account/createCreate account

Create a local account for onboarding.

JSON body

Field	Type	Required	Description
`nickname`	string	Required	Display nickname for the account.

Example request


curl -X POST "http://127.0.0.1:1729/v1/tilekit/account/create" \
  -H 'Content-Type: application/json' \
  -d '{
  "nickname": "alice"
}'

Response

Returns the account result in data.

GET/account/statusGet account status

Read the current local account details.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/account/status"

Response

Returns the local account in data. Returns 404 when no local account exists.

ATproto

Connect an ATproto account and publish session snapshots. Source.

POST/atproto/loginLog in

Begin ATproto login for the supplied handle.

JSON body

Field	Type	Required	Description
`user_handle`	string	Required	ATproto account handle.

Example request


curl -X POST "http://127.0.0.1:1729/v1/tilekit/atproto/login" \
  -H 'Content-Type: application/json' \
  -d '{
  "user_handle": "alice.bsky.social"
}'

Response

Returns the login result in data after the login flow completes.

POST/atproto/logoutLog out

Log out of the connected ATproto account.

Request body: None.

Example request


curl -X POST "http://127.0.0.1:1729/v1/tilekit/atproto/logout"

Response

Returns the logout result in data.

GET/atproto/statusGet login status

Read the connected ATproto account.

Request body: None.

Example request


curl -X GET "http://127.0.0.1:1729/v1/tilekit/atproto/status"

Response

Returns data.handle and data.did. Returns 404 when not logged in.

POST/atproto/share-session/{session_id}Share session

Publish a stored session to the connected account’s PDS and return a share link. This writes a record each time it is called.

Path parameter

session_id · string · required. Replace YOUR_SESSION_ID in the example with the session ID.

JSON body

Field	Type	Required	Description
`is_private`	boolean	Optional	Defaults to `false`. Use `true` to encrypt the shared session.

Example request


curl -X POST "http://127.0.0.1:1729/v1/tilekit/atproto/share-session/YOUR_SESSION_ID" \
  -H 'Content-Type: application/json' \
  -d '{
  "is_private": true
}'

Response

Returns data.url and data.is_private. Requires an ATproto login and an existing stored session.

Source and tooling

Open docs/apis in Bruno, select the Tilekit collection, and use its dev environment. It sets tilekit_base_url to the local base URL above.

The daemon route definitions are authoritative. The design overview includes planned endpoints and older names, including /server/load-model, /agent/stop, /session/resume, /session/search, and /account/set-nickname, which are not registered in the current daemon. HTTP endpoints live in the daemon.

Modelfile Reference

A Modelfile is a text-based blueprint for a model’s configuration, parameters, templates, and system prompt. Tiles supports a format inspired by Ollama-style instructions.

The separate tilekit Rust crate exports the Modelfile parser, implemented in tilekit/src/modelfile.rs using the nom parser combinator library. It parses a text-based configuration format for defining model configurations, parameters, templates, and system prompts.

This page describes what is parsed, what is validated, and what is actually used at runtime today.

Quick Start

Minimal working Modelfile:


FROM mlx-community/gpt-oss-20b-MXFP4-Q4
SYSTEM You are a concise assistant.

FROM is required. Most other fields are optional.

Supported Instructions

Tiles currently parses these top-level instructions (case-insensitive):

FROM (required, exactly one)
PARAMETER (repeatable)
TEMPLATE (at most one)
SYSTEM (latest value wins)
ADAPTER (at most one)
LICENSE (at most one)
MESSAGE (repeatable)
# comments

If FROM is missing, parsing fails.

FROM

FROM is parsed as a string, but runtime behavior is intentionally narrower right now.

What works today

Hugging Face-style model repo identifiers, for example:
- mlx-community/gpt-oss-20b-MXFP4-Q4
- mlx-community/Qwen3.5-4B-MLX-4bit

Important nuance

Any GGUF file hosted on Hugging Face is supported through FROM.
Local file paths are not supported yet.

In short: FROM supports Hugging Face model repositories, including any GGUF file hosted on Hugging Face. Local paths are not yet supported.

SYSTEM

SYSTEM sets the system/developer instruction prompt used in chat requests.

If multiple SYSTEM lines exist, the latest one replaces earlier ones.
If omitted, Tiles falls back to the default Modelfile prompt for the selected mode.

This is one of the two Modelfile fields that materially affects runtime behavior today (FROM and SYSTEM).

PARAMETER

PARAMETER is parsed and validated against an allowlist.

Supported keys:

num_ctx (int)
repeat_last_n (int)
repeat_penalty (float)
temperature (float)
seed (int)
stop (string)
num_predict (int)
top_k (int)
top_p (float)
min_p (float)

Notes:

Unknown parameter names fail validation.
Type mismatches fail validation.
Parameters are currently parsed/stored but not fully applied in the runtime request payload yet.

MESSAGE

MESSAGE supports role + content pairs.

Accepted roles:

system
user
assistant

Notes:

Messages are validated and stored.
Current runtime conversation assembly does not directly consume modelfile.messages yet.

TEMPLATE, ADAPTER, LICENSE

These instructions are parsed and validated with single-value semantics:

TEMPLATE: at most one
ADAPTER: at most one
LICENSE: at most one

Current status:

They are represented in the parsed Modelfile structure.
They are not currently wired into the main model execution path.

Comments

Lines beginning with # are accepted and preserved in serialized Modelfile output.

Current Runtime Behavior

In the current implementation, the Modelfile fields that directly influence execution are:

FROM (Hugging Face model repository identifier, including repositories containing GGUF files)
SYSTEM (prompt override/fallback behavior)

Other parsed fields are available at parse/validation level and can be considered forward-compatible surface for future runtime expansion.

Example


FROM mlx-community/gpt-oss-20b-MXFP4-Q4
SYSTEM """
You are Tiles assistant.
Keep answers practical and concise.
"""
PARAMETER temperature 0.2
PARAMETER num_ctx 4096

The example above is valid. Today, FROM and SYSTEM drive behavior directly; parameter validation still applies.

Tilekit

REST API

Server

Agent

Session

Account

ATproto

Source and tooling

Modelfile Reference

Quick Start

Supported Instructions

FROM

What works today

Important nuance

SYSTEM

PARAMETER

MESSAGE

TEMPLATE, ADAPTER, LICENSE

Comments

Current Runtime Behavior

Example

Try Tiles now.