API Overview

Short version:

Longer version: The OliveTin API is formally defined using the Protobuf IDL, in the proto/ directory of the OliveTin repository. Server and client code is generated from that definition, and the API is served using Connect RPC.

The API is exposed at /api/ on the single HTTP frontend (port 1337 by default), and is the same API used by the WebUI. You can call it with plain JSON over HTTP (eg: curl http://olivetinServer:1337/api/WhoAmI --json '{}'), with binary Protobuf, or with gRPC-Web clients.

Machine readable API (for scripts, integrations and AI agents)

The OliveTin API is completely machine readable - every method, request and response message, field, and enum is defined in the Protobuf files. This makes it straightforward for code generators, API tooling, and LLMs / AI agents to discover and use the API without guessing.

  • Source of truth: proto/ on GitHub - the service is olivetin.api.v1.OliveTinApiService in olivetin/api/v1/olivetin.proto.

  • Generate a client: use buf or protoc with the Connect, gRPC, or gRPC-Web plugins for your language of choice (Go, TypeScript, Python, Java, etc). Set the client’s base URL to http://olivetinServer:1337/api (not the server root) - the API is only served under /api/, and requests to /olivetin.api.v1.OliveTinApiService/<MethodName> at the root go to the web UI instead.

  • Call it directly: each unary RPC is available as POST /api/<MethodName> with a JSON body matching the request message, using protobuf JSON field names (lowerCamelCase, eg: bindingId). Server-streaming RPCs (EventStream) use the Connect streaming protocol (enveloped application/connect+json messages), so they cannot be called with a plain JSON request - use a generated Connect client for those.

  • HTTP method: every unary RPC is called with POST - a GET request returns 405 Method Not Allowed.

  • OpenAPI: the Swagger / OpenAPI links below are generated from the Protobuf files, and are also available for tools that prefer OpenAPI.

Links

Please do talk to the developers on Discord if you’d like help using the API, or you’re thinking about building something interesting using the API!