For developers

Public REST API

Access and authentication

Base URL: https://api.blinkerbot.com/v1. API access requires the master feature flag and the workspace's PUBLIC_API entitlement; both are off until explicitly enabled. The owner or an administrator creates a scoped key in Settings → Developers using fresh 2FA, after the 24-hour security-change lock. Copy the key immediately; it is shown once. Keys have no automatic expiry; revoke them when no longer needed.

Send Authorization: Bearer bb_live_… on every request. Use HTTPS and a secure credential store. Never put a key in a URL, browser bundle, spreadsheet cell or application log. Only a SHA-256 hash and the last four characters are stored. Key listings never reveal the original. The key is limited to its workspace; resource IDs from another workspace return 404.

curl 'https://api.blinkerbot.com/v1/me' \
  -H 'Authorization: Bearer bb_live_REPLACE_WITH_YOUR_KEY'

Scopes and routes

  • Any active key: GET /v1/me returns workspace ID, name, slug, scopes and API version.
  • contacts:read: GET /v1/contacts and GET /v1/contacts/{id}.
  • contacts:write: PATCH /v1/contacts/{id}.
  • conversations:read: GET /v1/conversations and GET /v1/conversations/{id}/messages.
  • bookings:read: GET /v1/bookings.
  • webhooks:manage: GET /v1/webhooks, POST /v1/webhooks, DELETE /v1/webhooks/{id}.

Use the smallest set of scopes required by your automation. Write operations are activity logged. AI memory, raw provider payloads, recordings and credentials are excluded from API responses.

Contacts

curl 'https://api.blinkerbot.com/v1/contacts?limit=50&updated_since=2026-11-12T00%3A00%3A00Z' \
  -H 'Authorization: Bearer bb_live_REPLACE_WITH_YOUR_KEY'

Optional phone, email and search parameters perform substring matching; email matching is case insensitive. search matches phone or email. updated_since is an exclusive RFC3339 timestamp with a timezone. Contact tag changes advance updatedAt. Responses contain id, name, phone, email, notes, createdAt, updatedAt and tags: [{"name":"Qualified"}].

curl -X PATCH 'https://api.blinkerbot.com/v1/contacts/contact_example' \
  -H 'Authorization: Bearer bb_live_REPLACE_WITH_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Ada","email":"ada@example.com","phone":"+905550000000","notes":"Call tomorrow","tags":{"add":["Qualified"],"remove":["New"]}}'

Fields are optional; null clears a scalar field. Maximum lengths: name 200, email 320, phone 64, notes 2000, tag name 48. A patch must contain at least one field. Tags are contact tags, separate from conversation topics. At most 50 tag add/remove entries are allowed. Adding an existing tag is harmless; removing a missing one is harmless. Writes use the same normalization and tag-ownership logic as panel contact edits and emit transactional webhook events.

Pagination and filtering

List responses have the form:

{"data":[{"id":"contact_example","name":"Ada","phone":"+905550000000","email":"ada@example.com","notes":null,"createdAt":"2026-11-12T12:00:00Z","updatedAt":"2026-11-12T12:00:00Z","tags":[]}],"next_cursor":"opaque_cursor"}

limit defaults to 50, maximum 100. Pass next_cursor unchanged as cursor on the next request with the same filters. Null means the end. Contacts, conversations and bookings sort by updatedAt, then ID, ascending. Messages sort by creation time then ID. Cursors are specific to a resource; do not decode or construct them. Lists reflect live data, not an immutable snapshot: an edited row can appear again. Deduplicate by ID and preserve a sync timestamp watermark with overlap for subsequent incremental runs.

Conversations accept updated_since. Messages require an owned conversation ID. Bookings accept start_from (inclusive) and start_to (exclusive), both RFC3339 timestamps; they filter the booking start time. Example: /v1/bookings?start_from=2026-11-12T00%3A00%3A00Z&start_to=2026-11-13T00%3A00%3A00Z.

REST hooks: subscribe and unsubscribe

curl -X POST 'https://api.blinkerbot.com/v1/webhooks' \
  -H 'Authorization: Bearer bb_live_REPLACE_WITH_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://receiver.example/hooks/leads","description":"CRM leads","eventTypes":["lead.captured","contact.updated"]}'

201 returns { "data": { "id": "endpoint_example", "url": "…", "eventTypes": ["lead.captured","contact.updated"], "enabled": true, "secret": "whsec_…" } } with additional endpoint metadata. Save secret and id now; GET omits the secret. The workspace can have up to 10 endpoints, including disabled ones. A public HTTPS address is mandatory. Private addresses, local names, credentials in the URL, fragments and unsafe ports are refused. DNS is checked again at connection time; redirects are not followed.

DELETE /v1/webhooks/endpoint_example returns 204 and removes queued deliveries for that endpoint. A subsequent delete returns 404. GET lists subscriptions without secrets. The owner controls secret rotation and transcript inclusion in the panel; REST subscriptions default to excluding transcripts. Message events are sent only when explicitly selected. Full event catalogue, verification and recipes.

Rate limits and errors

Each key shares a 60-request/minute bucket across API replicas. RateLimit-Limit and RateLimit-Remaining describe the bucket. A 429 includes Retry-After in seconds; wait at least that duration before retrying. Temporary limiter/storage outages fail closed with 503.

{"error":{"code":"insufficient_scope","message":"insufficient scope"}}
  • 400: invalid_request, invalid_cursor, invalid_range, invalid_url, endpoint_limit.
  • 401: unauthorized (missing, invalid or revoked key).
  • 403: insufficient_scope, entitlement_required.
  • 404: not_found (also for another tenant's resource).
  • 429: rate_limited.
  • 503: service_unavailable, rate_limit_unavailable.

The public OpenAPI 3.1 contract is available at openapi.json when the feature is enabled. It includes request/response schemas, filters, authentication and required scopes. Official Zapier/Make app listings and native CRM connectors are separate future work; generic Webhook/HTTP modules work against this contract.