OpenParable
Skip to content
← Back to skills

Serverpod Endpoints

Development
serverpod-endpoints

Serverpod Endpoints is an Agent Skill for development published in the serverpod/serverpod repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Define Serverpod endpoints, use Session, pass parameters, and call from client. Use when creating RPC endpoints, working with Session, or client code generation.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/serverpod/serverpod/blob/HEAD/packages/serverpod/skills/serverpod-endpoints/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/serverpod-endpoints, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Serverpod Endpoints

Extend Endpoint with instance methods; first parameter is Session, return Future<T> (or Stream<T> for real-time data streaming). Place anywhere under server lib/. If serverpod start is not running with hot-reload, run serverpod generate to update the client.

Defining an endpoint

import 'package:serverpod/serverpod.dart';

class ExampleEndpoint extends Endpoint {
  Future<String> hello(Session session, String name) async {
    return 'Hello $name';
  }
}

Client name is derived from the class name minus Endpoint suffix (ExampleEndpoint → example).

Calling from the client

var result = await client.example.hello('World');

Client initialized once:

final serverUrl = await getServerUrl();
client = Client(serverUrl)
  // When using Flutter:
  ..connectivityMonitor = FlutterConnectivityMonitor()
  // When using authentication:
  ..authSessionManager = FlutterAuthSessionManager();

Supported parameter and return types

  • Primitives: bool, int, double, String
  • Duration, DateTime (UTC), ByteData, UuidValue, Uri, BigInt
  • Generated serializable models (from .spy.yaml)
  • List, Map, Set, Record — strictly typed with the above

Default request size limit: 512 kB. Change with maxRequestSize in config. Use the file upload API for large files.

Session

Provides: database access (session.db, Model.db), cache (session.caches), logging, request context. Do not capture for use after the request completes.

Excluding from code generation

  • Entire endpoint: @doNotGenerate on the class.
  • Single method: @doNotGenerate on the method.

Endpoint inheritance

  • Concrete extends concrete: Client gets both; subclass exposes own + inherited methods.
  • Abstract endpoint: Not registered; only concrete subclass is exposed.
  • Parent with @doNotGenerate: Parent hidden; subclass gets a client implementing inherited methods.

Overriding is allowed: same signature, different behavior, client code unchanged.

Backward compatibility

Older app versions may still call your server. Do not rename parameters (REST API passes by name). Do not delete methods, add required parameters, or change signatures; add new methods or optional named parameters instead.

When you must break an endpoint's API, create a versioned endpoint:

@Deprecated('Use TeamV2Endpoint instead')
class TeamEndpoint extends Endpoint {
  Future<TeamInfo> join(Session session) async { /* ... */ }
}

class TeamV2Endpoint extends TeamEndpoint {
  @override
  @doNotGenerate
  Future<TeamInfo> join(Session session) async => throw UnimplementedError();

  Future<NewTeamInfo> joinWithCode(Session session, String invitationCode) async {
    // New implementation
  }
}

Old clients use client.team.join(); new clients use client.teamV2.joinWithCode(...). Remove the old endpoint after all clients upgrade. Alternative: extract logic into a helper class callable from both endpoints.