Protobuf and gRPC

The Voplica API is defined in protobuf, and the definitions are public. Generate code from them for your language, call the API with a Connect or gRPC-Web client, or read them in the reference of each package.

The definitions

The voplica/api repository on GitHub holds the definitions, with a tag for each version (today’s is v1.0.1):

Path	What it holds
proto/voplica/	The .proto files: every method of the API, and the messages and enums it uses.
buf.yaml	A buf module over proto/, with the lint and breaking-change rules the definitions follow.
openapi/voplica-api.openapi.yaml	The same API as an OpenAPI 3.1 document. The API reference is made from it.
VERSION, CHANGELOG.md	The version, and what each version changed.

Every method carries an (auth) option, defined in voplica/auth.proto. auth_type: NOT_REQUIRED means anyone may call the method, with or without a key; auth_type: ANY_USER needs a signed-in user: call it with your key. pat_allowed: true, on every method here, means an API key may call it.

The files are generated from the platform’s own definitions for each version, so a pull request to them can’t be merged. To suggest a change, start a discussion in voplica/help.

The protocols

https://api.voplica.com serves every method in three ways:

• the Connect protocol with JSON — the JSON API;
• the Connect protocol with binary protobuf (Content-Type: application/proto);
• gRPC-Web.

The native gRPC endpoint opens soon. Until then, a client built on grpc-go, grpc-java or Python’s grpcio cannot call the API: use a Connect client, a gRPC-Web client, or any HTTP client with the JSON API. The clients send their typed messages as JSON.

Try a method with buf curl

buf curl reads the definitions straight from the repository, so it needs no generated code:

buf curl --schema 'https://github.com/voplica/api.git#tag=v1.0.1' \
  --data '{}' \
  https://api.voplica.com/voplica.api.ai.model.ModelVariantService/GetRecommendedBaseModelVariant

For a method that needs your key, add -H "Authorization: Bearer $VOPLICA_API_KEY".

Caution

Your key is a secret: run these commands on your own machine or server, and never paste a key into a shared script.

Generate code for another language

buf generate reads the repository at a version tag and runs a code generator for each language you choose. For Python:

buf.gen.yaml

version: v2
inputs:
  - git_repo: https://github.com/voplica/api.git
    tag: v1.0.1
plugins:
  - remote: buf.build/protocolbuffers/python:v36.2
    out: gen
  - remote: buf.build/protocolbuffers/pyi:v36.2
    out: gen

Then run buf generate: each definition file becomes a module under gen/, for example gen/voplica/api/payment/payment_pb2.py. Pin each plugin to a version, so a later run makes the same code, and use a protobuf runtime at least as new as the generator: for the plugins above, Python’s protobuf 7.36.2 or later.

The generators for each language, and the packages already made from them:

Language	Plugins	Ready-made
Python	buf.build/protocolbuffers/python:v36.2 and buf.build/protocolbuffers/pyi:v36.2 (type stubs)	voplica-api
Java	buf.build/protocolbuffers/java:v36.2, with protobuf-java 4.36.2 or later	com.voplica:voplica-api
TypeScript	protoc-gen-es (without the package)	@voplica/connect
Go	protoc-gen-go and protoc-gen-go-grpc, set up in the repository’s clients/go/	none: generate it

Clients shows how to call the API with each of them.

The reference of each package

The sidebar’s Protobuf packages has a page for each package of the API: its services and methods, with their requests and responses; its messages and their fields; its enums and their values. Methods that answer without a key are marked anonymous allowed. The API reference shows the same methods as JSON operations.