Worklynq data feed spec

1. Authentication

• Generate a long random key (32 or more characters) for each company that will connect, and give it to that company’s System Admin.
• Worklynq sends it on every request: Authorization: Bearer <key>.
• Answer 401 for a missing or wrong key. Compare keys in constant time, and store only a hash if you can.
• Serve over https, from an address reachable on the internet. Don’t redirect — Worklynq doesn’t follow redirects.

2. Manifest: GET <feed url>

The feed URL is any path you choose, for example https://app.example.com/api/worklynq. It describes your datasets:

{
  "worklynq_feed": 1,
  "app": {"name": "Corner Bakery Rewards", "url": "https://rewards.example.com"},
  "datasets": [
    {
      "id": "members",
      "label": "Loyalty members",
      "noun": "members",
      "description": "Everyone in the rewards program, with their tier and points.",
      "key": "id",
      "default_time_field": "joined_at",
      "fields": [
        {"id": "id", "type": "string"},
        {"id": "name", "label": "Name", "type": "string"},
        {"id": "tier", "label": "Tier", "type": "string", "values": ["Bronze", "Silver", "Gold"]},
        {"id": "points", "label": "Points balance", "type": "integer", "unit": "points"},
        {"id": "rewards_redeemed", "label": "Rewards redeemed", "type": "integer", "unit": "rewards"},
        {"id": "joined_at", "label": "Joined", "type": "datetime"},
        {"id": "last_visit_at", "label": "Last visit", "type": "datetime"}
      ],
      "list": {"title": "name", "subtitle": "tier"}
    }
  ]
}

For each dataset, Worklynq can show the number of records and the total and average of any number, integer, or money field — split by category fields, over time by date fields, and filtered like tier:gold points:>100.

3. Records: GET <feed url>/<dataset id>

Worklynq asks for ?limit=1000, and adds &cursor=<cursor> for the following pages:

{
  "items": [
    {"id": "m_1042", "name": "Ana P.", "tier": "Gold", "points": 920, "rewards_redeemed": 5,
     "joined_at": "2026-03-02T17:04:00Z", "last_visit_at": "2026-10-24T19:12:00Z"}
  ],
  "next_cursor": "m_1042"
}

• Return at most limit items, in any stable order (oldest first, or by id).
• next_cursor is an opaque string for the next page, or null on the last page. The first request has no cursor.
• Every item has the dataset’s fields; use null for missing values. Extra fields are ignored.
• Return current values — today’s points balance, today’s tier.
• Worklynq keeps answers for 5 minutes and reads at most 50,000 records per dataset. Each page must be under 20 MB, and answer within 15 seconds.

4. Privacy

Send only what the dashboards need. Prefer a display name or initials over full names, and leave out emails, phone numbers, and birthdays unless the company asks for them. By default, only the company’s System Admins can see the data in Worklynq.

5. Checklist

1. GET <feed url> with the key returns the manifest; without it, 401.
2. GET <feed url>/<dataset id> returns the first page, and following next_cursor reaches null.
3. The company’s System Admin opens Admin console → Connectors → Custom apps → Add custom app, enters the feed URL and key, clicks Test feed, then Add app.

Questions about the feed? info@cohesync.com