docs
/
Client Integration

Flutter requests

Reads and writes over any datatype, the escape hatch for everything else, and what the errors mean.

Datatypes, not tables

AppEngine does not hand out a fixed set of tables. Every record has a datatype — sf_product, reservation, customer, or one you define — and the same handful of calls can address permitted datatypes. Sensitive account operations have dedicated APIs. That is the part worth understanding first: you are not limited to the datatypes the platform ships with.

Records come back as plain maps with the fields under data. The client does not impose models, because your app knows its own shapes better than a generic client can.

Reading

final page = await appmint.repository.find(
  'sf_order',
  filter: {'data.status': 'open'},
  pageSize: 20,
  sort: {'createdate': -1},
);

page.items;    // List<Map<String, dynamic>>
page.total;
page.hasMore;
page.page;     // 1-based; next request uses page: page.page + 1
page.pageSize;

find defaults to page 1 and page size 50. The request body is {query: filter, options: {page, pageSize, sort, sortType}}. Only the first entry in sort is sent; multiple map entries do not produce a compound sort. Numeric directions pass through; strings starting with asc become 1, other strings become -1.

The parser accepts a list or a data/items list inside a map. total falls back to the returned item count if absent, so hasMore cannot prove that an unreported next page does not exist. It computes page * pageSize < total.

filter is passed through as-is, so it takes the query shape the server understands, including operators:

filter: {'data.total': {r'$gt': 100}}

One record by id:

final order = await appmint.repository.findById('sf_order', id);
final fields = order?['data']; // Map when the response is a record envelope
`findByAttribute` matches loosely

It can return records that merely resemble the value you passed. Read what comes back and confirm each record is the one you meant before acting on it — and never pipe its results straight into delete. That mistake has destroyed live records.

The wrapper returns null for a successful non-map findById response; HTTP 404 still throws. It does not URL-encode datatype, ID, attribute, or attribute value segments. Use known URL-safe identifiers or encode individual segments with Uri.encodeComponent before passing them to helpers.

