Skip to content
AdVentur.aiAdVentur.aiAdVentur.ai Docs

X DMs API

Tracked X DM conversations and drafted messages.

5 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}/dms

Bearer tokenMCP tool: list_dm_conversations

Lists the X direct-message conversations the user is tracking, with the drafted next message. Conversations where it's the user's turn come first, then ones where a follow-up is due.

Path parameters

  • orgIdstring (uuid)required

Query parameters

  • statusstring

    one of open, your_turn, waiting, follow_up_due, closed, all

Responses

200Lists the X direct-message conversations the user is tracking, with the drafted next message. Conversations where it's the user's turn come first, then ones where a follow-up is due.
  • dataobjectrequired
    Fields
    • itemsarray<object>required
      Item fields
      • idstring (uuid)required
      • platformstringrequired

        one of x

      • statusstringrequired

        one of your_turn, waiting, closed

      • personobjectrequired
        Fields
        • handlestringrequired
        • namestring | nullrequired
        • biostring | nullrequired
        • followersinteger | nullrequired
        • profileUrlstringrequired
      • notesstring | nullrequired
      • messagesarray<object>required
        Item fields
        • idstring (uuid)required
        • fromstringrequired

          one of them, me

        • textstringrequired
        • atstringrequired
      • draftTextstring | nullrequired
      • draftReasonstring | nullrequired
      • draftedAtstring | nullrequired
      • lastMessageAtstring | nullrequired
      • followUpAtstring | nullrequired
      • followUpDuebooleanrequired
      • sendOnXUrlstringrequired
      • createdAtstringrequired
Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/dms" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

POST/v1/orgs/{orgId}/dms

Bearer tokenMCP tool: add_dm_conversation

Starts tracking a direct-message conversation with someone on X, optionally with the messages so far, and drafts the next message in the user's voice. Adding someone already tracked carries on their conversation. Sends nothing.

Path parameters

  • orgIdstring (uuid)required

Request body application/json

  • handleanyrequired
  • messagesarray<object>
    Item fields
    • fromstringrequired

      one of them, me

    • textstringrequired
  • notesstring
  • draftboolean
  • guidancestring

Responses

201Starts tracking a direct-message conversation with someone on X, optionally with the messages so far, and drafts the next message in the user's voice. Adding someone already tracked carries on their conversation. Sends nothing.
  • dataobjectrequired
    Fields
    • idstring (uuid)required
    • platformstringrequired

      one of x

    • statusstringrequired

      one of your_turn, waiting, closed

    • personobjectrequired
      Fields
      • handlestringrequired
      • namestring | nullrequired
      • biostring | nullrequired
      • followersinteger | nullrequired
      • profileUrlstringrequired
    • notesstring | nullrequired
    • messagesarray<object>required
      Item fields
      • idstring (uuid)required
      • fromstringrequired

        one of them, me

      • textstringrequired
      • atstringrequired
    • draftTextstring | nullrequired
    • draftReasonstring | nullrequired
    • draftedAtstring | nullrequired
    • lastMessageAtstring | nullrequired
    • followUpAtstring | nullrequired
    • followUpDuebooleanrequired
    • sendOnXUrlstringrequired
    • createdAtstringrequired
Request
curl -X POST "https://api.adventur.ai/v1/orgs/$ORG_ID/dms" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"handle":"string"}'

PATCH/v1/orgs/{orgId}/dms/{conversationId}

Bearer tokenMCP tool: update_dm_conversation

Logs a message the other person sent or one the user sent on X, edits the drafted message or notes, or closes or reopens the conversation. Optionally drafts the next message. Sends nothing.

Path parameters

  • orgIdstring (uuid)required
  • conversationIdstring (uuid)required

Request body application/json

  • addMessageobject
    Fields
    • fromstringrequired

      one of them, me

    • textstringrequired
  • notesstring
  • draftTextstring
  • statusstring

    one of open, closed

  • draftboolean
  • guidancestring

Responses

