---
title: API conventions
description: Common Basalt developer conventions for envelopes, errors, idempotency, revisions, limits, availability, and provenance.
slug: conventions
path: /conventions
section: Reference
availability: supported
nav_order: 12
canonical_url: https://developers.basaltnotes.com/conventions
markdown_url: https://developers.basaltnotes.com/conventions.md
mirror_url: https://basaltnotes.com/developers/conventions
---
# API conventions

Basalt has several developer surfaces, but they share a common set of reliability and trust conventions.

## JSON and Markdown representations

Where an endpoint explicitly supports it, clients may request a Markdown representation with:

```http
Accept: text/markdown
```

Do not assume every API endpoint has a Markdown representation.

## Idempotency

Applied write operations should use a stable idempotency key when the endpoint supports/requires one.

Common forms include:

```http
Idempotency-Key: external-operation-123
```

or an explicit `idempotencyKey` body field.

Use one stable key for retries of the same intended operation. Use a new key for a materially new operation/version.

## Dry run

Hosted knowledge mutations default to preview/dry-run on Developer REST and MCP transaction paths. Applying a mutation requires an explicit apply intent (`dryRun: false`) plus the other required safeguards.

Do not infer that a 2xx preview response means knowledge was mutated.

## Revisions

When changing/deleting existing knowledge, use the current revision/hash required by the endpoint. Depending on the surface this may be supplied as:

- `expectedHash`;
- `If-Match`;
- a Product Runtime current-revision field.

Treat a stale-revision error as a reconciliation event: re-read the current state and decide whether to retry with a new intentional mutation.

## Errors

Where present, use the machine-readable response `code` plus HTTP status as the stable branching signal. Human-readable messages may improve over time.

Expected error classes include:

- authentication required/invalid credential;
- plan/entitlement required;
- workspace role insufficient;
- logical vault or hosted mapping not authorized;
- invalid path/payload;
- stale revision/conflict;
- idempotency failure;
- quota/rate limit;
- unsupported runtime/schema version;
- capability unavailable because data is local-only.

## Availability and completeness

Product Runtime uses explicit availability/completeness semantics. A capability may be unavailable or partial rather than returning invented empty data.

When an API reports truncation or partial completeness, do not interpret absence from that response as proof of nonexistence.

## Limits

Limits are part of the trust and abuse boundary. Do not write clients that depend on silently exceeding documented payload, scan, source-count, action-count, or result limits.

Machine-readable schemas/OpenAPI should be treated as the preferred source for exact current limits where they exist.

## Time and cursors

Use returned timestamps/cursors as opaque contract values unless the endpoint documents arithmetic semantics. Provenance/event `since` values are intended to bound subsequent reads, not to infer global ordering across unrelated workspaces.

## Provenance

Preserve source IDs, revisions, provider/client identity, actor identity, fingerprints, and decision/action receipts where the workflow depends on traceability. Do not rewrite marketing attribution into provenance fields.

## Retries

Safe retry order:

1. retry reads according to normal network policy;
2. retry a dry run freely when inputs are unchanged;
3. retry an applied mutation only with the same idempotency key and expected semantic intent;
4. on revision conflict, re-read before forming a new mutation.

## Security

Never put bearer credentials in query strings, Handoff redirect URLs, telemetry payloads, or user-generated note content.