Skip to content
AdVentur.aiAdVentur.aiAdVentur.ai Docs

Reply inbox API

The reply inbox, Engage feeds and Reddit listening.

9 endpoints. Every path is relative to the API base URL and needs a bearer token unless it is marked public. See the REST API overview for authentication, errors and pagination.

GET/v1/orgs/{orgId}/engagement

Bearer tokenMCP tool: list_reply_inbox

Lists replies, mentions and community posts on X, and Reddit threads found by listening, with their drafted replies, newest first. Open items (the default) are those still waiting on a decision.

Path parameters

  • orgIdstring (uuid)required

Query parameters

  • statusstring

    one of open, sent, dismissed, all

  • kindstring

    one of mention, community, all

  • platformstring

    one of x, reddit, all

  • feedIdstring
  • pageinteger
  • limitinteger

Responses

200Lists replies, mentions and community posts on X, and Reddit threads found by listening, with their drafted replies, newest first. Open items (the default) are those still waiting on a decision.
  • dataobjectrequired
    Fields
    • itemsarray<object>required
      Item fields
      • idstring (uuid)required
      • platformstringrequired

        one of x, reddit

      • kindstringrequired

        one of mention, community

      • statusstringrequired

        one of new, drafted, sending, sent, dismissed, failed

      • externalPostIdstringrequired
      • urlstringrequired
      • authorobjectrequired
        Fields
        • handlestring | nullrequired
        • namestring | nullrequired
        • followersinteger | nullrequired
      • textstringrequired
      • postedAtstring | nullrequired
      • likeCountintegerrequired
      • replyCountintegerrequired
      • inReplyToTextstring | nullrequired
      • matchedBystring | nullrequired
      • feedIdstring | nullrequired
      • titlestring | nullrequired
      • communitystring | nullrequired
      • relevanceinteger | nullrequired
      • draftTextstring | nullrequired
      • draftReasonstring | nullrequired
      • canSendFromAppbooleanrequired
      • replyOnXUrlstringrequired
      • sentUrlstring | nullrequired
      • sentAtstring | nullrequired
      • lastErrorstring | nullrequired
      • createdAtstringrequired
    • pageintegerrequired
    • limitintegerrequired
    • totalintegerrequired
    • hasMorebooleanrequired
Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/engagement" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

PATCH/v1/orgs/{orgId}/engagement/{itemId}

Bearer tokenMCP tool: update_reply_draft

Edits a drafted reply, dismisses the item, brings it back, or records a reply posted on X by hand. Never posts anything.

Path parameters

  • orgIdstring (uuid)required
  • itemIdstring (uuid)required

Request body application/json

  • draftTextstring
  • statusstring

    one of drafted, dismissed, sent

Responses

200Edits a drafted reply, dismisses the item, brings it back, or records a reply posted on X by hand. Never posts anything.
  • dataobjectrequired
    Fields
    • idstring (uuid)required
    • platformstringrequired

      one of x, reddit

    • kindstringrequired

      one of mention, community

    • statusstringrequired

      one of new, drafted, sending, sent, dismissed, failed

    • externalPostIdstringrequired
    • urlstringrequired
    • authorobjectrequired
      Fields
      • handlestring | nullrequired
      • namestring | nullrequired
      • followersinteger | nullrequired
    • textstringrequired
    • postedAtstring | nullrequired
    • likeCountintegerrequired
    • replyCountintegerrequired
    • inReplyToTextstring | nullrequired
    • matchedBystring | nullrequired
    • feedIdstring | nullrequired
    • titlestring | nullrequired
    • communitystring | nullrequired
    • relevanceinteger | nullrequired
    • draftTextstring | nullrequired
    • draftReasonstring | nullrequired
    • canSendFromAppbooleanrequired
    • replyOnXUrlstringrequired
    • sentUrlstring | nullrequired
    • sentAtstring | nullrequired
    • lastErrorstring | nullrequired
    • createdAtstringrequired
Request
curl -X PATCH "https://api.adventur.ai/v1/orgs/$ORG_ID/engagement/$ITEM_ID" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/v1/orgs/{orgId}/engagement/{itemId}/draft

Bearer tokenMCP tool: draft_reply

Writes a new reply to an inbox item in the brand voice and the way the user writes in their own recent X posts, optionally steered by guidance. Posts nothing.

Path parameters

  • orgIdstring (uuid)required
  • itemIdstring (uuid)required

Request body application/json

  • guidancestring

Responses

