Skip to content
PostyAPIv0.3.81
Menu

API reference

Today

Get today

get/v1/today

Get the signed-in user's Today snapshot for the workspace: ranked blockers, decisions, next actions, progress and insights, plus what resolved since yesterday. Items are filtered to the caller's own permissions. Needs an OAuth user; API keys are rejected because Today is personal.

Response 200

Today snapshot

  • workspaceIdstringrequired
  • asOfstring (date-time)required
  • projectionRevisionintegerrequired
  • summaryobjectrequired
    Child attributes
    • blockersintegerrequired
    • decisionsintegerrequired
    • actionsintegerrequired
    • updatesintegerrequired
    • insightsintegerrequired
  • sectionsobjectrequired
    Child attributes
  • sinceYesterdayobjectrequired
    Child attributes
    • countintegerrequired
    • itemsarray of objectrequired
      Child attributes
      • idstringrequired
      • kindstringrequired

        One ofblockerdecisionactionupdateinsightcelebration

      • presentationTodayPresentationrequired
      • resolvedAtstring (date-time)required

Errors

401
Unauthenticated
403
API key callers (Today needs a signed-in user), or missing permission
Request
curl "https://api.posty.social/v1/today" \
  -H "Authorization: Bearer $POSTY_API_KEY"
Response 200
{
  "workspaceId": "string",
  "asOf": "2026-01-15T09:30:00.000Z",
  "projectionRevision": 1,
  "summary": {
    "blockers": 1,
    "decisions": 1,
    "actions": 1,
    "updates": 1,
    "insights": 1
  },
  "sections": {
    "urgent": [
      {
        "id": "string",
        "recipeKey": "string",
        "targetKind": "user",
        "kind": "blocker",
        "severity": "critical",
        "priorityBucket": 1,
        "presentationKind": "setup_action",
        "presentation": {
          "eyebrow": "string",
          "title": "string",
          "summary": "string",
          "detail": "string",
          "primaryAction": {
            "type": "navigate",
            "label": null,
            "action": null,
            "params": null
          }
        },
        "channels": [
          {
            "id": null,
            "name": null,
            "avatarUrl": null,
            "platform": "bluesky"
          }
        ],
        "occurredAt": "2026-01-15T09:30:00.000Z",
        "dueAt": "2026-01-15T09:30:00.000Z",
        "canDismiss": true
      }
    ],
    "next": [
      {
        "id": "string",
        "recipeKey": "string",
        "targetKind": "user",
        "kind": "blocker",
        "severity": "critical",
        "priorityBucket": 1,
        "presentationKind": "setup_action",
        "presentation": {
          "eyebrow": "string",
          "title": "string",
          "summary": "string",
          "detail": "string",
          "primaryAction": {
            "type": "navigate",
            "label": null,
            "action": null,
            "params": null
          }
        },
        "channels": [
          {
            "id": null,
            "name": null,
            "avatarUrl": null,
            "platform": "bluesky"
          }
        ],
        "occurredAt": "2026-01-15T09:30:00.000Z",
        "dueAt": "2026-01-15T09:30:00.000Z",
        "canDismiss": true
      }
    ],
    "progress": [
      {
        "id": "string",
        "recipeKey": "string",
        "targetKind": "user",
        "kind": "blocker",
        "severity": "critical",
        "priorityBucket": 1,
        "presentationKind": "setup_action",
        "presentation": {
          "eyebrow": "string",
          "title": "string",
          "summary": "string",
          "detail": "string",
          "primaryAction": {
            "type": "navigate",
            "label": null,
            "action": null,
            "params": null
          }
        },
        "channels": [
          {
            "id": null,
            "name": null,
            "avatarUrl": null,
            "platform": "bluesky"
          }
        ],
        "occurredAt": "2026-01-15T09:30:00.000Z",
        "dueAt": "2026-01-15T09:30:00.000Z",
        "canDismiss": true
      }
    ],
    "insights": [
      {
        "id": "string",
        "recipeKey": "string",
        "targetKind": "user",
        "kind": "blocker",
        "severity": "critical",
        "priorityBucket": 1,
        "presentationKind": "setup_action",
        "presentation": {
          "eyebrow": "string",
          "title": "string",
          "summary": "string",
          "detail": "string",
          "primaryAction": {
            "type": "navigate",
            "label": null,
            "action": null,
            "params": null
          }
        },
        "channels": [
          {
            "id": null,
            "name": null,
            "avatarUrl": null,
            "platform": "bluesky"
          }
        ],
        "occurredAt": "2026-01-15T09:30:00.000Z",
        "dueAt": "2026-01-15T09:30:00.000Z",
        "canDismiss": true
      }
    ]
  },
  "sinceYesterday": {
    "count": 1,
    "items": [
      {
        "id": "string",
        "kind": "blocker",
        "presentation": {
          "eyebrow": "string",
          "title": "string",
          "summary": "string",
          "detail": "string",
          "primaryAction": {
            "type": "navigate",
            "label": null,
            "action": null,
            "params": null
          }
        },
        "resolvedAt": "2026-01-15T09:30:00.000Z"
      }
    ]
  }
}

