REST API reference

Authenticate, list resources, create posts, handle errors, and use the BlendDuck OpenAPI 3.1 contract.

The BlendDuck v1 API uses JSON over HTTPS and is scoped to the organization selected by the bearer API key. The machine-readable OpenAPI 3.1 schema is the source of truth for all 25 operations, request and response schemas, generated SDKs, and compatibility checks.

Base URL and authentication

https://blendduck.com/api/v1

Create and manage organization API keys from Dashboard → Developer → API keys. The full key is shown only when created. Store it in a secret manager and send it only from trusted server-side code:

Authorization: Bearer $BLENDDUCK_API_KEY
Content-Type: application/json

The key selects exactly one organization. Canonical v1 requests never accept a workspace_id and never use a dashboard cookie as fallback authentication.

First request

curl --fail-with-body https://blendduck.com/api/v1/tenant \
  -H "Authorization: Bearer $BLENDDUCK_API_KEY"

A successful response uses a data envelope and includes the same request ID in meta.requestId and the X-Request-ID response header.

Endpoint catalog

Resource	Operations
Tenant	`GET /tenant`
Channels	`GET /channels`, `GET /channels/{channelId}`, `DELETE /channels/{channelId}`
Posts	`GET /posts`, `POST /posts`, `GET/PATCH/DELETE /posts/{postId}`
Analytics	`GET /analytics`
Media	`GET /media`, `POST /media`, `GET /media/{mediaId}`
Providers	`GET /providers`, `GET /providers/{providerId}`
Webhooks	`GET/POST /webhooks`, `GET/PATCH/DELETE /webhooks/{webhookEndpointId}`
Webhook operations	rotate secret, send test, list/get deliveries, and replay a failed delivery

Open the OpenAPI schema for every parameter, enum, field, example, response, and required scope. Generated clients are listed under SDKs.

Create a multi-channel post

Create a draft first when integrating. Replace the example UUID with a channel returned by GET /channels:

curl --fail-with-body https://blendduck.com/api/v1/posts \
  -X POST \
  -H "Authorization: Bearer $BLENDDUCK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-post-2026-08-09" \
  --data '{
    "content": "Hello from BlendDuck",
    "mode": "draft",
    "targets": [
      { "channelId": "00000000-0000-4000-8000-000000000000" }
    ]
  }'

One post.id identifies the logical post. targets[] contains independently addressable channel deliveries. A target may override content, publishAt, media, settings, or thread. Delivery modes are draft, schedule, next_available, prioritize, and publish_now.

Use Idempotency-Key on mutations. Repeating the same operation and payload with the same key returns the original result; reusing the key for a different payload returns a conflict.

Pagination and filtering

Collection endpoints accept limit from 1 to 100 and an opaque cursor. Read meta.pagination.nextCursor and pass it back unchanged. Stop when it is null; do not parse or manufacture cursors.

Endpoint-specific filters, sort order, and date formats are defined in /openapi.json. Date-time values use RFC 3339 with Z or an explicit offset.

Errors

Errors use one stable envelope:

{
  "error": {
    "code": "validation_error",
    "message": "The request could not be accepted",
    "details": []
  },
  "meta": { "requestId": "request-id" }
}

Status	Meaning	Client action
`400`	Invalid syntax or transport	Correct the request before retrying.
`401`	Missing, invalid, or revoked key	Replace or rotate the credential.
`403`	Valid key without required access	Grant the required scope or role.
`404`	Resource is not visible in this organization	Check the ID and tenant.
`409`	State or idempotency conflict	Read the current resource, then decide.
`422`	Field or provider validation failed	Use `error.details` to fix the input.
`429`	Quota or rate limit reached	Respect `Retry-After`.
`5xx`	BlendDuck or dependency failure	Retry only safe/idempotent operations with backoff.

API-key responses include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy. A throttled response also includes Retry-After.

Request tracing and security

Send X-Request-ID when you need to correlate a workflow across systems, or record the server-generated value. Logs must exclude Authorization headers, webhook secrets, raw social tokens, and unnecessary customer content.

Use a separate key per environment or integration, grant the smallest scopes, rotate suspected credentials immediately, and never expose organization keys in browser or mobile application bundles.

Versioning

Responses expose X-BlendDuck-API-Version. Additive fields can appear within v1, so clients should ignore unknown response fields. Removed or incompatible changes require a new version. Legacy workspace-addressed routes remain only for existing integrations and are excluded from OpenAPI, SDKs, and new examples.

On this page