Skip to content
AdVentur.aiAdVentur.aiAdVentur.ai Docs

Scheduler API

Best-time suggestions, posting windows and schedule coverage.

6 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}/marketing/scheduler/events

Bearer token

Path parameters

  • orgIdstring (uuid)required

Query parameters

  • pageinteger
  • limitinteger
  • sortBystring

    one of scheduledForUtc, createdAt, status, platform

  • sortDirstring

    one of asc, desc

  • filterobject
    Fields
    • platformstring
    • statusstring
    • socialAccountIdstring
    • tagIdstring
    • scheduledFromstring
    • scheduledTostring
  • filterOpobject
    Fields
    • platformstring

      one of eq, in

    • statusstring

      one of eq, in

    • socialAccountIdstring

      one of eq

    • tagIdstring

      one of eq, in

    • scheduledFromstring

      one of gte

    • scheduledTostring

      one of lte

Responses

200
  • dataarray<object>required
    Item fields
    • idstring (uuid)required
    • orgIdstring (uuid)required
    • groupIdstring (uuid)required
    • platformstringrequired

      one of x, linkedin, tiktok, reddit, facebook, instagram, youtube, bluesky, threads

    • socialAccountIdstring (uuid) | nullrequired
    • statusstringrequired

      one of draft, pending_approval, approved, scheduled, publishing, awaiting_platform, published, failed, canceled

    • scheduledForUtcstring | nullrequired
    • contentTextstringrequired
    • mediaobject | nullrequired
    • platformPayloadobject | nullrequired
    • publishedExternalIdstring | nullrequired
    • publishedUrlstring | nullrequired
    • attemptCountnumberrequired
    • lastAttemptAtstring | nullrequired
    • nextRetryAtstring | nullrequired
    • lastErrorstring | nullrequired
    • idempotencyKeystring | nullrequired
    • createdAtstringrequired
    • updatedAtstringrequired
    • scheduleReasonstring | null
    • approvalsarray<object>
      Item fields
      • idstring (uuid)required
      • levelstringrequired

        one of group, post

      • groupIdstring (uuid)required
      • postIdstring (uuid) | nullrequired
      • approvedByUserIdstring (uuid)required
      • approvedAtstringrequired
      • actionstringrequired

        one of submit_for_approval, approved, reapproved, rejected

Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/scheduler/events" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

GET/v1/orgs/{orgId}/marketing/scheduler/schedule-coverage

Bearer token

Derived schedule-coverage state for the next N days (gaps, clustering, pending approval).

Path parameters

  • orgIdstring (uuid)required

Query parameters

  • daysinteger
  • timezonestring

Responses

200Derived schedule-coverage state for the next N days (gaps, clustering, pending approval).
  • dataobjectrequired
    Fields
    • windowDaysintegerrequired
    • timezonestringrequired
    • overallStatusstringrequired

      one of covered, needs_attention

    • channelsarray<object>required
      Item fields
      • platformstringrequired

        one of x, linkedin, tiktok, reddit, facebook, instagram, youtube, bluesky, threads

      • scheduledCountintegerrequired
      • publishedCountintegerrequired
      • pendingApprovalCountintegerrequired
      • targetPostsnumber | nullrequired
      • statusstringrequired

        one of covered, gap, clustered, waiting

      • nextGapAtstring | nullrequired
      • notesarray<string>required
    • pendingApprovalTotalintegerrequired
Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/scheduler/schedule-coverage" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

GET/v1/orgs/{orgId}/marketing/scheduler/settings

Bearer token

The workspace's scheduling profile: audience type and timezone, posting windows per platform, blackout dates, spacing and daily limits. Unset fields show the defaults for the audience type.

Path parameters

  • orgIdstring (uuid)required

Responses

200The workspace's scheduling profile: audience type and timezone, posting windows per platform, blackout dates, spacing and daily limits. Unset fields show the defaults for the audience type.
  • dataobjectrequired
    Fields
    • timezonestringrequired
    • timezoneIsSetbooleanrequired
    • audienceTimezonestring | nullrequired
    • effectiveTimezonestringrequired
    • audienceTypestringrequired

      one of b2b, b2c, mixed

    • includeWeekendsbooleanrequired
    • postingWindowsobjectrequired
      Fields
      • xarray<object>required
        Item fields
        • daysarray<integer>required
        • startstringrequired
        • endstringrequired
        • weightnumberrequired
      • linkedinarray<object>required
        Item fields
        • daysarray<integer>required
        • startstringrequired
        • endstringrequired
        • weightnumberrequired
      • tiktokarray<object>required
        Item fields
        • daysarray<integer>required
        • startstringrequired
        • endstringrequired
        • weightnumberrequired
    • customPostingWindowsarray<string>required
    • blackoutDatesarray<string>required
    • minGapMinutesintegerrequired
    • maxPostsPerDayintegerrequired
    • ownerAvailabilityarray<object>required
      Item fields
      • daysarray<integer>required
      • startstringrequired
      • endstringrequired
Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/scheduler/settings" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

