Doop API documentation

The Doop API lets an app act on behalf of a consenting account. API access is available to all active Doop accounts, with no paid subscription required. Documentation is public.

1. Open Settings → Integrations and create an app. Add your app’s privacy policy, support URL, and exact HTTPS callback URL.
2. Save your client ID and the one-time client secret in your server’s secret store. Apps start with access to their owner’s account. Request review to connect other Doop accounts.
3. Complete the OAuth flow below. Keep client secrets and tokens on your backend.
4. Make your first request with the resulting access token.

curl "https://doop.live/api/v1/me" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN"

{
  "data": {
    "id": "9cae713a-e731-40be-8c77-53bdfab2fd60",
    "username": "amara",
    "display_name": "Amara Mensah"
  }
}

Examples use illustrative IDs and content. Replace them with values returned for your account. You can download the OpenAPI specification for API clients.

v1 supports confidential server-side OAuth clients. Personal API keys, attachments, bulk messaging, post publishing, uploads, analytics, and financial operations are not included.

Use authorization code OAuth with PKCE S256. Each connection records the user’s explicit consent. Additional permissions require a new consent flow.

1. Prepare the authorization request

Create an unpredictable verifier and state value. Store both in the user’s server-side session, then redirect their browser to the authorization URL. The callback must exactly match a registered HTTPS URL, including its path and query.

import { randomBytes, createHash } from 'node:crypto';

const verifier = randomBytes(32).toString('base64url');
const state = randomBytes(32).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
// Save { verifier, state } in this user's server-side session.
const query = new URLSearchParams({
  response_type: 'code',
  client_id: process.env.DOOP_CLIENT_ID,
  redirect_uri: 'https://example.com/oauth/doop/callback',
  scope: 'profile:read posts:read comments:read',
  state,
  code_challenge: challenge,
  code_challenge_method: 'S256',
});
const authorizationUrl = 'https://doop.live/oauth/authorize?' + query;
// Redirect the user's browser to authorizationUrl.

After consent, the callback contains code, your state, and iss=https://doop.live. Verify state and issuer before exchanging the code. A declined request returns error=access_denied instead of a code.

2. Exchange the code

POST /oauth/token accepts form-encoded fields. Codes expire after five minutes and can be used once. Authenticate the client with HTTP Basic as below, or with client_id and client_secret form fields—never both.

curl -X POST "https://doop.live/oauth/token" \
  -u "$DOOP_CLIENT_ID:$DOOP_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=$DOOP_CODE" \
  --data-urlencode "redirect_uri=https://example.com/oauth/doop/callback" \
  --data-urlencode "code_verifier=$DOOP_VERIFIER"

{
  "access_token": "example_access_token",
  "refresh_token": "example_refresh_token",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "profile:read posts:read comments:read"
}

3. Refresh the connection

Access tokens last 15 minutes; refresh tokens last 30 days. Save both newly returned tokens atomically after every refresh. Serialize refreshes for the same connection; a duplicate refresh fails. Reusing an older refresh token outside the ten-second concurrency window revokes the connection.

curl -X POST "https://doop.live/oauth/token" \
  -u "$DOOP_CLIENT_ID:$DOOP_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=$DOOP_REFRESH_TOKEN"

The response has the same shape as the token response above. Omit scope when refreshing; to change permissions, reconnect through consent. The connected account must remain active.

4. Disconnect

curl -X POST "https://doop.live/oauth/revoke" \
  -u "$DOOP_CLIENT_ID:$DOOP_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=$DOOP_REFRESH_TOKEN"

A successful revocation returns HTTP 200 with {}. Either an access token or refresh token revokes the entire connection. Unknown tokens return the same response. Revocation and Settings disconnection remain available regardless of subscription. Disabling an app or rotating its secret disconnects its access.

OAuth failures

OAuth routes use the OAuth error format rather than the resource API envelope.

{
  "error": "invalid_grant",
  "error_description": "Credential already used. Reconnect if needed."
}

Request only what your app needs. A scope never overrides ownership, blocking, moderation, or messaging rules.

New apps may connect only their owner until approved by Doop. All active accounts can connect, regardless of plan. Subscription changes do not interrupt API access or webhooks. Suspended or closed accounts cannot use the API; users can still disconnect apps.

