Activity Sharing

Share activities with other PushWard users via time-limited share codes or pattern-based sharing. Shared users receive push notifications for the activity on their own devices.

How It Works

Activity sharing lets an activity owner generate a share code — an 8-character alphanumeric code that another user can redeem to join the activity. Shared users see the activity in their activity list and receive all push notifications (start, update, end) on their devices.

Role	Permissions
`viewer`	Receives push notifications. Can view the activity.
`editor`	Everything a viewer can do, plus update the activity via `PATCH /activity/{slug}`.

ℹ Info

Sharing requires an active subscription for both the owner (to create share codes) and the joining user (to join).

💡 Tip

When a user joins a shared activity, the owner receives a push notification letting them know someone has joined.

PushWard supports two sharing modes:

Single-activity sharing -- share a specific activity via a share code
Pattern-based sharing -- share all activities matching a slug pattern (e.g. argocd-*), including future activities that match

Create Share Code

POST /activities/{slug}/share

Generate a share code for an activity you own.

Request Body

Field	Type	Default	Description
`role`	string	`viewer`	`"viewer"` or `"editor"`
`max_uses`	integer	`1`	How many users can redeem this code (minimum 1)
`expires_in`	integer	`86400`	Seconds until the code expires (60 to 604800 — 1 minute to 7 days)

Example

curl -X POST https://api.pushward.app/activities/dishwasher/share \
  -H "Authorization: Bearer hla_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "viewer",
    "max_uses": 1,
    "expires_in": 86400
  }'

Response (201):

{
  "id": "a1b2c3d4-...",
  "code": "ABCD1234",
  "share_url": "https://pushward.app/share/ABCD1234",
  "role": "viewer",
  "max_uses": 1,
  "use_count": 0,
  "expires_at": "2026-03-08T12:00:00Z",
  "created_at": "2026-03-07T12:00:00Z"
}

💡 Tip

The share_url is a universal link. On iOS, tapping it opens the PushWard app and automatically joins the activity.

Join a Shared Activity

POST /shares/join

Redeem a share code to join an activity. Your devices are automatically subscribed.

Example

curl -X POST https://api.pushward.app/shares/join \
  -H "Authorization: Bearer hla_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "ABCD1234"}'

Response (200):

{
  "id": 1,
  "activity_slug": "dishwasher",
  "activity_name": "Dishwasher",
  "role": "viewer",
  "owner_nickname": "Alice",
  "created_at": "2026-03-07T12:30:00Z"
}

Errors

Status	Meaning
`404`	Code not found or expired
`400`	Cannot join your own activity
`410`	Code has reached its maximum uses

List Shared With Me

GET /shares

List all activities that have been shared with you.

Example

curl https://api.pushward.app/shares \
  -H "Authorization: Bearer hla_YOUR_TOKEN"

Response (200):

[
  {
    "id": 1,
    "activity_slug": "dishwasher",
    "activity_name": "Dishwasher",
    "role": "viewer",
    "owner_nickname": "Alice",
    "created_at": "2026-03-07T12:30:00Z"
  }
]

List Share Codes

GET /activities/{slug}/share

List active share codes for an activity you own.

Example

curl https://api.pushward.app/activities/dishwasher/share \
  -H "Authorization: Bearer hla_YOUR_TOKEN"

List Shared Users

GET /activities/{slug}/shares

List all users who have access to your activity.

Example

curl https://api.pushward.app/activities/dishwasher/shares \
  -H "Authorization: Bearer hla_YOUR_TOKEN"

Response (200):

[
  {
    "id": 1,
    "shared_user_id": "b2c3d4e5-...",
    "shared_user_nickname": "Bob",
    "role": "viewer",
    "created_at": "2026-03-07T12:30:00Z"
  }
]

Update Shared User Role

PATCH /activities/{slug}/shares/{userID}

Change a shared user's role.

Example

curl -X PATCH https://api.pushward.app/activities/dishwasher/shares/b2c3d4e5-... \
  -H "Authorization: Bearer hla_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "editor"}'

Response: 204 No Content

Revoke Shared Access

DELETE /activities/{slug}/shares/{userID}

Remove a user's access to your activity. Their push-update tokens for this activity are also cleared.

Example