Dismiss today item

post/v1/today/items/{id}/dismiss

Dismiss an open Today item by ID for everyone in the selected workspace and archive its associated user notifications. Updates shared Posty state and notifies connected workspace clients. Only items whose canDismiss is true can be dismissed. Requires an OAuth user with workspace:update. Returns the item ID, status and projection revision. restore_today_item can reopen it while the underlying condition still holds.

Path parameters

  • idstringrequired

Response 200

Item dismissed

  • itemIdstringrequired
  • statusstringrequired

    One ofopenresolveddismissedexpired

  • projectionRevisionintegerrequired

Errors

400
Invalid request
401
Unauthenticated
403
API key callers (Today needs a signed-in user), or missing permission
404
Today item not found in this workspace
409
The item or settings changed since they were read
Request
curl -X POST "https://api.posty.social/v1/today/items/$ID/dismiss" \
  -H "Authorization: Bearer $POSTY_API_KEY"
Response 200
{
  "itemId": "string",
  "status": "open",
  "projectionRevision": 1
}

Restore today item

post/v1/today/items/{id}/restore

Restore a dismissed Today item by ID so it appears again for everyone in the selected workspace. Changes shared Posty state from dismissed to open and notifies connected workspace clients. Returns the item ID, status and projection revision. Fails with 409 if the item is not dismissed or its underlying condition is no longer active. Requires an OAuth user with workspace:update.

Path parameters

  • idstringrequired

Response 200

Item restored

  • itemIdstringrequired
  • statusstringrequired

    One ofopenresolveddismissedexpired

  • projectionRevisionintegerrequired

Errors

400
Invalid request
401
Unauthenticated
403
API key callers (Today needs a signed-in user), or missing permission
404
Today item not found in this workspace
409
The item or settings changed since they were read
Request
curl -X POST "https://api.posty.social/v1/today/items/$ID/restore" \
  -H "Authorization: Bearer $POSTY_API_KEY"
Response 200
{
  "itemId": "string",
  "status": "open",
  "projectionRevision": 1
}

Get today settings

get/v1/today/settings

Get the workspace's Today rules: each configurable recipe's setting definitions, effective values, where each value comes from, and the workspace override with its revision. Needs an OAuth user who is a workspace member.

Response 200

Today settings

  • workspaceIdstringrequired
  • workspaceSettingsRevisionintegerrequired
  • recipesarray of TodayRecipeSettingsrequired

Errors

401
Unauthenticated
403
API key callers (Today needs a signed-in user), or missing permission
Request
curl "https://api.posty.social/v1/today/settings" \
  -H "Authorization: Bearer $POSTY_API_KEY"
