API Reference

Teabar provides a gRPC API using the Connect protocol, enabling programmatic access to all platform features. The API supports both gRPC and HTTP/JSON transports.

Overview

The Teabar API is built on:

• Protocol Buffers - Strongly typed service definitions
• Connect Protocol - Modern RPC framework compatible with gRPC
• HTTP/JSON - RESTful access for simple integrations

Base URL

https://api.teabar.dev

For self-hosted installations, replace with your instance URL.

Transport Options

Services

Quick Start

Using curl (HTTP/JSON)

# List environments
curl -H "Authorization: Bearer $TEABAR_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{}' 
  https://api.teabar.dev/teabar.v1.EnvironmentService/ListEnvironments

Using Connect (TypeScript)

import { createClient } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-web";
import { EnvironmentService } from "./gen/teabar/v1/environment_connect";

const transport = createConnectTransport({
  baseUrl: "https://api.teabar.dev",
});

const client = createClient(EnvironmentService, transport);

const response = await client.listEnvironments({});
console.log(response.environments);

Using gRPC (Go)

import (
    "context"
    environmentv1 "teabar.dev/gen/teabar/v1"
    "google.golang.org/grpc"
)

conn, err := grpc.Dial("api.teabar.dev:443", grpc.WithTransportCredentials(credentials.NewTLS(nil)))
client := environmentv1.NewEnvironmentServiceClient(conn)

resp, err := client.ListEnvironments(ctx, &environmentv1.ListEnvironmentsRequest{})

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer <keycloak-access-token>

Obtain tokens via:

• Interactive login - OIDC device flow via teactl
• Service accounts - Keycloak client credentials flow for CI/CD

See Authentication for details.

Request Format

Connect/gRPC

Send protobuf-encoded messages to service methods:

POST /teabar.v1.EnvironmentService/CreateEnvironment
Content-Type: application/proto

HTTP/JSON

Send JSON with the same field names as protobuf:

POST /teabar.v1.EnvironmentService/CreateEnvironment
Content-Type: application/json

{
  "name": "my-environment",
  "blueprintId": "bp_abc123",
  "projectId": "proj_xyz"
}

Response Format

Success Response

{
  "environment": {
    "id": "env_abc123",
    "name": "my-environment",
    "status": "PROVISIONING",
    "createdAt": "2024-03-10T14:30:00Z"
  }
}

Error Response

{
  "code": "not_found",
  "message": "Environment not found",
  "details": [
    {
      "@type": "type.googleapis.com/teabar.v1.ErrorInfo",
      "reason": "ENVIRONMENT_NOT_FOUND",
      "domain": "teabar.dev"
    }
  ]
}

Proto Definitions

Download proto files for code generation:

# Clone the proto definitions
git clone https://github.com/teabar/proto.git

# Generate client code (example with buf)
buf generate proto

Or use the Buf Schema Registry:

buf export buf.build/teabar/api -o proto

Client Libraries

Official SDKs

Generated Clients

Generate clients for any language using buf generate:

# buf.gen.yaml
version: v1
plugins:
  - plugin: buf.build/connectrpc/es
    out: gen
    opt: target=ts

Idempotency

For safe retries, include an idempotency key:

Idempotency-Key: unique-request-id-123

The server will return the same response for duplicate requests with the same key (within 24 hours).

Pagination

List methods support cursor-based pagination:

{
  "pageSize": 50,
  "pageToken": "cursor_abc123"
}

Response includes next page token:

{
  "environments": [...],
  "nextPageToken": "cursor_def456"
}

Streaming

Some methods support server-side streaming for real-time updates:

// Watch environment status changes
const stream = client.watchEnvironment({ environmentId: "env_abc123" });

for await (const update of stream) {
  console.log("Status:", update.status);
}

Versioning

The API is versioned in the package name:

• teabar.v1 - Current stable version

Breaking changes require a new version. Non-breaking additions are made to the current version.

See Also

• Authentication - Authentication details
• Errors - Error handling
• Rate Limits - Usage limits
• CLI Reference - Command-line interface