curl -X DELETE https://api.pushward.app/activities/dishwasher/shares/b2c3d4e5-... \
  -H "Authorization: Bearer hla_YOUR_TOKEN"

Response: 204 No Content

Delete Share Code

DELETE /activities/{slug}/share/{codeID}

Delete an active share code so it can no longer be redeemed.

Example

curl -X DELETE https://api.pushward.app/activities/dishwasher/share/a1b2c3d4-... \
  -H "Authorization: Bearer hla_YOUR_TOKEN"

Response: 204 No Content

Pattern-Based Sharing

Pattern-based sharing lets you share all activities matching a slug pattern with another user. When a user joins a pattern share, they automatically get access to all current and future activities that match the pattern.

ℹ Info

Patterns use a trailing * for prefix matching. For example, argocd-* matches argocd-sync, argocd-deploy, and any other activity with a slug starting with argocd-.

Create Pattern Share Code

POST /shares/patterns

Generate a share code for a slug pattern. Other users can redeem the code to join all matching activities.

Request Body

Field	Type	Default	Description
`slug_pattern`	string	--	Required. Pattern ending with `` (e.g. `argocd-`)
`role`	string	`viewer`	`"viewer"` or `"editor"`
`max_uses`	integer	`1`	How many users can redeem this code
`expires_in`	integer	`86400`	Seconds until the code expires (60 to 604800)

Example

curl -X POST https://api.pushward.app/shares/patterns \
  -H "Authorization: Bearer hla_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug_pattern": "argocd-*",
    "role": "viewer",
    "max_uses": 3,
    "expires_in": 86400
  }'

Response (201):

{
  "id": "a1b2c3d4-...",
  "code": "WXYZ5678",
  "share_url": "https://pushward.app/share/WXYZ5678",
  "role": "viewer",
  "slug_pattern": "argocd-*",
  "max_uses": 3,
  "use_count": 0,
  "expires_at": "2026-03-25T12:00:00Z",
  "created_at": "2026-03-24T12:00:00Z"
}

💡 Tip

Joining a pattern share code uses the same POST /shares/join endpoint. The server automatically detects whether the code is for a single activity or a pattern.

List Pattern Share Codes

GET /shares/patterns/codes

List all active pattern share codes you've created.

Example

curl https://api.pushward.app/shares/patterns/codes \
  -H "Authorization: Bearer hla_YOUR_TOKEN"

Response (200):

[
  {
    "id": "a1b2c3d4-...",
    "code": "WXYZ5678",
    "share_url": "https://pushward.app/share/WXYZ5678",
    "role": "viewer",
    "slug_pattern": "argocd-*",
    "max_uses": 3,
    "use_count": 1,
    "expires_at": "2026-03-25T12:00:00Z",
    "created_at": "2026-03-24T12:00:00Z"
  }
]

Delete Pattern Share Code

DELETE /shares/patterns/codes/{codeID}

Delete a pattern share code so it can no longer be redeemed.

Example

curl -X DELETE https://api.pushward.app/shares/patterns/codes/a1b2c3d4-... \
  -H "Authorization: Bearer hla_YOUR_TOKEN"

Response: 204 No Content

List Owned Pattern Shares

GET /shares/patterns/owned

List all pattern shares you own -- users who have joined your pattern share codes.

Example

curl https://api.pushward.app/shares/patterns/owned \
  -H "Authorization: Bearer hla_YOUR_TOKEN"

Response (200):

[
  {
    "id": 1,
    "slug_pattern": "argocd-*",
    "shared_user_id": "b2c3d4e5-...",
    "shared_user_nickname": "Bob",
    "role": "viewer",
    "matched_count": 4,
    "created_at": "2026-03-24T12:30:00Z"
  }
]

Delete Pattern Share

DELETE /shares/patterns/{id}

Remove a user's pattern-based access. They will lose access to all activities they gained through this pattern share.

Example

curl -X DELETE https://api.pushward.app/shares/patterns/1 \
  -H "Authorization: Bearer hla_YOUR_TOKEN"

Response: 204 No Content

Leave Pattern Share

POST /shares/patterns/{id}/leave

Leave a pattern share that was shared with you. You will lose access to all activities gained through this pattern.

Example

curl -X POST https://api.pushward.app/shares/patterns/1/leave \
  -H "Authorization: Bearer hla_YOUR_TOKEN"

Response: 204 No Content