200Writes a new reply to an inbox item in the brand voice and the way the user writes in their own recent X posts, optionally steered by guidance. Posts nothing.
  • dataobjectrequired
    Fields
    • idstring (uuid)required
    • platformstringrequired

      one of x, reddit

    • kindstringrequired

      one of mention, community

    • statusstringrequired

      one of new, drafted, sending, sent, dismissed, failed

    • externalPostIdstringrequired
    • urlstringrequired
    • authorobjectrequired
      Fields
      • handlestring | nullrequired
      • namestring | nullrequired
      • followersinteger | nullrequired
    • textstringrequired
    • postedAtstring | nullrequired
    • likeCountintegerrequired
    • replyCountintegerrequired
    • inReplyToTextstring | nullrequired
    • matchedBystring | nullrequired
    • feedIdstring | nullrequired
    • titlestring | nullrequired
    • communitystring | nullrequired
    • relevanceinteger | nullrequired
    • draftTextstring | nullrequired
    • draftReasonstring | nullrequired
    • canSendFromAppbooleanrequired
    • replyOnXUrlstringrequired
    • sentUrlstring | nullrequired
    • sentAtstring | nullrequired
    • lastErrorstring | nullrequired
    • createdAtstringrequired
Request
curl -X POST "https://api.adventur.ai/v1/orgs/$ORG_ID/engagement/$ITEM_ID/draft" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/v1/orgs/{orgId}/engagement/{itemId}/send

Bearer tokenMCP tool: send_reply

Posts the approved reply to a mention on X, or as a comment on a Reddit thread from the connected Reddit account. Sending is the approval, so the exact text is required. X community posts can't be replied to through X's API; post those on X with the item's replyOnXUrl.

Path parameters

  • orgIdstring (uuid)required
  • itemIdstring (uuid)required

Request body application/json

  • textstringrequired

Responses

200Posts the approved reply to a mention on X, or as a comment on a Reddit thread from the connected Reddit account. Sending is the approval, so the exact text is required. X community posts can't be replied to through X's API; post those on X with the item's replyOnXUrl.
  • dataobjectrequired
    Fields
    • idstring (uuid)required
    • platformstringrequired

      one of x, reddit

    • kindstringrequired

      one of mention, community

    • statusstringrequired

      one of new, drafted, sending, sent, dismissed, failed

    • externalPostIdstringrequired
    • urlstringrequired
    • authorobjectrequired
      Fields
      • handlestring | nullrequired
      • namestring | nullrequired
      • followersinteger | nullrequired
    • textstringrequired
    • postedAtstring | nullrequired
    • likeCountintegerrequired
    • replyCountintegerrequired
    • inReplyToTextstring | nullrequired
    • matchedBystring | nullrequired
    • feedIdstring | nullrequired
    • titlestring | nullrequired
    • communitystring | nullrequired
    • relevanceinteger | nullrequired
    • draftTextstring | nullrequired
    • draftReasonstring | nullrequired
    • canSendFromAppbooleanrequired
    • replyOnXUrlstringrequired
    • sentUrlstring | nullrequired
    • sentAtstring | nullrequired
    • lastErrorstring | nullrequired
    • createdAtstringrequired
Request
curl -X POST "https://api.adventur.ai/v1/orgs/$ORG_ID/engagement/$ITEM_ID/send" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"string"}'

POST/v1/orgs/{orgId}/engagement/reddit-suggestions

Bearer tokenMCP tool: suggest_reddit_listening

Suggests pain-point phrases and subreddits to listen to on Reddit, from the brand profile and strategy. Saves nothing.

Path parameters

  • orgIdstring (uuid)required

Responses

200Suggests pain-point phrases and subreddits to listen to on Reddit, from the brand profile and strategy. Saves nothing.
  • dataobjectrequired
    Fields
    • redditKeywordsarray<string>required
    • subredditsarray<string>required
Request
curl -X POST "https://api.adventur.ai/v1/orgs/$ORG_ID/engagement/reddit-suggestions" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

POST/v1/orgs/{orgId}/engagement/refresh

Bearer tokenMCP tool: refresh_reply_inbox

Pulls new replies, mentions and community posts from X, and Reddit threads about the workspace's pain points, into the reply inbox and drafts a reply to each. Posts nothing.

Path parameters

  • orgIdstring (uuid)required

Request body application/json

  • feedIdstring

Responses

200Pulls new replies, mentions and community posts from X, and Reddit threads about the workspace's pain points, into the reply inbox and drafts a reply to each. Posts nothing.
  • dataobjectrequired
    Fields
    • addedintegerrequired
    • draftedintegerrequired
    • mentionsFoundintegerrequired
    • communityFoundintegerrequired
    • redditFoundintegerrequired
    • feedsFoundintegerrequired
    • warningsarray<string>required
    • itemsarray<object>required
      Item fields
      • idstring (uuid)required
      • platformstringrequired

        one of x, reddit

      • kindstringrequired

        one of mention, community

      • statusstringrequired

        one of new, drafted, sending, sent, dismissed, failed

      • externalPostIdstringrequired
      • urlstringrequired
      • authorobjectrequired
        Fields
        • handlestring | nullrequired
        • namestring | nullrequired
        • followersinteger | nullrequired
      • textstringrequired
      • postedAtstring | nullrequired
      • likeCountintegerrequired
      • replyCountintegerrequired
      • inReplyToTextstring | nullrequired
      • matchedBystring | nullrequired
      • feedIdstring | nullrequired
      • titlestring | nullrequired
      • communitystring | nullrequired
      • relevanceinteger | nullrequired
      • draftTextstring | nullrequired
      • draftReasonstring | nullrequired
      • canSendFromAppbooleanrequired
      • replyOnXUrlstringrequired
      • sentUrlstring | nullrequired
      • sentAtstring | nullrequired
      • lastErrorstring | nullrequired
      • createdAtstringrequired
