Per-Workspace Dashboard A ranked, paginated feed of actionable cards for each workspace member — mentions, file activity, and pending signatures — with an optional AI overlay.

The Dashboard assembles a single, ranked, paginated list of actionable cards for the calling workspace member. Cards are drawn from deterministic sources (@mentions, file activity, and pending signatures) and ordered by urgency, due date, and type. On workspaces whose plan includes AI features, an AI-generated summary, urgency score, and suggested action may be layered on top of each card, and cross-item synthesis cards may appear at the end of the feed.

The dashboard is per-workspace and per-member. A member sees only the cards relevant to them in that workspace. Dismiss and snooze operations are also per-member and out-of-band — they hide a card from the member's view without changing the underlying signature or activity item.

Endpoint Summary

Card Schema

Every card in the cards array has the following shape. Fields that are AI-only are null when no AI overlay is available for the workspace.

Card Types & Sources

Card type values

Cards are ranked in this priority order: actionable cards first (signatures and mentions always rank above passive file activity, regardless of recency), then within a tier by blocking, then by due_at ascending (nulls last), then by urgency descending (nulls last), then by created_at descending, then by type weight in the order listed above.

Card source values

AI Overlay

On workspaces whose plan includes AI features, the dashboard may carry an AI overlay. The overlay is computed asynchronously in the background and merged onto the deterministic card feed on each read.

• Additive only. The AI overlay can enrich existing cards with ai_summary, urgency, and suggested_action, and append synthesis cards at the end of the feed. It cannot fabricate new non-synthesis cards, change a card's target, or cause cards to appear that do not belong to the calling member.
• Graceful degradation. When no overlay is available (AI not entitled on the plan, overlay not yet computed, or overlay stale relative to the current card set), the feed is served with purely deterministic cards. ai_summary, urgency, and suggested_action are null; no synthesis cards appear.
• Compute-on-open. The first time a member opens their dashboard, and periodically when the overlay grows stale, a background refresh is triggered automatically. Rapid successive opens are coalesced — the refresh fires at most once per debounce window.
• Urgency range. When set, urgency is an integer in 0–100. A present 0 means evaluated and not urgent; null means not yet evaluated. Higher is more urgent. AI urgency participates in card ranking.

Ripley Agent Seed (ripley_seed)

Every card carries a ripley_seed object that pre-populates a Ripley Agent conversation focused on the card's subject matter. Pass this seed to the AI agent when the member selects a "Ask Ripley" affordance on a card.

Shape

{
  "question": "Help me review and act on the signature request \"Q4 Contractor Agreement\".",
  "subjects": [
    {
      "type": "signature",
      "id": "5556667778889990001",
      "display_text": "Q4 Contractor Agreement"
    }
  ]
}

Subject type values

Pagination

The dashboard uses offset-based pagination. Default page size is 50; maximum is 200.

Read side effect (billing): by default a read may enqueue an AI refresh of the overlay, billed to the workspace's organization as AI usage, when the plan includes AI features, the token has full access, the stored overlay is absent, older than the freshness window, or no longer matches the current card set, and no refresh was requested in the last couple of minutes. A still-compatible stored overlay is returned while the refresh runs. Pass refresh=false to guarantee a read never triggers that spend.

The response includes a standard pagination envelope (total, limit, offset, has_more) plus dismissed_recent_count — the number of cards the caller has dismissed or snoozed in the trailing 24 hours.

Get Dashboard

Auth: JWT required. Workspace membership (View or above) required.

Path Parameters

Query Parameters

Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/dashboard/?limit=25" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "cards": [
    {
      "card_key": "sign_envelope:5556667778889990001",
      "type": "signature",
      "source": "signature",
      "actor": {
        "id": null,
        "display_name": "Alice Johnson"
      },
      "target": {
        "kind": "sign_envelope",
        "id": "5556667778889990001",
        "name": "Contractor Agreement",
        "deep_link": null
      },
      "summary": "You are a pending signer on Contractor Agreement.",
      "summary_segments": null,
      "ai_summary": null,
      "urgency": null,
      "suggested_action": null,
      "primary_action": {
        "kind": "sign",
        "method": "POST",
        "endpoint": "/current/workspace/1234567890123456789/sign_envelopes/5556667778889990001/my_sign_link/",
        "payload_template": {}
      },
      "ripley_seed": {
        "question": "Help me review and act on the signature request \"Contractor Agreement\".",
        "subjects": [
          {
            "type": "signature",
            "id": "5556667778889990001",
            "display_text": "Contractor Agreement"
          }
        ]
      },
      "blocking": true,
      "due_at": null,
      "created_at": "2026-06-15 14:00:00 UTC",
      "dismissible": true,
      "event_count": null,
      "actor_count": null
    }
  ],
  "pagination": {
    "total": 7,
    "limit": 25,
    "offset": 0,
    "has_more": false
  },
  "dismissed_recent_count": 2,
  "ai_overlay": {
    "generated_at": "2026-09-02 13:05:41 UTC",
    "stale": false,
    "refresh_requested": false
  }
}

