# Export Center REST API

> **Audience:** Platform integrators, Console/CLI developers, and automation engineers orchestrating export runs.  
> **Base route:** `/api/export/*` behind the StellaOps gateway; requires Authority-issued tokens with export scopes.

This reference describes the Export Center API introduced in Export Center Phase 1 (Epic 10) and extended in Phase 2. Use it alongside the [Export Center Architecture](architecture.md) and [Profiles](profiles.md) guides for service-level semantics.

> Status: Endpoint implementation lands with `EXPORT-SVC-35-006` (Sprint 35) and related follow-on tasks. As of the current build the WebService hosts only the template stub; use this contract for coordination and update once the API is wired.

## 1. Authentication and headers

- **Authorization:** Bearer tokens in `Authorization: Bearer <token>` paired with DPoP proof. Required scopes per endpoint:
  - `export:profile:manage` for profile CRUD.
  - `export:run` to submit and cancel runs.
  - `export:read` to list and inspect runs.
  - `export:download` for bundle downloads and manifests.
- **Tenant context:** Provide `X-Stella-Tenant` when the token carries multiple tenants; defaults to token tenant otherwise.
- **Idempotency:** Mutating endpoints accept `Idempotency-Key` (UUID). Retrying with the same key returns the original result.
- **Rate limits and quotas:** Responses include `X-Stella-Quota-Limit`, `X-Stella-Quota-Remaining`, and `X-Stella-Quota-Reset`. Exceeding quotas returns `429 Too Many Requests` with `ERR_EXPORT_QUOTA`.
- **Content negotiation:** Requests and responses use `application/json; charset=utf-8` unless otherwise stated. Downloads stream binary content with profile-specific media types.
- **SSE:** Event streams set `Content-Type: text/event-stream` and keep connections alive with comment heartbeats every 15 seconds.

## 2. Error model

Errors follow standard HTTP codes with structured payloads:

```json
{
  "code": "ERR_EXPORT_002",
  "message": "Profile not found for tenant acme",
  "details": [],
  "traceId": "01J9N4Y4K2XY8C5V7T2S",
  "timestamp": "2025-10-29T13:42:11Z"
}
```

| Code | Description | Typical HTTP status | Notes |
|------|-------------|---------------------|-------|
| `ERR_EXPORT_001` | Validation failure (selectors, configuration) | 400 | `details` enumerates offending fields. |
| `ERR_EXPORT_002` | Profile missing or not accessible for tenant | 404 | Returned on run submission or profile fetch. |
| `ERR_EXPORT_003` | Concurrency or quota exceeded | 429 | Includes `retryAfterSeconds` in `details`. |
| `ERR_EXPORT_004` | Adapter failure (schema mismatch, upstream outage) | 502 | Worker logs contain adapter error reason. |
| `ERR_EXPORT_005` | Signing or KMS error | 500 | Run marked failed with `errorCode=signing`. |
| `ERR_EXPORT_006` | Distribution failure (HTTP, OCI, object storage) | 502 | `details` lists failing distribution driver. |
| `ERR_EXPORT_007` | Run canceled or expired | 409 | Includes cancel author and timestamp. |
| `ERR_EXPORT_BASE_MISSING` | Base manifest for delta exports not found | 400 | Specific to `mirror:delta`. |
| `ERR_EXPORT_EMPTY` | No records matched selectors (when `allowEmpty=false`) | 422 | Useful for guard-railled automation. |
| `ERR_EXPORT_QUOTA` | Daily quota exhausted | 429 | Always paired with quota headers. |

All responses include `traceId` for correlation with logs and metrics.

## 3. Profiles endpoints

### 3.1 List profiles

```
GET /api/export/profiles?kind=json&variant=raw&page=1&pageSize=20
Scopes: export:read
```

Returns tenant-scoped profiles. Response headers: `X-Total-Count`, `Link` for pagination.

**Response**

```json
{
  "items": [
    {
      "profileId": "prof-json-raw",
      "name": "Daily JSON Raw",
      "kind": "json",
      "variant": "raw",
      "distribution": ["http", "object"],
      "retention": {"mode": "days", "value": 14},
      "createdAt": "2025-10-23T08:00:00Z",
      "createdBy": "user:ops"
    }
  ],
  "page": 1,
  "pageSize": 20
}
```

### 3.2 Get a profile

```
GET /api/export/profiles/{profileId}
Scopes: export:read
```

Returns full configuration, including `config` payload, distribution options, and metadata.

### 3.3 Create a profile

```
POST /api/export/profiles
Scopes: export:profile:manage
```

**Request**

```json
{
  "profileId": "prof-airgap-mirror",
  "name": "Airgap Mirror Weekly",
  "kind": "mirror",
  "variant": "full",
  "include": ["advisories", "vex", "sboms", "policy"],
  "distribution": ["http", "object"],
  "encryption": {
    "enabled": true,
    "recipientKeys": ["age1tenantkey..."],
    "strict": false
  },
  "retention": {"mode": "days", "value": 30}
}
```

**Response 201**

```json
{
  "profileId": "prof-airgap-mirror",
  "version": 1,
  "createdAt": "2025-10-29T12:05:22Z",
  "createdBy": "user:ops",
  "status": "active"
}
```

### 3.4 Update profile metadata

```
PATCH /api/export/profiles/{profileId}
Scopes: export:profile:manage
```

Allows renaming, toggling distribution switches, or updating retention. Structural configuration updates (kind/variant/include) create a new revision; the API returns `revisionCreated=true` and the new `profileId` (e.g., `prof-airgap-mirror@2`).

### 3.5 Archive profile

```
POST /api/export/profiles/{profileId}:archive
Scopes: export:profile:manage
```