Generic repository access remains subject to backend datatype and ownership rules. Use /client-data/* for customer self-service and domain APIs for business actions; the existence of a helper does not grant access or trigger all of a domain service’s side effects.

Writing

final created = await appmint.repository.create('my_datatype', {'title': 'Hello'});

await appmint.repository.update('my_datatype', id, {'title': 'Replaced'});

await appmint.repository.updateFields('my_datatype', id, {
  'data.title': 'Renamed',
  'data.settings.theme': 'dark',
});

await appmint.repository.delete('my_datatype', id);

create sends {datatype, isNew: true, data}. A nonempty map is returned as received. An empty successful response throws AppmintException with reason: 'duplicate_create' and statusCode: 200; do not render it as a saved record. update wraps the supplied fields in {data: ...}, while updateFields sends your map at the root. Both return an empty map for a successful non-map response, so read back important changes by ID.

Two details matter for writes:

updateFields takes dot paths, not a nested map. Passing {'data': {'settings': {'theme': 'dark'}}} replaces that whole branch and drops its other keys, quietly.

Create is a PUT on the server, not a POST. The client handles that; you only meet it if you call the endpoint yourself and get a 404.

Everything else

The package wraps the calls every app needs. Anything else is one line away, with headers and tokens still handled:

final profile = await appmint.http.get('/client-data/profile');
await appmint.http.put('/client-data/profile', body: {'firstName': 'Alex'});
final tickets = await appmint.http.get('/events/$eventId/tickets');

Pass sendUserToken: false for a call that should go out with app authentication alone. HTTP results are dynamic: JSON maps/lists remain their actual shape, an empty body becomes null, and a non-JSON success body stays a string. Validate a route’s response instead of casting every success to a map.

get accepts Map<String, String> query values. For a POST with query parameters, use send:

final result = await appmint.http.send(
  'POST',
  '/crm/inbox/update',
  query: {'send': 'true'},
  body: messageRecord, // A valid message record for the CRM inbox contract.
);

Do not append ?send=true to path: send rebuilds the URI query and removes an inline query when no separate query map is supplied. The current CRM sample contains this inline-query pattern; adapt it using send before relying on SMS sending. Empty query values, literal null, and NaN are omitted. Browser GETs also receive a _ts parameter to avoid stale browser cache results.

Multipart uploads

upload(path, bytes:, fileName:, fields:, field: 'file') POSTs one multipart file and returns a map or {}. The target must explicitly support that form field and any required metadata. A route-specific upload example is the chat package’s sendAttachments, documented below.

Unlike normal requests, this helper does not retry, refresh on 401, emit onCall, or wrap transport failures in AppmintNetworkException. It always attaches the current user token if present. The send timeout is twice the configured timeout; it is not a guarantee for fully consuming the streamed response. Handle transport exceptions separately and reconcile uploads before retrying.

Chat and attachments

appmint_flutter_chat is a separate package in the same repository. It does not depend on the Flutter client; the host supplies a customer JWT callback:

import 'package:appmint_flutter_chat/appmint_flutter_chat.dart';

final chatConfig = AppmintChatConfig(
  endpoint: appmint.config.baseUrl,
  orgId: appmint.config.orgId,
  user: AppmintChatUser(email: user.email, name: user.displayName),
  token: () async => appmint.http.userToken,
  onTokenExpired: () async {
    final token = await appmint.auth.refreshSession();
    if (token == null) await appmint.auth.signOut();
  },
);
// In a Flutter route:
// AppmintSupportChatScreen(config: chatConfig)

The screen creates, starts, and disposes its controller. With your own layout, retain one AppmintChatController, await start(), render AppmintChatView, and dispose the controller when leaving the account or organization. Render connection, error, and canSend; a connected socket is not yet authenticated. Do not pass the app token to chat.

The service connects to the /chat Socket.IO namespace with WebSocket transport. The server emits authenticate; the client does not emit an authentication message. Threads use customer::<lowercase-email>. Optional configId and appId select the site’s chat setup; AppmintSiteChat.fromSite(site) reads these from the site record. Optional loadSessionId/saveSessionId callbacks resume the server-issued chat session; partition their storage by endpoint, org, customer and chat config.

controller.sendAttachments accepts AppmintChatAttachment objects holding List<int> bytes, name, and mimeType. Supply a picker through the screen’s onPickAttachments; the package does not request camera/library permissions. Chat upload uses multipart files on /chat/upload/:scope/:email, where scope is configId or chatId, with the customer token in Authorization. This is a different authentication contract from normal Appmint HTTP requests. Uploaded path is durable; signed url may expire. Current service comments report that history strips attachments; do not promise their persistence in the history UI without checking your server.

Initial authenticate rejection with token_expired triggers one refresh and restart in the controller. A later token_expired event calls the callback and sets failure state but does not itself reconnect; expose controller.retry() after successful renewal. Outgoing messages can become failed, and there is no durable offline queue. See the chat example.

Watching what it does

appmint.http.onCall = (call) {
  print('${call.method} ${call.path} → ${call.status} '
        '(${call.took.inMilliseconds}ms) '
        'app:${call.appAuthenticated} user:${call.sentUserToken}');
};

AppmintCall carries no token values — only whether each was attached, which is the genuinely confusing part of this API. The authentication example puts this on screen beside the app.

onCall reports completed response paths, including app authentication. It is not a complete wire trace: transport failures, uploads, and the initial 401 before renewal are not each emitted as separate events. Do not let an observer throw. logRequests: true logs request information and error-body excerpts; redact those before sharing.

Errors

Failures arrive as AppmintException, and message is safe to show — AppEngine writes its refusals in plain language and the client passes them through rather than replacing them.

TypeMeans
AppmintExceptionThe server answered and refused. statusCode, and reason where it gives one — invalid_code and challenge_expired need different cures
AppmintAppAuthExceptionThe app itself could not sign in. reason carries AppEngine's code (attestation_off, debug_token_invalid, cert_mismatch, secret_refused, …) or proof_unavailable / proof_failed from the device; see Phone apps without a secret. No request can succeed until it is fixed
AppmintSessionExpiredExceptionThe session is gone and could not be renewed. Send them back to sign-in
AppmintNetworkExceptionNo usable HTTP response was received; timeout/reset can leave a write’s outcome unknown

Normal calls retry recognized transport errors up to transientRetries total attempts, with 400 * attempt milliseconds between attempts (400, 800, 1200 ms for the default four attempts). This applies to writes too. A 5xx is not transport-retried; a 401 has the separate renewal path. For a non-idempotent operation, use a client configured with transientRetries: 1 and reconcile a lost response by reading the saved record or domain status. This setting does not disable the separate 401 retry.

That last distinction matters: a 400 is an answer, and calling it a network error sends people to check their wifi instead of their password.

Current AppEngine account-write restrictions

The13 October 2026 backend source rejects generic partial updates for user, customer, apikey, user_security and two_factor_backup. Generic user/customer deletion is also refused. Use the dedicated profile, staff-management or security API with its required permissions. A repository helper does not bypass those restrictions or reproduce notifications, audit and session cleanup performed by domain operations.