distributor/docs/roadmap/api.md

# API Roadmap

This document records API work that is not part of the current implementation. Current HTTP upload behavior is documented in `docs/integrations/http-upload.md`, current configuration behavior is documented in `docs/config.md`, and current producer package usage is documented under `docs/consumers/`.

## Implemented HTTP Upload Behavior

The pipeline-scoped HTTP upload API is implemented. The current contract is:

- upload authentication is configured with top-level `upload_tokens`;
- token values resolve through the process environment or `secrets.directory`, never YAML literals;
- bearer tokens authenticate producers and authorize configured upload pipelines through `allow_pipelines`;
- upload requests use `POST /v1/pipelines/{pipeline_id}/upload`;
- missing, malformed, or unknown bearer tokens return `401 Unauthorized`;
- valid tokens that are not allowed for the requested pipeline return `403 Forbidden`;
- `pkg/upload` upload options require `PipelineID`;
- idempotency records are scoped by token id, pipeline id, and idempotency key;
- source manifests remain free of routing, destination, transform, and credential data.

The unscoped upload route no longer accepts uploads. Pipeline query parameters are rejected.

## Deferred API Work

The following topics remain separate roadmap items:

- durable upload status storage;
- durable idempotency records across server restarts;
- in-app public exposure policy;
- built-in TLS termination;
- built-in upload rate limiting.

## Boundaries

- Do not add destination selection to producer manifests.
- Do not let producers specify destination ids, transforms, links, publish policy, or transfer policy through the upload API.
- Keep `http_upload` source-only. A selected pipeline owns destination configuration, transforms, links, transfer policy, and publication behavior.