---
title: Calling the API
---

# 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](../cli/quickstart.md).

## Prefer the `bd` CLI for terminal workflows

If you are primarily working from the command line, start with the [`bd` CLI quickstart](../cli/quickstart.md).
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](../api/bitdrift_public_unary_admin_v1_AdminService.md#CreateKey) for the underlying
API surface.

For user-authenticated access, use the [`bd` CLI authentication flow](../cli/quickstart.md#authentication).
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`](https://github.com/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:

=== "`curl`"

    ```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.

=== "`grpcurl`"

    ```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.

=== "`buf curl` (Connect)"

    ```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.

=== "`buf curl` (gRPC)"

    ```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`](https://github.com/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](../api/services.md) for callable methods and example payloads.
- [Types](../api/reference.md) for message and enum definitions.

If you mostly want a supported terminal workflow rather than hand-authoring requests, use the
[`bd` CLI docs](../cli/quickstart.md).