Safe retries

Use one stable idempotency key per intended write. If the connection drops, retry the same method, URL, key, and JSON body. The API returns the stored result without repeating the write. Reusing the key with different data returns 409. Keys belong to an OAuth connection and are not shared across reconnects. DELETE subscription requests are already idempotent and need no key.

List responses

Paginated endpoints return data and next_cursor. Default limit is 25; maximum is 100. Results are ordered by creation time, newest first. Pass a non-null cursor unchanged to fetch the next page. Keep separate cursors for each resource and Feed/Watch type. Webhook listing is a bounded list without cursor pagination.

{
  "data": [
    {
      "id": "feed_<uuid>",
      "body": "Example post",
      "created_at": "2026-10-11T10:00:00.000Z",
      "type": "feed"
    }
  ],
  "next_cursor": "opaque_cursor_returned_by_the_api"
}

curl --get "https://doop.live/api/v1/posts" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN" \
  --data-urlencode "type=feed" \
  --data-urlencode "limit=25" \
  --data-urlencode "cursor=$DOOP_NEXT_CURSOR"

For historical synchronization, walk pages until next_cursor is null. For incremental polling, deduplicate stable IDs and walk from the newest page until the last known record. New records created while paging are picked up by the next poll.

Identifiers & returned fields

Post and comment IDs are prefixed with feed_ or watch_. User, conversation, message, and subscription IDs are UUIDs. Dates are ISO 8601 strings. Nullable fields, such as parent_id and closed_at, use JSON null. A root comment has parent_id: null; a reply points to its root. Never infer ownership from an ID.

Resource errors return an error object containing code, message, and request_id. Do not branch on human-readable message text; use status and code.

{
  "error": {
    "code": "ACCOUNT_INACTIVE",
    "message": "An active Doop account is required.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

Request allowances

The API allows 120 requests per minute per account and per app/account pair, plus 30 resource POST attempts per hour per account. Existing messaging limits also apply. Retries consume request allowance. The token endpoint allows 60 requests per minute per client.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1791712860
X-Request-Id: cb5a1325-ff88-4453-8cd2-aa8fc4127eaf
Cache-Control: no-store

The reset value is Unix seconds. For a 429, honor Retry-After in seconds; the hourly write cap can differ from the per-minute allowance shown in X-RateLimit headers. Network-level protection may also reject a request before it reaches the resource handler.

Read and reply on your own Feed and Watch content. The same routes support both types through their prefixed IDs.

curl "https://doop.live/api/v1/posts?type=feed&limit=25" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "feed_0ebecbdb-d0a7-473a-b610-58c03a40f983",
      "body": "What would make your workflow easier?",
      "created_at": "2026-10-11T10:00:00.000Z",
      "type": "feed"
    }
  ],
  "next_cursor": null
}

{
  "error": {
    "code": "INVALID_TYPE",
    "message": "Choose feed or watch.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

curl "https://doop.live/api/v1/posts/feed_0ebecbdb-d0a7-473a-b610-58c03a40f983" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN"

{
  "data": {
    "id": "feed_0ebecbdb-d0a7-473a-b610-58c03a40f983",
    "body": "What would make your workflow easier?",
    "created_at": "2026-10-11T10:00:00.000Z",
    "type": "feed"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource is not available.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

curl "https://doop.live/api/v1/posts/feed_0ebecbdb-d0a7-473a-b610-58c03a40f983/comments?limit=25" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "feed_7973721b-a18c-4da5-90f5-bad85016ce00",
      "body": "Can this connect to our support tools?",
      "author_user_id": "82ba212a-b26b-4c2e-8edc-d8376638a0c2",
      "author_username": "kwame",
      "parent_id": null,
      "created_at": "2026-10-11T10:00:00.000Z",
      "post_id": "feed_0ebecbdb-d0a7-473a-b610-58c03a40f983"
    }
  ],
  "next_cursor": null
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource is not available.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

curl "https://doop.live/api/v1/comments/feed_7973721b-a18c-4da5-90f5-bad85016ce00/replies?limit=25" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "feed_c3164828-a34c-47a8-9a3b-1d8db3969ec1",
      "body": "Yes, you can connect them through the API.",
      "author_user_id": "9cae713a-e731-40be-8c77-53bdfab2fd60",
      "author_username": "amara",
      "parent_id": "feed_7973721b-a18c-4da5-90f5-bad85016ce00",
      "created_at": "2026-10-11T10:00:00.000Z",
      "post_id": "feed_0ebecbdb-d0a7-473a-b610-58c03a40f983"
    }
  ],
  "next_cursor": null
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource is not available.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

