API contracts

Every Agyn service exposes its API via Protobuf. The schemas live in a single repository — agynio/api — and are the source of truth for both internal gRPC services and the external Gateway via ConnectRPC.

This page is a pointer rather than a full API reference. The repository's schemas are versioned and machine-generatable; we don't duplicate them here.

Repository layout

agynio/api/
├── proto/agynio/api/
│   ├── agents/v1/
│   ├── chat/v1/
│   ├── files/v1/
│   ├── identity/v1/
│   ├── llm/v1/
│   ├── notifications/v1/
│   ├── organizations/v1/
│   ├── runners/v1/
│   ├── secrets/v1/
│   ├── threads/v1/
│   ├── tracing/v1/
│   ├── users/v1/
│   └── ...
├── buf.yaml
└── buf.gen.yaml

Each package's *.proto file defines:

  • The internal service (used by other platform services over gRPC).
  • The external <Service>Gateway (exposed through the Gateway via ConnectRPC).
  • All request/response messages and enums.

Generate clients

With buf installed:

sh
buf generate https://github.com/agynio/api.git

buf.gen.yaml controls which languages get generated. Out of the box it includes Go and TypeScript; add more generators as needed.

For a one-off check of method signatures:

sh
buf lint https://github.com/agynio/api.git
buf curl https://gateway.agyn.example.com/agynio.api.users.v1.UsersGateway/GetMe \
  --protocol connect --schema https://github.com/agynio/api.git

Gateway services

The external API surface — every method below is callable via the Gateway:

ServiceMethods (selection)
UsersGatewayGetMe, GetUser, SearchUsers, CreateAPIToken, ListAPITokens, RevokeAPIToken, CreateDevice, ListDevices, DeleteDevice
OrganizationsGatewayCreateOrganization, GetOrganization, ListOrganizations, UpdateOrganization, DeleteOrganization, CreateMembership, AcceptMembership, DeclineMembership, RemoveMembership, UpdateMembershipRole, ListMembers, ListMyMemberships
AgentsGatewayCreateAgent, GetAgent, ListAgents, UpdateAgent, DeleteAgent, plus CRUD for MCPs, Skills, Hooks, ENVs, InitScripts, Volume Attachments, Image Pull Secret Attachments. Also: SetAgentRole, RemoveAgentRole, ListAgentRoles, ListMyAgentRoles
RunnersGatewayRegisterRunner, GetRunner, ListRunners, UpdateRunner, DeleteRunner, EnrollRunner, ListWorkloads, GetWorkload, ListWorkloadsByThread, TouchWorkload, StreamWorkloadLogs, GetVolume, ListVolumes, ListVolumesByThread
LLMGatewayCreateProvider, GetProvider, ListProviders, UpdateProvider, DeleteProvider, CreateModel, GetModel, ListModels, UpdateModel, DeleteModel, TestModel
SecretsGatewayCreateSecretProvider, GetSecretProvider, ListSecretProviders, UpdateSecretProvider, DeleteSecretProvider, CreateSecret, GetSecret, ListSecrets, UpdateSecret, DeleteSecret, CreateImagePullSecret, GetImagePullSecret, ListImagePullSecrets, UpdateImagePullSecret, DeleteImagePullSecret
ChatGatewayListConversations, GetConversation, CreateConversation, UpdateConversation, MarkRead, GetUnackedMessageCounts
ThreadsGatewayCreateThread, GetThread, ListThreads, SendMessage, AckMessages, GetUnackedMessages, GetMessages, AddParticipant, DegradeThread
FilesGatewayUploadFile, GetFileMetadata, GetDownloadUrl, GetFileContent
NotificationsGatewaySubscribe (server-streaming)
TracingGatewayListSpans, GetSpan, GetTrace, StreamRunEvents (server-streaming)
AppsGatewayCreateApp, GetApp, GetAppBySlug, ListApps, UpdateApp, DeleteApp, InstallApp, GetInstallation, ListInstallations, UpdateInstallation, UninstallApp

For the full method list and request/response shapes, see each service's .proto file in the repository.

Streaming methods

Server-streaming methods over ConnectRPC:

  • NotificationsGateway/Subscribe — real-time events.
  • RunnersGateway/StreamWorkloadLogs — container logs.
  • TracingGateway/StreamRunEvents — run events as they happen.
  • FilesGateway/GetFileContent — file bytes.

Most clients consume these via ConnectRPC's stream API. gRPC and gRPC-Web both work.

Authentication for API calls

See Build & extend → Gateway API for how to authenticate (OIDC, API tokens, OpenZiti mTLS).

Versioning

  • All API packages are v1. Breaking changes will go through a v2 package with both versions served for a deprecation window.
  • Field additions are non-breaking and roll out without a version bump.
  • Default field values are explicit on every message — clients should always send the fields they care about.

Internal services

Not every service in agynio/api is exposed through the Gateway. Internal services (e.g. Runners.CreateWorkload, Agents.ResolveAgentIdentity) are restricted to specific platform callers via Istio AuthorizationPolicy. See each service's spec for the internal vs. external split.