Blendwave

Developer docs

A small, honest HTTP reference.

This is a source-backed inventory of the routes in the current Blendwave application. General production API key issuance is not available yet.

Start here

Availability

This is the minimum reference for the HTTP routes that are already present in the application. It is not an API launch promise. Blendwave does not currently issue production customer keys for the general workspace API, and there is no public Blendwave SDK in this reference. Treat the availability labels below as part of the contract.

Credentials

Authentication

The general workspace routes use a controlled local development credential path. They are structurally disabled in production. The console does not issue customer keys for these routes, so they are not available as a production customer API today.

Generic API channel credential

Connecting a Generic API channel creates a bearer secret scoped to that channel. The current channel detail screen masks the secret and does not provide a complete public issuance or reveal flow, so production use requires guided setup with Blendwave. This bearer accepts inbound channel traffic only. It does not unlock the workspace API preview.

Current surface

Endpoints

The workspace list below records implementation status only. It is not a usable production customer API until Blendwave ships a customer-key lifecycle. The reserved public help center routes return 503 without reading article data.

Workspace API, developer preview only

  • GET/api/v1/me

    Validate API access and read the workspace capability and quota surface.

  • GET/api/v1/conversations

    List conversations with optional status, limit, and cursor query parameters.

  • GET/api/v1/conversations/{id}

    Read one UUID-addressed conversation and its non-internal message thread.

  • GET/api/v1/contacts

    List contacts with optional segment, email, tag, limit, and cursor filters.

  • POST/api/v1/messages

    Record an outbound reply or internal note against an existing conversation.

Generic API channel, guided setup

  • POST/api/v1/inbound

    Ingest a message through a configured Generic API channel.

Generic inbound payloads

The inbound route is tied to a configured Generic API channel and its scoped bearer. Its payload schema is not published in this minimum guide. Do not guess a universal payload. Use the route only with a channel contract supplied by Blendwave.

Safe retries

Idempotency

The developer-preview POST /api/v1/messages route and guided POST /api/v1/inbound route accept an optional Idempotency-Key header. Send a unique, stable key for each logical request. Repeating the same key with the same body can return the cached result. Reusing it with a different body returns 409. A request already in progress can return 425.

Current request caching is not documented as durable across deployments. Keep your own stable request identifier and reconciliation record.

Failure contract

Errors

Error responses use an error code and may include a human-readable message. Rate limits return 429, aRetry-After header, and retry_after_ms when available. Handle status codes first, then the machine-readable error code.

400
Invalid JSON, identifier, payload, or idempotency key.
401
Missing or invalid credentials.
404
The scoped resource was not found.
409
An idempotency key was reused with a different body.
425
The matching request is still in progress.
429
The applicable rate limit was reached.
503
The requested prelaunch surface is unavailable.

Scope boundary

Service routes are not customer API routes

Provider status callbacks, payment webhooks, scheduled jobs, authentication callbacks, and internal operator streams are service routes. Do not call them as application endpoints. Their signature and verification contracts belong to the matching provider configuration, not this public guide.

Need an endpoint enabled or a contract clarified? Contact Blendwave.