Response 200
{
  "workspaceId": "string",
  "workspaceSettingsRevision": 1,
  "recipes": [
    {
      "recipeKey": "string",
      "recipeVersion": 1,
      "settingsSchemaVersion": 1,
      "definitions": {
        "key": {
          "configurableAt": [
            "organization"
          ],
          "defaultValue": "string",
          "description": "string",
          "kind": "boolean",
          "label": "string",
          "maximum": 1,
          "minimum": 1,
          "unit": "days"
        }
      },
      "effective": {
        "key": "string"
      },
      "sources": {
        "key": "code"
      },
      "workspaceOverride": {
        "key": "string"
      },
      "overrideRevision": 1
    }
  ]
}

Update today settings

put/v1/today/settings/{recipeKey}

Replace the workspace override for one Today recipe (for example workspace.content_gap). Send the overrideRevision from get_today_settings as expectedRevision (null when there is no override yet); an empty configuration resets to inherited values. Needs an OAuth user holding workspace:update.

Path parameters

  • recipeKeystringrequired

    Pattern ^workspace\.[a-z][a-z0-9_]*$

Request body

  • configurationmap of string or number or booleanrequired
  • expectedRevisionintegerrequirednullable

    Min 0

Response 200

Settings saved

  • changedbooleanrequired
  • recipeKeystringrequired
  • overrideRevisionintegerrequirednullable
  • workspaceSettingsRevisionintegerrequired
  • projectionRevisionintegerrequirednullable

Errors

400
Invalid request
401
Unauthenticated
403
API key callers (Today needs a signed-in user), or missing permission
404
Today item not found in this workspace
409
The item or settings changed since they were read
Request
curl -X PUT "https://api.posty.social/v1/today/settings/$RECIPE_KEY" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "configuration": {
    "key": "string"
  },
  "expectedRevision": 1
}'
Response 200
{
  "changed": true,
  "recipeKey": "string",
  "overrideRevision": 1,
  "workspaceSettingsRevision": 1,
  "projectionRevision": 1
}

Models

Objects referenced by the endpoints above.

TodayAction

  • typestringrequired

    One ofnavigate

  • labelstringrequired
  • actionstringrequired
  • paramsmap of string

TodayItem

  • idstringrequired
  • recipeKeystringrequired
  • targetKindstringrequired

    One ofuserworkspace_permissionorg_permission

  • kindstringrequired

    One ofblockerdecisionactionupdateinsightcelebration

  • severitystringrequired

    One ofcriticalhighnormallow

  • priorityBucketintegerrequired
  • presentationKindstringrequired

    One ofsetup_actiontaskdecisionriskprogress_updatecelebrationmetric_insightworkspace_group

  • presentationTodayPresentationrequired
  • channelsarray of objectrequired
    Child attributes
    • idstringrequired
    • namestringrequired
    • avatarUrlstringrequirednullable
    • platformstringrequired

      One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube

  • occurredAtstring (date-time)required
  • dueAtstring (date-time)requirednullable
  • canDismissbooleanrequired

TodayPresentation

  • eyebrowstring
  • titlestringrequired
  • summarystring
  • detailstring
  • primaryActionTodayAction

TodayRecipeSettings

  • recipeKeystringrequired
  • recipeVersionintegerrequired
  • settingsSchemaVersionintegerrequired
  • definitionsmap of objectrequired
    Child attributes
    • configurableAtarray of stringrequired

      One oforganizationworkspace

    • defaultValuestring or number or booleanrequired
    • descriptionstringrequirednullable
    • kindstringrequired

      One ofbooleandurationnumberpercentage

    • labelstringrequired
    • maximumnumberrequirednullable
    • minimumnumberrequirednullable
    • unitstringrequirednullable

      One ofdayshourspercent

  • effectivemap of string or number or booleanrequired
  • sourcesmap of stringrequired
  • workspaceOverridemap of string or number or booleanrequired
  • overrideRevisionintegerrequirednullable