curl -X POST "https://doop.live/api/v1/comments/feed_7973721b-a18c-4da5-90f5-bad85016ce00/replies" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-event-001" \
  -d '{"body":"Yes, you can connect them through the API."}'

{
  "body": "Yes, you can connect them through the API."
}

{
  "data": {
    "id": "feed_c3164828-a34c-47a8-9a3b-1d8db3969ec1",
    "body": "Yes, you can connect them through the API.",
    "author_user_id": "9cae713a-e731-40be-8c77-53bdfab2fd60",
    "author_username": "amara",
    "parent_id": "feed_7973721b-a18c-4da5-90f5-bad85016ce00",
    "created_at": "2026-10-11T10:00:00.000Z",
    "post_id": "feed_0ebecbdb-d0a7-473a-b610-58c03a40f983"
  }
}

{
  "error": {
    "code": "REQUEST_REJECTED",
    "message": "Comments are disabled for this video.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

To contact someone new, find their public user ID, create or find a conversation, then send a message. A conversation can exist before a message request is accepted.

curl "https://doop.live/api/v1/users/by-username/kojo" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN"

{
  "data": {
    "id": "82ba212a-b26b-4c2e-8edc-d8376638a0c2",
    "username": "kojo",
    "display_name": "Kojo Owusu"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource is not available.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

curl "https://doop.live/api/v1/conversations?limit=25" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "f85a71e9-6d88-4fbe-b1bb-d9371044f568",
      "context_type": "DIRECT",
      "created_at": "2026-10-11T10:00:00.000Z",
      "closed_at": null,
      "message_request_state": "PENDING",
      "other_user_id": "82ba212a-b26b-4c2e-8edc-d8376638a0c2"
    }
  ],
  "next_cursor": null
}

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This connection does not have the required permission.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

curl -X POST "https://doop.live/api/v1/conversations" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-conversation-event-001" \
  -d '{"recipient_id":"82ba212a-b26b-4c2e-8edc-d8376638a0c2"}'

{
  "recipient_id": "82ba212a-b26b-4c2e-8edc-d8376638a0c2"
}

{
  "data": {
    "id": "f85a71e9-6d88-4fbe-b1bb-d9371044f568"
  }
}

{
  "error": {
    "code": "REQUEST_REJECTED",
    "message": "Contact is unavailable between these accounts.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

curl "https://doop.live/api/v1/conversations/f85a71e9-6d88-4fbe-b1bb-d9371044f568/messages?limit=25" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "b67c0875-60a4-4c29-8bcb-759a5a29ea75",
      "conversation_id": "f85a71e9-6d88-4fbe-b1bb-d9371044f568",
      "sender_user_id": "9cae713a-e731-40be-8c77-53bdfab2fd60",
      "body": "Hello! Thanks for reaching out.",
      "created_at": "2026-10-11T10:00:00.000Z"
    }
  ],
  "next_cursor": null
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource is not available.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

curl -X POST "https://doop.live/api/v1/conversations/f85a71e9-6d88-4fbe-b1bb-d9371044f568/messages" \
  -H "Authorization: Bearer $DOOP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-message-event-001" \
  -d '{"body":"Hello! Thanks for reaching out."}'

{
  "body": "Hello! Thanks for reaching out."
}

{
  "data": {
    "id": "b67c0875-60a4-4c29-8bcb-759a5a29ea75",
    "conversation_id": "f85a71e9-6d88-4fbe-b1bb-d9371044f568",
    "sender_user_id": "9cae713a-e731-40be-8c77-53bdfab2fd60",
    "body": "Hello! Thanks for reaching out.",
    "created_at": "2026-10-11T10:00:00.000Z"
  }
}

{
  "error": {
    "code": "REQUEST_REJECTED",
    "message": "This conversation is read-only.",
    "request_id": "cb5a1325-ff88-4453-8cd2-aa8fc4127eaf"
  }
}

Subscriptions start with new activity. They do not send historical data. Events come from both normal app use and API activity. The default ignore_own_app filter prevents your own integration’s writes from triggering a loop. Message events exclude system messages and your own outgoing messages.

Content-Type: application/json
X-Doop-Event-Id: 1ccfe516-b6a2-46cf-a932-18c57ee8e2f1
X-Doop-Signature: t=1791712800,v1=<hex_hmac_sha256>

{
  "id": "1ccfe516-b6a2-46cf-a932-18c57ee8e2f1",
  "type": "comment.created",
  "api_version": "v1",
  "created_at": "2026-10-11T10:00:00.000Z",
  "originating_app_id": null,
  "data": {
    "id": "feed_7973721b-a18c-4da5-90f5-bad85016ce00",
    "body": "Can this connect to our support tools?",
    "author_user_id": "82ba212a-b26b-4c2e-8edc-d8376638a0c2",
    "author_username": "kwame",
    "parent_id": null,
    "created_at": "2026-10-11T10:00:00.000Z",
    "post_id": "feed_0ebecbdb-d0a7-473a-b610-58c03a40f983"
  }
}

data is a single comment, message, or post with the same fields as the corresponding resource response. originating_app_id is null for normal app activity, or the app UUID for API-generated activity. Payload data is read at delivery time; deleted, blocked, or inaccessible content is withheld.

Verify the exact raw body

Compute HMAC-SHA256 over the timestamp, a period, and the unmodified raw request body using your subscription’s signing secret. Compare in constant time and reject timestamps more than five minutes from your server clock. Do not parse and reserialize the body before verification.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyDoopWebhook(rawBody, signature, secret) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signature || '');
  if (!match || Math.abs(Date.now() / 1000 - Number(match[1])) > 300) {
    throw new Error('Invalid or expired signature');
  }
  const expected = createHmac('sha256', secret)
    .update(match[1] + '.').update(rawBody).digest();
  const supplied = Buffer.from(match[2], 'hex');
  if (supplied.length !== expected.length || !timingSafeEqual(expected, supplied)) {
    throw new Error('Invalid signature');
  }
  return JSON.parse(rawBody.toString('utf8'));
}
// Capture a Buffer from your HTTP framework before its JSON parser.
// Verify, durably deduplicate event.id, enqueue the work, then return 2xx.