Request
curl -X POST "https://api.adventur.ai/v1/orgs/$ORG_ID/engagement/refresh" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET/v1/orgs/{orgId}/engagement/settings

Bearer tokenMCP tool: get_engagement_settings

The X accounts and keywords the reply inbox watches, its saved Engage feeds, the Reddit pain-point phrases and subreddits it listens to, and whether it checks automatically.

Path parameters

  • orgIdstring (uuid)required

Responses

200The X accounts and keywords the reply inbox watches, its saved Engage feeds, the Reddit pain-point phrases and subreddits it listens to, and whether it checks automatically.
  • dataobjectrequired
    Fields
    • watchHandlesarray<any>required
    • keywordsarray<string>required
    • autoRefreshbooleanrequired
    • redditKeywordsarray<string>required
    • subredditsarray<any>required
    • redditExcludeTermsarray<string>required
    • feedsarray<object>required
      Item fields
      • idstringrequired
      • namestringrequired
      • sourcestringrequired

        one of keywords, list, people

      • keywordsarray<string>required
      • listIdstring | nullrequired
      • handlesarray<string>required
      • minFollowersnumber | nullrequired
      • maxFollowersnumber | nullrequired
      • enabledbooleanrequired
      • lastCheckedAtstring | nullrequired
    • lastRefreshedAtstring | nullrequired
Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/engagement/settings" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

PUT/v1/orgs/{orgId}/engagement/settings

Bearer tokenMCP tool: update_engagement_settings

Sets the X accounts (up to 10) and keywords (up to 5) to watch for community posts, up to 5 Engage feeds, the Reddit pain-point phrases (up to 8) and subreddits (up to 10) to listen to, and whether to check automatically.

Path parameters

  • orgIdstring (uuid)required

Request body application/json

  • watchHandlesarray<any>
  • keywordsarray<string>
  • autoRefreshboolean
  • redditKeywordsarray<string>
  • subredditsarray<any>
  • redditExcludeTermsarray<string>
  • feedsarray<object>
    Item fields
    • namestringrequired
    • sourcestringrequired

      one of keywords, list, people

    • idstring
    • keywordsarray<string>
    • listIdany | null
    • handlesarray<any>
    • minFollowersinteger | null
    • maxFollowersinteger | null
    • enabledboolean

Responses

200Sets the X accounts (up to 10) and keywords (up to 5) to watch for community posts, up to 5 Engage feeds, the Reddit pain-point phrases (up to 8) and subreddits (up to 10) to listen to, and whether to check automatically.
  • dataobjectrequired
    Fields
    • watchHandlesarray<any>required
    • keywordsarray<string>required
    • autoRefreshbooleanrequired
    • redditKeywordsarray<string>required
    • subredditsarray<any>required
    • redditExcludeTermsarray<string>required
    • feedsarray<object>required
      Item fields
      • idstringrequired
      • namestringrequired
      • sourcestringrequired

        one of keywords, list, people

      • keywordsarray<string>required
      • listIdstring | nullrequired
      • handlesarray<string>required
      • minFollowersnumber | nullrequired
      • maxFollowersnumber | nullrequired
      • enabledbooleanrequired
      • lastCheckedAtstring | nullrequired
    • lastRefreshedAtstring | nullrequired
Request
curl -X PUT "https://api.adventur.ai/v1/orgs/$ORG_ID/engagement/settings" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST/v1/orgs/{orgId}/engagement/x-account-suggestions

Bearer tokenMCP tool: suggest_x_accounts

Suggests up to 15 X accounts the workspace's audience follows, checked against X for existence and size. Runs at most once a week; within the week it returns the saved suggestions at no cost. Saves no feed.

Path parameters

  • orgIdstring (uuid)required

Responses

200Suggests up to 15 X accounts the workspace's audience follows, checked against X for existence and size. Runs at most once a week; within the week it returns the saved suggestions at no cost. Saves no feed.
  • dataobjectrequired
    Fields
    • accountsarray<object>required
      Item fields
      • handlestringrequired
      • namestring | nullrequired
      • followersinteger | nullrequired
      • biostring | nullrequired
      • reasonstringrequired
    • generatedAtstringrequired
    • cachedbooleanrequired
    • nextRefreshAtstringrequired
Request
curl -X POST "https://api.adventur.ai/v1/orgs/$ORG_ID/engagement/x-account-suggestions" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"