Response Fields

Error Responses

Dismiss or Snooze a Card

Auth: JWT required. Workspace membership (View or above) required.

URL-encode {card_key}. Card keys contain : (e.g. sign_envelope:1234567890123456789) and must be percent-encoded in the URL path: sign_envelope%3A1234567890123456789.

Path Parameters

Request Body (optional, application/json)

Examples

# Permanent dismiss
curl -X POST \
  "https://api.fast.io/current/workspace/1234567890123456789/dashboard/cards/sign_envelope%3A9876543210987654321/dismiss/" \
  -H "Authorization: Bearer {jwt_token}"

# Snooze until tomorrow
curl -X POST \
  "https://api.fast.io/current/workspace/1234567890123456789/dashboard/cards/sign_envelope%3A9876543210987654321/dismiss/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"snooze_until": "2026-06-18 09:00:00 UTC"}'

Response (200 OK)

{
  "result": true,
  "card_dismiss": {
    "card_key": "sign_envelope:9876543210987654321",
    "dismissed": true,
    "snooze_until": null
  }
}

// Snooze response
{
  "result": true,
  "card_dismiss": {
    "card_key": "sign_envelope:9876543210987654321",
    "dismissed": true,
    "snooze_until": "2026-06-18 09:00:00 UTC"
  }
}

Response Fields

Error Responses

All input-validation failures share the category label (Invalid Input) and HTTP 406; the distinct error.code identifies the exact cause. Auth failures mirror the dashboard read endpoint (10011 / 10545 / 10581) — and as there, 10545 is 401 for a membership failure but 403 when the token’s scope does not cover the workspace’s parent org.

Undismiss a Card

Auth: JWT required. Workspace membership (View or above) required.

Path Parameters

Example

curl -X DELETE \
  "https://api.fast.io/current/workspace/1234567890123456789/dashboard/cards/sign_envelope%3A9876543210987654321/dismiss/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "card_dismiss": {
    "card_key": "sign_envelope:9876543210987654321",
    "dismissed": false,
    "snooze_until": null
  }
}

Error Responses

Get Signing Link for a Signature Card

Auth: JWT required. Workspace membership required. A write-capable token is required (read-only scoped tokens cannot mint signing links).

Method note: This is a POST because minting a signing link is a state-changing operation — it reserves a per-user throttle slot for the envelope. An empty request body is expected.

Path Parameters

Example

curl -X POST \
  "https://api.fast.io/current/workspace/1234567890123456789/sign_envelopes/5556667778889990001/my_sign_link/" \
  -H "Authorization: Bearer {jwt_token}"

Response — Actionable (200 OK)

Caller is an active pending signer and their routing slot is open. A signing URL is returned.

{
  "result": true,
  "sign_url": "https://sign.fast.io/s/eyJhb...",
  "recipient_status": "sent",
  "auth_method": "email_link",
  "routing_order": 1,
  "blocked_signers": [],
  "is_terminal": false
}

Response — Blocked (200 OK)

Caller's routing slot has not yet been reached (an earlier signer in the routing order has not yet signed). No signing URL is returned. blocked_signers lists the downstream signers still waiting on the caller (those whose routing_order is strictly greater than the caller's).

{
  "result": true,
  "sign_url": null,
  "recipient_status": "pending",
  "auth_method": "email_link",
  "routing_order": 2,
  "blocked_signers": [
    { "display_name": "Alice Johnson", "routing_order": 3 }
  ],
  "is_terminal": false
}

Response — Terminal (200 OK)

The envelope is in a terminal state (completed, declined, voided, expired). Nothing to sign.

{
  "result": true,
  "sign_url": null,
  "recipient_status": null,
  "auth_method": null,
  "routing_order": null,
  "blocked_signers": [],
  "is_terminal": true
}

Response — Re-auth Required (200 OK)

The caller already has an in-progress signing session or has already authenticated via OTP. The caller should continue from their existing session rather than starting a new one.

{
  "result": true,
  "sign_url": null,
  "recipient_status": "authenticated",
  "auth_method": "email_otp",
  "routing_order": 1,
  "blocked_signers": [],
  "is_terminal": false,
  "reauth_required": true
}

Response Fields

Error Responses