Delivery guarantees

Delivery is at least once and may arrive out of order. Event IDs remain stable across retries. Persist IDs to prevent duplicate downstream actions. Acknowledge with any 2xx response only after durable acceptance. Non-2xx responses and timeouts trigger retries; redirects are not followed.

Retry delays after failed attempts are 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 6 hours, and 12 hours. Delivery stops after eight attempts or seven days. Each HTTP attempt times out after ten seconds. Timing can be later depending on worker scheduling.

Inspect delivery status and attempt history in Settings → Integrations → Webhooks. Eligible failed or skipped events within seven days can be explicitly replayed with the same event ID. Diagnostics are retained for 30 days. Expiry, disconnection, or lost permission stops delivery; upgrading does not replay missed events automatically.

Webhook URLs must resolve only to public HTTPS destinations without URL credentials, fragments, or custom ports. Private, loopback, metadata, and reserved addresses are rejected. DNS is rechecked for each attempt.

Comment → spreadsheet

1. Connect with comments:read and webhooks:manage. Add posts:read if you need to discover post IDs.
2. Create a comment.created subscription, optionally filtered to one owned post.
3. Verify the signature and deduplicate the event ID.
4. Append data.id, data.post_id, data.author_user_id, data.body, and data.created_at to your spreadsheet.

Incoming message → support workflow

1. Connect with messages:read and webhooks:manage.
2. Subscribe to message.received and store the conversation_id with your support ticket.
3. If your workflow sends a response, also request messages:write and use a stable per-action idempotency key.

Automation → new conversation

