feed:query

Description: Retrieve a chronological activity feed for a community, showing what has happened over a given time period.

This endpoint returns a paginated list of account activities (create, update, delete, archive events) with human-readable descriptions, expanded trackable objects, and actor information. It’s designed to give external LLM agents a single-call digest of community activity.

---

Request Schema

{
  "payload": {
    "type": "feed:query",
    "q": {
      "since": "2025-05-01T00:00:00Z",
      "until": "2025-05-13T23:59:59Z",
      "trackable_type": "Person",
      "page": 1,
      "per_page": 20
    }
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

• See global request attributes

Attribute	Type	Required	Default	Description
q.since	String	No	null	Only include activities created at or after this ISO 8601 timestamp
q.until	String	No	null	Only include activities created at or before this ISO 8601 timestamp
q.trackable_type	String	No	null	Filter by trackable class name (e.g., “Person”, “Activity”, “Todo”)
q.page	Integer	No	1	Page number for pagination
q.per_page	Integer	No	20	Items per page (max 50)

Additional ransack filters are supported (e.g., key_cont, trackable_name_cont).

Authentication Behavior

This endpoint follows Pattern A: Full Account Access.

All authentication methods see the same data — no person filtering is applied.

Response Schema

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-05-13T14:30:00Z",
  "signature": "8b6392d5550605bd6ccddf9c21ebec470de4b44e4b4deb746076e37ab61c5346e07e7c7c7cebb5bbee41cdd92a476bcd3f02373d146ec165b31c31fc31c9ce0d",
  "payload": {
    "type": "feed:query",
    "q": {
      "per_page": 20,
      "page": 1,
      "total": 147,
      "since": "2025-05-01T00:00:00Z",
      "until": "2025-05-13T23:59:59Z",
      "trackable_type": "Person"
    },
    "resources": [
      {
        "id": 123,
        "key": "person.create",
        "description": "La personne John Doe a été créée par Jane Admin",
        "action": "create",
        "trackable": {
          "type": "Person",
          "id": 456,
          "name": "John Doe"
        },
        "actor": {
          "type": "Person",
          "id": 789,
          "name": "Jane Admin"
        },
        "created_at": "2025-05-13T12:00:00Z"
      },
      {
        "id": 124,
        "key": "activity.archive",
        "description": "Événement - Weekly Production Planning Session 1 à propos de Toucan Solutions a été archivée par Toucan",
        "action": "archive",
        "trackable": {
          "type": "Activity",
          "id": 457,
          "name": "Événement - Weekly Production Planning Session 1"
        },
        "actor": {
          "type": "Person",
          "id": 790,
          "name": "Toucan"
        },
        "created_at": "2025-05-13T11:30:00Z"
      }
    ]
  }
}

Response Attributes

• payload.q - Object - Query metadata including pagination info and echoed filter params
  • per_page - Integer - Items per page
  • page - Integer - Current page number
  • total - Integer - Total number of matching activities
  • since - String - Echoed since parameter (if provided)
  • until - String - Echoed until parameter (if provided)
  • trackable_type - String - Echoed trackable_type parameter (if provided)
• payload.resources - Array of activity objects:

Activity Object

Field	Type	Description
id	Integer	Unique identifier for the account activity
key	String	Activity key in format {resource}.{action} (e.g., person.create)
description	String	Human-readable localized description (HTML stripped)
action	String	Action extracted from key (e.g., create, update, archive)
trackable	Object	The object that was acted upon (null if discarded)
actor	Object	The person or user who performed the action
created_at	String	ISO 8601 timestamp when the activity occurred

Trackable Object

Field	Type	Description
type	String	Class name (e.g., “Person”, “Activity”)
id	Integer	Trackable ID
name	String	Display name of the trackable

Actor Object

Field	Type	Description
type	String	Class name (e.g., “Person”, “User”)
id	Integer	Actor ID
name	String	Display name of the actor

Error Responses

When an invalid query parameter is provided:

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-05-13T14:30:00Z",
  "signature": "...",
  "payload": {
    "type": "feed:query",
    "q": { "since": "invalid-date" }
  },
  "error": "Error message",
  "status": "bad_request"
}

Real Life Examples

Get recent activity for all types

{
  "payload": {
    "type": "feed:query",
    "q": {
      "since": "2025-05-01T00:00:00Z",
      "per_page": 10,
      "page": 1
    }
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

Get person activity only

{
  "payload": {
    "type": "feed:query",
    "q": {
      "trackable_type": "Person",
      "per_page": 20,
      "page": 1
    }
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

Get activity for a specific date range

{
  "payload": {
    "type": "feed:query",
    "q": {
      "since": "2025-05-01T00:00:00Z",
      "until": "2025-05-07T23:59:59Z",
      "per_page": 50,
      "page": 1
    }
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

---

Usage Notes

• This is an ephemeral query - no message is persisted to the database
• Activities are ordered by created_at DESC (newest first)
• The description field is localized based on the community’s default locale (French by default)
• The key field is provided so clients can localize descriptions themselves if needed
• When a trackable has been soft-deleted (discarded), trackable will be null but the description still includes the name
• Authentication can be via token, whitelist, or membership
• All activities in the account are accessible regardless of authentication method