OliveTin/docs/modules/ROOT/pages/api/intro.adoc

[#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/<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

* 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!