1. Request profile:read, conversations:write, and messages:write.
2. Look up the recipient by username and use their returned ID to create or find a direct conversation.
3. Send the first message using the returned conversation ID. Handle a pending message request instead of repeatedly sending.

const response = await fetch(
  'https://doop.live/api/v1/conversations/' + conversationId + '/messages',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + accessToken,
      'Content-Type': 'application/json',
      'Idempotency-Key': sourceEventId + ':support-reply',
    },
    body: JSON.stringify({ body: 'Thanks! Our team will follow up here.' }),
  },
);
const result = await response.json();
if (!response.ok) {
  // Honor Retry-After on 429. Retry transient failures with the same key.
  throw new Error(result.error?.code || 'Request failed');
}
console.log(result.data.id);

OAuth and webhook contracts can be used by your own backend or automation platform. The Zapier connector is available by invitation while publication and reviewer access are being arranged. The Make app has been submitted for review and is pending approval. Neither submission nor successful test runs mean a public directory listing is available.

During review, use the Doop app invitation, add a Doop module, and create a connection. Sign in with Google, GitHub, or LinkedIn, then approve the requested permissions. A paid Doop subscription is not required. The official Make OAuth client is approved for consenting accounts beyond its owner; custom clients still require separate Doop approval. Revoke access in Settings → Integrations.

Triggers and actions

Triggers include Watch comments, Watch replies, Watch received messages, Watch published posts, and Watch activity. The combined trigger needs filters on Event type before using event-specific fields. Posts & comments contains Get a post, List posts, List comments, List replies, and Create a reply. Conversations & messages contains List conversations, List messages, Create a conversation, and Send a message. Account & users contains Get my profile and Find a user. Other contains Make an API call.

Map Resource ID from a trigger into the matching resource action. Event ID identifies the notification and is used for deduplication. Create a conversation returns only Conversation ID; List conversations provides additional conversation details. Ownership, blocking, and message-request rules apply to every action.

Post pickers and list limits

Get a post, List comments, and comment/reply webhook filters offer Feed or Watch followed by a post picker. The picker follows pages of 100 up to 500 posts. Map a prefixed Post ID for a post outside that list. Get a post starts in mapping mode. The type selector only affects picker options; leaving an optional webhook Post ID blank watches all Feed and Watch posts. The connector omits the empty filter; the API also accepts null as no filter.

List modules default to 10 results. Limit is optional: leave it empty for all available records. Requests fetch 100 records per page, following next_cursor, and Make trims to the chosen total. Large unbounded lists can consume more time and credits.

Prevent duplicate replies and messages

Map Event ID plus a distinct step name into Unique operation key, for example Event ID followed by :reply or:message. Retain the same key when retrying the same operation. A new operation needs a new source-event key. A constant reused across runs returns the previous result without another write; changing the input under that key returns HTTP 409. Random defaults are intentionally avoided because they can duplicate writes on retry. For other workflows, persist a source task identifier plus a step name.

API calls and troubleshooting

Make an API call takes a path such as api/v1/me, query parameters, optional headers, and a JSON body. Authorization comes from the connection; POST requests need a Unique operation key. OAuth failures show error and error_description. Resource failures show error.code and error.message, with a response-body fallback for network-level failures. Reconnect after revoked access, check ownership and blocking for 403/404, and retain the operation key when retrying temporary failures. See Errors & rate limits above.

Open Profile → Account settings → Automations to build a sequence inside Doop. All active accounts can create automations. Free includes 1 automation with 2 steps; Creator ($5/month) includes 3 automations with 4 steps each; Creator Plus ($20/month) includes unlimited automations and steps. Every card counts, including the trigger and optional keyword condition.

All plans retain a safety limit of 30 completed sequences per hour per account. Your own comments and automated/API activity are ignored. Blocking, ownership, and message-request rules still apply; incoming message requests must be accepted before an automatic reply can be sent. If any action fails, the sequence rolls back together. Temporary failures retry up to three attempts.

Pause, edit, or delete an automation in the manager. Changes discard queued work from the previous version. After a downgrade, the oldest saved automations retain the available plan slots. Automations over the count or step allowance stay saved but cannot run until they fit the plan. Paused automations also occupy a slot. Restoring access does not replay missed activity.