Marks profile as inactive; existing runs remain accessible. Use `:restore` to reactivate.

## 4. Run management

### 4.1 Submit an export run

```
POST /api/export/runs
Scopes: export:run
```

**Request**

```json
{
  "profileId": "prof-json-raw",
  "selectors": {
    "tenants": ["acme"],
    "timeWindow": {
      "from": "2025-10-01T00:00:00Z",
      "to": "2025-10-29T00:00:00Z"
    },
    "products": ["registry.example.com/app:*"],
    "sboms": ["sbom:S-1001", "sbom:S-2004"]
  },
  "policySnapshotId": "policy-snap-42",
  "options": {
    "allowEmpty": false,
    "priority": "standard"
  }
}
```

**Response 202**

```json
{
  "runId": "run-20251029-01",
  "status": "pending",
  "profileId": "prof-json-raw",
  "createdAt": "2025-10-29T12:12:11Z",
  "createdBy": "user:ops",
  "selectors": { "...": "..." },
  "links": {
    "self": "/api/export/runs/run-20251029-01",
    "events": "/api/export/runs/run-20251029-01/events"
  }
}
```

### 4.2 List runs

```
GET /api/export/runs?status=active&profileId=prof-json-raw&page=1&pageSize=10
Scopes: export:read
```

Returns latest runs with pagination. Each item includes summary counts, duration, and last event.

### 4.3 Get run status

```
GET /api/export/runs/{runId}
Scopes: export:read
```

Response fields:

| Field | Description |
|-------|-------------|
| `status` | `pending`, `running`, `success`, `failed`, `canceled`. |
| `progress` | Object with `adapters`, `bytesWritten`, `recordsProcessed`. |
| `errorCode` | Populated when `status=failed` (`signing`, `distribution`, etc). |
| `policySnapshotId` | Returned for policy-aware profiles. |
| `distributions` | List of available distribution descriptors (type, location, sha256, expiresAt). |

### 4.4 Cancel a run

```
POST /api/export/runs/{runId}:cancel
Scopes: export:run
```

Body optional (`{"reason": "Aborted due to incident INC-123"}`). Returns 202 and pushes `run.canceled` event.

## 5. Events and telemetry

### 5.1 Server-sent events

```
GET /api/export/runs/{runId}/events
Scopes: export:read
Accept: text/event-stream
```

Event payload example:

```
event: run.progress
data: {"runId":"run-20251029-01","phase":"adapter","adapter":"json","records":1024,"bytes":7340032,"timestamp":"2025-10-29T12:13:15Z"}
```

Event types:

| Event | Meaning |
|-------|---------|
| `run.accepted` | Planner accepted job and queued with Orchestrator. |
| `run.progress` | Periodic updates with phase, adapter, counts. |
| `run.distribution` | Distribution driver finished (includes descriptor). |
| `run.signed` | Signing completed successfully. |
| `run.succeeded` | Run marked `success`. |
| `run.failed` | Run failed; payload includes `errorCode`. |
| `run.canceled` | Run canceled; includes `canceledBy`. |

SSE heartbeats (`: ping`) keep long-lived connections alive and should be ignored by clients.

### 5.2 Audit events

`GET /api/export/runs/{runId}/events?format=audit` returns the same event stream in newline-delimited JSON for offline ingestion.

## 6. Download endpoints

### 6.1 Bundle download

```
GET /api/export/runs/{runId}/download
Scopes: export:download
```

Streams the primary bundle (tarball, zip, or profile-specific layout). Headers:

- `Content-Disposition: attachment; filename="export-run-20251029-01.tar.zst"`
- `X-Export-Digest: sha256:...`
- `X-Export-Size: 73482019`
- `X-Export-Encryption: age` (when mirror encryption enabled)

Supports HTTP range requests for resume functionality. If no bundle exists yet, responds `409` with `ERR_EXPORT_007`.

### 6.2 Manifest download

```
GET /api/export/runs/{runId}/manifest
Scopes: export:download
```

Returns signed `export.json`. To fetch the detached signature, append `?signature=true`.

### 6.3 Provenance download

```
GET /api/export/runs/{runId}/provenance
Scopes: export:download
```

Returns signed `provenance.json`. Supports `?signature=true`. Provenance includes attestation subject digests, policy snapshot ids, adapter versions, and KMS key identifiers.

### 6.4 Distribution descriptors

```
GET /api/export/runs/{runId}/distributions
Scopes: export:read
```

Lists all registered distribution targets (HTTP, OCI, object storage). Each item includes `type`, `location`, `sha256`, `sizeBytes`, and `expiresAt`.

## 7. Webhook hand-off

Exports can notify external systems once a run succeeds by registering an HTTP webhook:

```
POST /api/export/webhooks
Scopes: export:profile:manage
```

Payload includes `targetUrl`, `events` (e.g., `run.succeeded`), and optional secret for HMAC signatures. Webhook deliveries sign payloads with `X-Stella-Signature` header (`sha256=...`). Retries follow exponential backoff with dead-letter capture in `export_events`.

## 8. Observability

- **Metrics endpoint:** `/metrics` (service-local) exposes Prometheus metrics listed in [Architecture](architecture.md#observability).
- **Tracing:** When `traceparent` header is provided, worker spans join the calling trace.
- **Run lookup by trace:** Use `GET /api/export/runs?traceId={id}` when troubleshooting distributed traces.

## 9. Related documentation

- [Export Center Overview](overview.md)
- [Export Center Architecture](architecture.md)
- [Export Center Profiles](profiles.md)
- [Export Center CLI Guide](cli.md) *(companion document)*
- [Aggregation-Only Contract reference](../../ingestion/aggregation-only-contract.md)

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.