Activity Groups

Activity Groups organise related measurable activity around a campaign, event, project, content programme or always-on initiative.

A publishing or automation workflow can:

• resolve an Activity Group by public ID or slug
• create a link inside that Activity Group
• move or reconcile an existing link into that Activity Group
• confirm the assignment in the link response
• use the Activity Group default UTM campaign when no explicit campaign is supplied

Activity Group creation, editing and archiving are managed in the Bytes app. The public Developer API provides read-only lookup and link assignment.

List Activity Groups

GET /api/v1/activity-groups

curl "https://api.jaww.ws/api/v1/activity-groups?slug=blog" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_BYTES_API_KEY"

Supported filters:

Parameter	Type	Notes
id	string	Immutable 26-character public Activity Group ID
slug	string	Workspace Activity Group slug, such as blog
q	string	Search name, slug and description
type	string	campaign, always_on, project, event, content or other
status	string	draft, scheduled, active, completed or archived
page	integer	Page number, starting at 1
per_page	integer	Between 1 and 100

Example response:

{
  "workspace": {
    "name": "Jawwws",
    "slug": "jawwws"
  },
  "activity_groups": [
    {
      "id": "01KYNVZSNW6Y56W2SHB4ZZ9QKE",
      "name": "Blog",
      "slug": "blog",
      "type": "content",
      "description": "Jawwws blog publishing and distribution activity.",
      "status": "active",
      "default_utm_campaign": "jawwws-blog",
      "starts_at": null,
      "ends_at": null,
      "archived_at": null
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 1
  }
}

An unknown slug or public ID returns an empty result rather than exposing whether a matching group exists in another workspace.

Assign a new link

Despite the field name, activity_group_id accepts either the public Activity Group ID or its slug.

curl -X POST https://api.jaww.ws/api/v1/links \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_BYTES_API_KEY" \
  -d '{
    "destination_url": "https://jawwws.com/blog/example",
    "slug": "jawwws-blog-example",
    "title": "Example Jawwws article",
    "channel": "social",
    "activity_group_id": "blog",
    "utm_source": "jawwws",
    "utm_medium": "blog"
  }'

The response confirms the primary assignment:

{
  "message": "Short link created successfully.",
  "link": {
    "id": "01K0M4ZN8X7P9Q2R3S4T5V6W7X",
    "slug": "jawwws-blog-example",
    "short_url": "https://jaww.ws/jawwws-blog-example",
    "destination_url": "https://jawwws.com/blog/example",
    "utm_campaign": "jawwws-blog",
    "activity_group": {
      "id": "01KYNVZSNW6Y56W2SHB4ZZ9QKE",
      "name": "Blog",
      "slug": "blog",
      "type": "content",
      "status": "active",
      "assignment": {
        "role": "primary",
        "channel": "social"
      }
    }
  }
}

UTM fallback and precedence

When an Activity Group has default_utm_campaign:

• omitting utm_campaign uses the group default
• supplying utm_campaign uses the explicit request value
• assigning a group does not overwrite an explicit campaign value

Reconcile an existing link

curl -X PATCH \
  "https://api.jaww.ws/api/v1/links/01K0M4ZN8X7P9Q2R3S4T5V6W7X" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_BYTES_API_KEY" \
  -d '{
    "activity_group_id": "blog",
    "channel": "email"
  }'

Bytes reconciles the primary assignment. Repeating the same request does not create duplicate active Activity Group items.

Workspace isolation

A workspace API key can only list and assign Activity Groups from its own workspace.

Unknown or cross-workspace assignments return:

422 Unprocessable Content

{
  "message": "Activity Group was not found in this workspace.",
  "errors": {
    "activity_group_id": [
      "Activity Group was not found in this workspace."
    ]
  }
}

Secure server-side automation

Use API keys only in trusted server-side code, deployment workflows or private automation runners.

Do not expose a key in browser JavaScript, a statically generated page, public build variables, client-side React or Vite code, logs or screenshots.

For a static website publishing workflow, call Bytes from the trusted build or deployment process. Publish only the finished https://jaww.ws/{slug} URL.

CLI equivalent

bytes activity-groups list --slug blog --json

bytes links create https://jawwws.com/blog/example \
  --slug jawwws-blog-example \
  --activity-group blog \
  --utm-source jawwws \
  --utm-medium blog

See the Bytes CLI guide.