PATCH/v1/orgs/{orgId}/marketing/scheduler/settings

Bearer token

Change part of the scheduling profile. Fields left out stay as they are. Owner/admin only.

Path parameters

  • orgIdstring (uuid)required

Request body application/json

  • audienceTimezonestring | null
  • audienceTypestring

    one of b2b, b2c, mixed

  • includeWeekendsboolean | null
  • postingWindowsobject
    Fields
    • xarray<object>
      Item fields
      • daysarray<integer>required
      • startstringrequired
      • endstringrequired
      • weightnumber
    • linkedinarray<object>
      Item fields
      • daysarray<integer>required
      • startstringrequired
      • endstringrequired
      • weightnumber
    • tiktokarray<object>
      Item fields
      • daysarray<integer>required
      • startstringrequired
      • endstringrequired
      • weightnumber
  • blackoutDatesarray<string>
  • minGapMinutesinteger
  • maxPostsPerDayinteger
  • ownerAvailabilityarray<object>
    Item fields
    • daysanyrequired
    • startstringrequired
    • endstringrequired
  • timezoneany
  • resetPostingWindowsarray<string>

Responses

200Change part of the scheduling profile. Fields left out stay as they are. Owner/admin only.
  • dataobjectrequired
    Fields
    • timezonestringrequired
    • timezoneIsSetbooleanrequired
    • audienceTimezonestring | nullrequired
    • effectiveTimezonestringrequired
    • audienceTypestringrequired

      one of b2b, b2c, mixed

    • includeWeekendsbooleanrequired
    • postingWindowsobjectrequired
      Fields
      • xarray<object>required
        Item fields
        • daysarray<integer>required
        • startstringrequired
        • endstringrequired
        • weightnumberrequired
      • linkedinarray<object>required
        Item fields
        • daysarray<integer>required
        • startstringrequired
        • endstringrequired
        • weightnumberrequired
      • tiktokarray<object>required
        Item fields
        • daysarray<integer>required
        • startstringrequired
        • endstringrequired
        • weightnumberrequired
    • customPostingWindowsarray<string>required
    • blackoutDatesarray<string>required
    • minGapMinutesintegerrequired
    • maxPostsPerDayintegerrequired
    • ownerAvailabilityarray<object>required
      Item fields
      • daysarray<integer>required
      • startstringrequired
      • endstringrequired
Request
curl -X PATCH "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/scheduler/settings" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET/v1/orgs/{orgId}/marketing/scheduler/slots

Bearer tokenMCP tool: suggest_slots

Ranks the best upcoming publishing times for a platform from the workspace's scheduling profile and its own post results, skipping times that clash with scheduled posts. Each slot says why it was picked.

Path parameters

  • orgIdstring (uuid)required

Query parameters

  • platformstring

    one of x, linkedin, tiktok

  • contentTypestring
  • daysinteger
  • countinteger

Responses

200Ranks the best upcoming publishing times for a platform from the workspace's scheduling profile and its own post results, skipping times that clash with scheduled posts. Each slot says why it was picked.
  • dataobjectrequired
    Fields
    • timezonestringrequired
    • audienceTypestringrequired

      one of b2b, b2c, mixed

    • historyPostsintegerrequired
    • slotsarray<object>required
      Item fields
      • scheduledForUtcstringrequired
      • localDatestringrequired
      • localTimestringrequired
      • weekdaystringrequired
      • scorenumberrequired
      • reasonstringrequired
      • basisstringrequired

        one of defaults, history

Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/scheduler/slots" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"

GET/v1/orgs/{orgId}/marketing/scheduler/suggested-times

Bearer token

Path parameters

  • orgIdstring (uuid)required

Query parameters

  • datestringrequired
  • timezonestringrequired
  • countinteger
  • platformstring

Responses

200
  • dataobjectrequired
    Fields
    • suggestionsarray<object>required
      Item fields
      • localTimestringrequired
      • reasonstringrequired
Request
curl -X GET "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/scheduler/suggested-times?date=string&timezone=string" \
  -H "Authorization: Bearer $ADVENTURAI_TOKEN"