View as Markdown

Calling the API

Use the public API directly when you want to script requests, debug payloads, or integrate bitdrift from your own tooling. If you want a higher-level terminal workflow or user-authenticated API access, start with the bd CLI quickstart.

Prefer the bd CLI for terminal workflows

If you are primarily working from the command line, start with the bd CLI quickstart. The CLI is the protocol-independent path for authenticated public-API access: it handles user login with bd auth, and it can mint API keys with bd key create api.

Authentication

For direct API access, authenticate with an API key by sending it in the x-bitdrift-api-key header. Use bd key create api to mint an API key, or refer to AdminService for the underlying API surface.

For user-authenticated access, use the bd CLI authentication flow. We do not currently support JWT-authenticated requests against the public API directly.

Supported transports

The same API methods are available through multiple transport layers.

Transport	Notes
gRPC over JSON	See the command examples below for direct HTTP requests against this surface.
Connect or gRPC clients	See bitdriftlabs/api for the public schema definitions under src/bitdrift/public.

Call the API from the command line

For quick exploration, you can call the same ListWorkflows method a few different ways:

curlgrpcurlbuf curl (Connect)buf curl (gRPC)

Bash

curl -X POST https://api-public.bitdrift.io/bitdrift.public.unary.workflows.v1.WorkflowService/ListWorkflows \
  -H "x-bitdrift-api-key: <key>" \
  -H "Content-Type: application/json" \
  -d '{}'

This is the gRPC-over-JSON surface used by the generated service-page examples.

Bash

grpcurl \
  -H "x-bitdrift-api-key: <key>" \
  api-public.bitdrift.io:443 \
  bitdrift.public.unary.workflows.v1.WorkflowService.ListWorkflows

Use grpcurl when you want to hit the native gRPC endpoint directly.

Bash

buf curl \
  --reflect-header "*" \
  -H "x-bitdrift-api-key: <key>" \
  https://api-public.bitdrift.io/bitdrift.public.unary.workflows.v1.WorkflowService/ListWorkflows

buf curl uses the Connect protocol by default. The CLI accepts JSON input and encodes the request as protobuf on the wire.

Bash

buf curl \
  --reflect-header "*" \
  --protocol grpc \
  -H "x-bitdrift-api-key: <key>" \
  https://api-public.bitdrift.io/bitdrift.public.unary.workflows.v1.WorkflowService/ListWorkflows

Use this when you want buf curl to target the native gRPC transport instead of Connect.

Generated clients

If you are integrating from application code, use the public schema definitions in bitdriftlabs/api. The queryable API definitions documented here live under src/bitdrift/public, and you can use that schema to generate the Connect or gRPC clients that fit your environment.

Find the right method first

The generated reference remains the source of truth for request and response shapes:

• Services for callable methods and example payloads.
• Types for message and enum definitions.

If you mostly want a supported terminal workflow rather than hand-authoring requests, use the bd CLI docs.