Blendwave

Developer docs

A small, honest HTTP reference.

This is a source-backed inventory of the routes in the current Blendwave application. Generated from the API's own OpenAPI document, so it cannot drift.

Start here

Availability

This is a source-backed reference for the HTTP routes present in the application. The endpoint list below is generated from the same OpenAPI document the API serves, so it cannot drift from what actually exists. There is still no public Blendwave SDK, and the API is closed by default: a workspace is enrolled before its keys work.

Credentials

Authentication

Every workspace route takes an Authorization: Bearer header carrying a workspace API key, which begins bwsk_. A key belongs to one workspace and holds a fixed set of scopes chosen when it was created. Scopes cannot be edited afterwards: to change what a key may do, revoke it and create another. Keys are secret and belong on your server, never in a browser. Access is granted per workspace, so a key only works once Blendwave has enrolled that workspace.

Generic API channel credential

Connecting a Generic API channel creates a separate bearer secret scoped to that channel, shown on the channel screen under Server credentials. It is a different credential from a workspace API key and does a different job: it accepts inbound messages on that one channel and unlocks nothing else. Like the workspace key, it belongs on your server.

Current surface

Endpoints

Generated from the OpenAPI document at /api/v1/openapi.json, which is the machine-readable version of this page and needs no credentials to read. Each entry names the scope it requires.

Workspace API

  • GET/api/oauth/authorize

    Start the consent flow in a browser.

  • POST/api/oauth/revoke

    Hand back a token you no longer need.

  • POST/api/oauth/token

    Exchange a code for tokens, or rotate a refresh token.

  • GET/api/v1/audit-log

    Read the tamper-evident audit trail.

  • GET/api/v1/contacts

    List contacts.

  • POST/api/v1/contacts

    Create or update a contact by your own user id.

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

    Read one contact.

  • PATCH/api/v1/contacts/{id}

    Update a contact, or bind one of your user ids to it.

  • GET/api/v1/conversations

    List conversations.

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

    Read one conversation with its thread.

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

    Change status, priority or assignee.

  • GET/api/v1/conversations/export

    Backfill historical conversations with their messages.

  • GET/api/v1/data-requests

    List subject-rights requests for this workspace.

  • POST/api/v1/data-requests

    Raise an export or deletion request for a contact.

  • GET/api/v1/help-center/articles

    List published help articles.

  • GET/api/v1/help-center/articles/{slug}

    Read one published article by slug.

  • GET/api/v1/me

    Validate a key and read back what it may do.

  • GET/api/v1/messages

    Describe the send endpoint.

  • POST/api/v1/messages

    Send an outbound reply, or add an internal note.

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.