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

## Error handling on the gRPC-over-JSON surface

When you call the JSON endpoint directly, application errors follow the same canonical gRPC status
model used by the native gRPC transport, but the JSON bridge maps that automatically into a normal
HTTP error response.

On this surface, clients should look at:

- The HTTP status code.
- The JSON response body, which uses the Connect-style error shape with `code` and `message`.

Common cases look like this:

| HTTP status | Connect-style `code` | Typical meaning |
| --- | --- | --- |
| `400` | `invalid_argument` | The request was syntactically valid JSON, but a field value was invalid for the API. |
| `404` | `not_found` | The requested resource does not exist. |
| `401` | `unauthenticated` | Authentication was missing or invalid. |

### Example error response

If you request hydration status for a session ID that does not exist, expect a not-found error.

```bash
curl -i -X POST https://api-public.bitdrift.io/bitdrift.public.unary.timeline.v1.TimelineService/GetHydrationStatus \
  -H "x-bitdrift-api-key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "00000000-0000-0000-0000-000000000000"
  }'
```

Example response shape:

```http
HTTP/1.1 404 Not Found
content-type: application/json
```

```json
{
  "code": "not_found",
  "message": "session doesn't exists"
}
```

Treat the HTTP status and the JSON `code` as the stable error contract on this surface.

## 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).