200Logs a message the other person sent or one the user sent on X, edits the drafted message or notes, or closes or reopens the conversation. Optionally drafts the next message. Sends nothing.
  • dataobjectrequired
    Fields
    • idstring (uuid)required
    • platformstringrequired

      one of x

    • statusstringrequired

      one of your_turn, waiting, closed

    • personobjectrequired
      Fields
      • handlestringrequired
      • namestring | nullrequired
      • biostring | nullrequired
      • followersinteger | nullrequired
      • profileUrlstringrequired
    • notesstring | nullrequired
    • messagesarray<object>required
      Item fields
      • idstring (uuid)required
      • fromstringrequired

        one of them, me

      • textstringrequired
      • atstringrequired
    • draftTextstring | nullrequired
    • draftReasonstring | nullrequired
    • draftedAtstring | nullrequired
    • lastMessageAtstring | nullrequired
    • followUpAtstring | nullrequired
    • followUpDuebooleanrequired
    • sendOnXUrlstringrequired
    • createdAtstringrequired
Request
curl -X PATCH "https://api.adventur.ai/v1/orgs/$ORG_ID/dms/$CONVERSATION_ID" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE/v1/orgs/{orgId}/dms/{conversationId}

Bearer token

Stops tracking a conversation and deletes what was logged. Nothing changes on X.

Path parameters

  • orgIdstring (uuid)required
  • conversationIdstring (uuid)required

Responses

200Stops tracking a conversation and deletes what was logged. Nothing changes on X.
  • dataobjectrequired
    Fields
    • idstring (uuid)required
    • platformstringrequired

      one of x

    • statusstringrequired

      one of your_turn, waiting, closed

    • personobjectrequired
      Fields
      • handlestringrequired
      • namestring | nullrequired
      • biostring | nullrequired
      • followersinteger | nullrequired
      • profileUrlstringrequired
    • notesstring | nullrequired
    • messagesarray<object>required
      Item fields
      • idstring (uuid)required
      • fromstringrequired

        one of them, me

      • textstringrequired
      • atstringrequired
    • draftTextstring | nullrequired
    • draftReasonstring | nullrequired
    • draftedAtstring | nullrequired
    • lastMessageAtstring | nullrequired
    • followUpAtstring | nullrequired
    • followUpDuebooleanrequired
    • sendOnXUrlstringrequired
    • createdAtstringrequired
Request
curl -X DELETE "https://api.adventur.ai/v1/orgs/$ORG_ID/dms/$CONVERSATION_ID" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

POST/v1/orgs/{orgId}/dms/{conversationId}/draft

Bearer tokenMCP tool: draft_dm

Drafts the next message in a DM conversation in the user's voice: an opener, a reply to their last message, or a follow-up when they haven't answered. Sends nothing.

Path parameters

  • orgIdstring (uuid)required
  • conversationIdstring (uuid)required

Request body application/json

  • guidancestring

Responses

200Drafts the next message in a DM conversation in the user's voice: an opener, a reply to their last message, or a follow-up when they haven't answered. Sends nothing.
  • dataobjectrequired
    Fields
    • idstring (uuid)required
    • platformstringrequired

      one of x

    • statusstringrequired

      one of your_turn, waiting, closed

    • personobjectrequired
      Fields
      • handlestringrequired
      • namestring | nullrequired
      • biostring | nullrequired
      • followersinteger | nullrequired
      • profileUrlstringrequired
    • notesstring | nullrequired
    • messagesarray<object>required
      Item fields
      • idstring (uuid)required
      • fromstringrequired

        one of them, me

      • textstringrequired
      • atstringrequired
    • draftTextstring | nullrequired
    • draftReasonstring | nullrequired
    • draftedAtstring | nullrequired
    • lastMessageAtstring | nullrequired
    • followUpAtstring | nullrequired
    • followUpDuebooleanrequired
    • sendOnXUrlstringrequired
    • createdAtstringrequired
Request
curl -X POST "https://api.adventur.ai/v1/orgs/$ORG_ID/dms/$CONVERSATION_ID/draft" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'