Mobile API reference (v1)

Pinter provides a dedicated, versioned REST and SSE streaming API designed specifically for mobile clients (React Native, Flutter, iOS, and Android) under /api/mobile/v1.

Key principles

Independent contract: Mobile endpoints are isolated from desktop web refactors to avoid breaking mobile releases.
Optimized payloads: Strips large internal trace spans and server logs, transmitting only essential message and activity chunks.
Guaranteed terminal SSE event: Streams always conclude with exactly one end event carrying final status and token usage statistics.
Connection resilience: Supports turn reconnection via the standard Last-Event-ID header and non-streaming fallback (stream: false).
No API-Version header required: The version is baked into the path (/v1).

Authentication endpoints

Method	Endpoint	Description
`POST`	`/api/mobile/v1/auth/login`	Authenticate using username and password with optional `X-Device-ID`. Returns tokens or MFA challenge.
`POST`	`/api/mobile/v1/auth/mfa/send`	Request an OTP challenge code via chosen method (email/WhatsApp).
`POST`	`/api/mobile/v1/auth/mfa/verify`	Verify OTP code and issue JWT tokens on success.
`POST`	`/api/mobile/v1/auth/refresh`	Rotate refresh token and obtain a fresh 60-minute access token.
`GET`	`/api/mobile/v1/auth/me`	Bootstrap profile, effective role level, permissions, and quick budget status.

Chat and streaming endpoints

Method	Endpoint	Description
`GET`	`/api/mobile/v1/agents`	List active, usable agents for chat selection.
`GET`	`/api/mobile/v1/conversations`	List conversations with single-query latest message previews.
`POST`	`/api/mobile/v1/conversations`	Create a new conversation room.
`PATCH`	`/api/mobile/v1/conversations/{id}`	Rename or archive a conversation.
`DELETE`	`/api/mobile/v1/conversations/{id}`	Soft-delete a conversation (HTTP 204).
`GET`	`/api/mobile/v1/conversations/{id}/messages`	Cursor-based message history using `before={message_id}`.
`POST`	`/api/mobile/v1/conversations/{id}/messages`	Send message with pre-turn quota check (returns 402 if exhausted) and SSE stream or JSON.
`GET`	`/api/mobile/v1/conversations/{id}/stream`	Reconnect to active turn stream using `Last-Event-ID`.
`POST`	`/api/mobile/v1/conversations/{id}/stop`	Cancel in-flight agent turn execution.
`POST`	`/api/mobile/v1/conversations/{id}/approvals`	Resolve human-in-the-loop tool execution confirmations.
`POST`	`/api/mobile/v1/attachments`	Upload multipart attachments before sending messages.
`GET`	`/api/mobile/v1/attachments/{blob_path}`	Authenticated proxy download for private GCS attachments.

Budget and quota endpoints

Method	Endpoint	Description
`GET`	`/api/mobile/v1/budget/summary`	Consolidated budget gauge status (`ok`, `near_limit`, `exhausted`, `no_quota`, `unlimited`).
`GET`	`/api/mobile/v1/budget/requests`	List user’s budget top-up requests with normalized lowercase status.
`POST`	`/api/mobile/v1/budget/requests`	Submit a new budget increase request (`requested_amount > 0`).
`GET`	`/api/mobile/v1/budget/trends`	Time-series chart points with configurable `tz` (default `Asia/Jakarta`).

SSE event taxonomy

Mobile stream consumers receive standard SSE events formatted as:

id: <int>
event: <name>
data: <json>

Event	Data payload	Purpose
`text`	`{"delta": "string"}`	Progressive assistant prose tokens.
`thinking`	`{"delta": "string"}`	Model chain-of-thought / reasoning output.
`tool`	`{"id": "...", "name": "...", "state": "running" \| "done"}`	Tool execution indicator.
`approval_required`	`{"approval_id": "...", "name": "...", "args": {...}}`	Human-in-the-loop confirmation card.
`artifact`	`{"kind": "html" \| "flint_chart", "content": ...}`	Renderable rich visualization components.
`error`	`{"code": "...", "message": "..."}`	Execution failures.
`end`	`{"status": "completed" \| "awaiting_approval" \| "failed" \| "stopped" \| "idle", "usage": {...}}`	Terminal signal guaranteed once per stream.

Standard error codes

Status	Code	Meaning
401	`AUTH_INVALID_CREDENTIALS`	Incorrect username or password.
401	`AUTH_TOKEN_EXPIRED`	Access token expired; call `/auth/refresh`.
401	`AUTH_SESSION_EXPIRED`	7-day session window exceeded or account disabled; re-login required.
401	`MFA_SESSION_EXPIRED`	MFA challenge token expired; re-authenticate required.
402	`QUOTA_EXCEEDED`	Token budget exhausted; prompt user to submit top-up request.
403	`FORBIDDEN`	Missing permission or outside role group jurisdiction.
404	`NOT_FOUND`	Resource does not exist.
422	`INVALID_CURSOR`	Cursor message id not found in the conversation.
422	`VALIDATION_ERROR`	Schema validation error (e.g. invalid amount).
429	`RATE_LIMITED`	Sliding window rate limit exceeded.

Get started

Architecture

Core workflows

Administration

Reference

Mobile API reference (v1)

Key principles

Authentication endpoints

Chat and streaming endpoints

Budget and quota endpoints

SSE event taxonomy

Standard error codes

​Key principles

​Authentication endpoints

​Chat and streaming endpoints

​Budget and quota endpoints

​SSE event taxonomy

​Standard error codes

Key principles

Authentication endpoints

Chat and streaming endpoints

Budget and quota endpoints

SSE event taxonomy

Standard error codes