Create Configurations with Custom Resources via the API

Create custom sources, destinations, processors, and extensions with the Bindplane API.

This guide uses POST /v1/apply with JSON to create Bindplane resources that store OpenTelemetry component YAML and a Bindplane configuration that references them by name.

Prerequisites

• Access to the Bindplane API (Growth and Enterprise)

• An API key sent on every request as X-Bindplane-Api-Key

• Your server base URL (cloud: https://app.bindplane.com, or your self-hosted URL)

Step 1 - Define custom sources and destinations

Define Bindplane resources whose spec.parameters include telemetry_types and configuration. The configuration value should contain YAML for a single OTel component (receiver, exporter, and so on).

Custom source (hostmetrics receiver)

apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
  id: hostmetrics-id
  name: hostmetrics
spec:
  type: custom
  parameters:
    - name: telemetry_types
      value:
        - Metrics
    - name: configuration
      value: |-
        hostmetrics:
          collection_interval: 1m0s
          scrapers:
            filesystem:
              metrics:
                system.filesystem.utilization:
                  enabled: true
            load:
              metrics: null
            memory:
              metrics:
                system.memory.utilization:
                  enabled: true
            network:
              metrics:
                system.network.conntrack.count:
                  enabled: true
                system.network.conntrack.max:
                  enabled: true

Edit custom source in the UI: same hostmetrics YAML under Configuration, with telemetry type set to Metrics.

Identifiers metadata.id and metadata.name identify this source. The configuration you build later references the resource by metadata.name (hostmetrics here). id is commonly a unique string or GUID; what matters for linking is a stable name.

Parameters

• telemetry_types controls which pipelines Bindplane adds this receiver to. Hostmetrics produces metrics only, so use Metrics.

• configuration is the YAML for that one component. Do not paste a full collector config here, only the receiver block.

Custom destination (OTLP exporter)

apiVersion: bindplane.observiq.com/v1
kind: Destination
metadata:
  id: otlp-id
  name: otlp
spec:
  type: custom:1
  parameters:
    - name: telemetry_types
      value:
        - Logs
        - Metrics
        - Traces
    - name: configuration
      value: |-
        otlp:
          compression: gzip
          endpoint: 127.0.0.1:4317
          timeout: 30s
          tls:
            insecure: true

Edit custom destination in the UI: OTLP exporter YAML and all three telemetry types selected.

When a telemetry type is present from a source in the configuration, Bindplane attaches this destination to pipelines for those signal types. The configuration block is the OTLP exporter YAML only.

Step 2 - Apply resources with the API

Bindplane resources are often edited as YAML, but /v1/apply expects a JSON body: an object with a resources array.

Example body that creates the destination and source above:

{
  "resources": [
    {
      "apiVersion": "bindplane.observiq.com/v1",
      "kind": "Destination",
      "metadata": {
        "id": "otlp-id",
        "name": "otlp"
      },
      "spec": {
        "type": "custom:1",
        "parameters": [
          {
            "name": "telemetry_types",
            "value": ["Logs", "Metrics", "Traces"]
          },
          {
            "name": "configuration",
            "value": "otlp:\n  compression: gzip\n  endpoint: 127.0.0.1:4317\n  timeout: 30s\n  tls:\n    insecure: true"
          }
        ]
      }
    },
    {
      "apiVersion": "bindplane.observiq.com/v1",
      "kind": "Source",
      "metadata": {
        "id": "hostmetrics-id",
        "name": "hostmetrics"
      },
      "spec": {
        "type": "custom",
        "parameters": [
          {
            "name": "telemetry_types",
            "value": ["Metrics"]
          },
          {
            "name": "configuration",
            "value": "hostmetrics:\n  collection_interval: 1m0s\n  scrapers:\n    filesystem:\n      metrics:\n        system.filesystem.utilization:\n          enabled: true\n    load:\n      metrics: null\n    memory:\n      metrics:\n        system.memory.utilization:\n          enabled: true\n    network:\n      metrics:\n        system.network.conntrack.count:\n          enabled: true\n        system.network.conntrack.max:\n          enabled: true"
          }
        ]
      }
    }
  ]
}

Save that object to a file (for example resources.json) and send it:

curl -sS -X POST "${BINDPLANE_URL}/v1/apply" \
  -H "X-Bindplane-Api-Key: ${BINDPLANE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d @resources.json

Set BINDPLANE_URL to your base URL (no trailing slash), for example https://app.bindplane.com.

Step 3 - Create and apply a configuration

A configuration lists which sources and destinations to use. Under each entry, id is local to that configuration; name must match the metadata.name of the source or destination resource.

YAML

apiVersion: bindplane.observiq.com/v1
kind: Configuration
metadata:
  id: test-config-id
  name: test-config
  labels:
    platform: macos
spec:
  sources:
    - id: source1
      name: hostmetrics
  destinations:
    - id: destination1
      name: otlp

Set metadata.labels.platform to the OS where collectors run: macos, linux, or windows.

JSON for /v1/apply

{
  "resources": [
    {
      "apiVersion": "bindplane.observiq.com/v1",
      "kind": "Configuration",
      "metadata": {
        "id": "test-config-id",
        "name": "test-config",
        "labels": {
          "platform": "macos"
        }
      },
      "spec": {
        "sources": [{ "id": "source1", "name": "hostmetrics" }],
        "destinations": [{ "id": "destination1", "name": "otlp" }]
      }
    }
  ]
}

After resources exist, the configuration appears in the UI with custom hostmetrics and OTLP components on the pipeline canvas.

Save the JSON to a file such as configuration.json and apply it:

curl -sS -X POST "${BINDPLANE_URL}/v1/apply" \
  -H "X-Bindplane-Api-Key: ${BINDPLANE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d @configuration.json

After apply, roll out the configuration to agents from the Bindplane UI if you do not have automatic rollouts enabled.

Processors

Custom processors follow the same telemetry_types and configuration pattern. Use the spec.type value your account expects for custom processors (often custom or custom:1); keep new resources consistent with your existing YAML exports.

Standalone processor resource (YAML)

apiVersion: bindplane.observiq.com/v1
kind: Processor
metadata:
  id: addfields-id
  name: addfields
spec:
  type: custom
  parameters:
    - name: telemetry_types
      value:
        - Metrics
    - name: configuration
      value: |-
        transform:
          error_mode: ignore
          metric_statements:
            - context: datapoint
              statements:
                - set(attributes["field1"], "foo") where true

JSON for /v1/apply

{
  "resources": [
    {
      "apiVersion": "bindplane.observiq.com/v1",
      "kind": "Processor",
      "metadata": {
        "id": "addfields-id",
        "name": "addfields"
      },
      "spec": {
        "type": "custom:1",
        "parameters": [
          {
            "name": "telemetry_types",
            "value": ["Metrics"]
          },
          {
            "name": "configuration",
            "value": "transform:\n  error_mode: ignore\n  metric_statements:\n    - context: datapoint\n      statements:\n        - set(attributes[\"field1\"], \"foo\") where true"
          }
        ]
      }
    }
  ]
}

Attach a processor to a configuration

Processors are not declared as a separate top-level list on the configuration. Attach them under a source or destination:

• Under a source, the processor runs after that source in the pipeline.

• Under a destination, the processor runs before that destination.

Processor after source

spec:
  sources:
    - id: source1
      name: hostmetrics
      processors:
        - id: p-addfields
          name: addfields
  destinations:
    - id: destination1
      name: otlp

Processor before destination

spec:
  sources:
    - id: source1
      name: hostmetrics
  destinations:
    - id: destination1
      name: otlp
      processors:
        - id: p-addfields
          name: addfields

With multiple processors in one list, Bindplane runs the first entry first.

Extensions

Define extensions inline on the configuration spec with type: custom and the same parameter shape.

apiVersion: bindplane.observiq.com/v1
kind: Configuration
metadata:
  id: test-config-id
  name: test-config
  labels:
    platform: macos
spec:
  sources:
    - id: source1
      name: hostmetrics
      processors:
        - id: p-addfields
          name: addfields
  destinations:
    - id: destination1
      name: otlp
  extensions:
    - id: extension1
      type: custom
      parameters:
        - name: telemetry_types
          value:
            - Logs
            - Metrics
            - Traces
        - name: configuration
          value: |-
            pprof:
              endpoint: 127.0.0.1:1777

Convert the configuration to the same {"resources":[...]} JSON shape and POST it to /v1/apply if you manage it through the API.

Next Steps

• Custom source

• Custom destination

• Custom processor

• Custom extension

• REST API reference