# OpenTelemetry API

## Quick reference

- **Base URL**

  api.altertable.ai

- **Protocol**

  OTLP/HTTP protobuf

- **Authentication**

  [HTTP Basic Auth](#authentication)

* [Export traces](#post-v1-traces)
* [Export logs](#post-v1-logs)
* [Configure an SDK](/docs/ingest-data/opentelemetry/logs.md#sdk-and-collector-setup)

Use the OpenTelemetry API to send OTLP/HTTP protobuf traces and logs to Altertable. Altertable writes accepted telemetry into the built-in `opentelemetry` catalog for the target environment.

For application setup, prefer the standard [OpenTelemetry SDKs](/docs/ingest-data/opentelemetry/logs.md#sdk-and-collector-setup). This page documents the HTTP endpoints those SDKs and collectors send to.

## API endpoint

| Hostname            | Port        | Protocol           |
| ------------------- | ----------- | ------------------ |
| `api.altertable.ai` | 443 (HTTPS) | OTLP/HTTP protobuf |

## Authentication

Authenticate requests with the same HTTP Basic Auth credentials used by the [Lakehouse API](/docs/api-references/lakehouse.md). Base64-encode your credentials in the format `lakehouse_username:lakehouse_password`:

```bash
echo -n "{{LAKEHOUSE_USERNAME}}:{{LAKEHOUSE_PASSWORD}}" | base64
```

Then send the encoded value in the `Authorization` header:

```http
Authorization: Basic <ALTERTABLE_BASIC_AUTH_TOKEN>
```

## Endpoints

| Signal | Endpoint                                   | Request body                                      | Content type             |
| ------ | ------------------------------------------ | ------------------------------------------------- | ------------------------ |
| Traces | `POST https://api.altertable.ai/v1/traces` | OTLP `ExportTraceServiceRequest` protobuf payload | `application/x-protobuf` |
| Logs   | `POST https://api.altertable.ai/v1/logs`   | OTLP `ExportLogsServiceRequest` protobuf payload  | `application/x-protobuf` |

Altertable does not support OpenTelemetry metrics yet. Do not send OTLP metrics payloads to Altertable.

## POST `/v1/traces`

Send an OTLP trace export payload to the built-in OpenTelemetry catalog.

**Authentication:** HTTP Basic Auth\
**Permission:** Write telemetry

| Parameter      | Type                      | Location | Required | Description                       |
| -------------- | ------------------------- | -------- | -------- | --------------------------------- |
| `Content-Type` | application/x-protobuf    | header   | Yes      | OTLP protobuf media type.         |
| `body`         | ExportTraceServiceRequest | body     | Yes      | Binary OTLP trace export payload. |

Accepted spans are written to `opentelemetry.main.spans`.

### Request

```curl
curl https://api.altertable.ai/v1/traces \
-H "Authorization: Basic $ALTERTABLE_BASIC_AUTH_TOKEN" \
-H "Content-Type: application/x-protobuf" \
--data-binary @traces.pb
```

## POST `/v1/logs`

Send an OTLP log export payload to the built-in OpenTelemetry catalog.

**Authentication:** HTTP Basic Auth\
**Permission:** Write telemetry

| Parameter      | Type                     | Location | Required | Description                     |
| -------------- | ------------------------ | -------- | -------- | ------------------------------- |
| `Content-Type` | application/x-protobuf   | header   | Yes      | OTLP protobuf media type.       |
| `body`         | ExportLogsServiceRequest | body     | Yes      | Binary OTLP log export payload. |

Accepted log records are written to `opentelemetry.main.logs`.

### Request

```curl
curl https://api.altertable.ai/v1/logs \
-H "Authorization: Basic $ALTERTABLE_BASIC_AUTH_TOKEN" \
-H "Content-Type: application/x-protobuf" \
--data-binary @logs.pb
```

## Related docs

- **[OpenTelemetry ingest](/docs/ingest-data/opentelemetry.md)**: enable the catalog and configure SDKs or collectors.
- **[OpenTelemetry OTLP specification](https://opentelemetry.io/docs/specs/otlp/)**: request payload definitions and protocol behavior.
- **[Lakehouse API authentication](/docs/api-references/lakehouse.md#authentication)**: Basic Auth format for lakehouse credentials.