[#api] = API Overview This section of the documentation is intended for developers, and those who want to hack around with OliveTin and extend it. This page provides a few pointers to get started. **Short version**: * http://olivetinServer:1337/api on your OliveTin server to get the REST API. * link:https://docs.olivetin.app/api/swagger/3k/[Swagger] documents the API. **Longer version**: The OliveTin API is formally defined using the Protobuf IDL, in link:https://github.com/OliveTin/OliveTin/tree/main/proto[the `proto/` directory of the OliveTin repository]. Server and client code is generated from that definition, and the API is served using link:https://connectrpc.com[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] == 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**: link:https://github.com/OliveTin/OliveTin/tree/main/proto[`proto/`] on GitHub - the service is `olivetin.api.v1.OliveTinApiService` in link:https://github.com/OliveTin/OliveTin/blob/main/proto/olivetin/api/v1/olivetin.proto[`olivetin/api/v1/olivetin.proto`]. * **Generate a client**: use link:https://buf.build[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/` at the root go to the web UI instead. * **Call it directly**: each unary RPC is available as `POST /api/` 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 * link:http://docs.olivetin.app/api/swagger/[OliveTin 2k API: Swagger UI] * link:http://docs.olivetin.app/api/swagger/OliveTin.openapi.json[OliveTin 2k API: OpenAPI JSON Definition] * link:http://docs.olivetin.app/api/swagger/3k/[OliveTin 3k API: Swagger UI] * link:http://docs.olivetin.app/api/swagger/3k/OliveTin.openapi.json[OliveTin 3k API: OpenAPI JSON Definition] * link:https://github.com/OliveTin/OliveTin/tree/main/proto[The OliveTin Protobuf definitions (source)] * link:https://github.com/OliveTin/OliveTin/blob/main/proto/olivetin/api/v1/olivetin.proto[The OliveTin Protobuf file] 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!