Actions API

Full REST reference for the actions domain. All routes are under /api/actions, require a Cognito JWT (Authorization: Bearer <token>), and are backed by services/backend/lambda/actions_handler.py / actions_service.py. See specs/api/actions.md in the repo for the underlying spec this page is based on, and the Actions feature guide for the product-level behavior.

Endpoints at a glance

Create

POST /api/actions

// Request
{
  "workspace_id": "ws_123",
  "title": "Create hero graphic",
  "assignee_id": "user_456",
  "description": "1200x627, brand colors",
  "linked_post_id": "post_789",
  "priority": "p2_high",
  "due_date": "2026-07-25"
}

// 201 Response
{
  "action_id": "a1b2c3d4-...",
  "workspace_id": "ws_123",
  "title": "Create hero graphic",
  "description": "1200x627, brand colors",
  "assignee_id": "user_456",
  "assignee_name": "Jane Doe",
  "assignee_response": "pending",
  "linked_post_id": "post_789",
  "status": "open",
  "priority": "p2_high",
  "due_date": "2026-07-25",
  "attachments": [],
  "created_by": "user_111",
  "created_at": "2026-07-17T12:00:00+00:00",
  "updated_at": "2026-07-17T12:00:00+00:00",
  "completed_at": null
}

workspace_id, title, and assignee_id are required (400 if missing or empty after trimming). assignee_id must already be a workspace member — there is no auto-invite from this endpoint (that flow lives in the frontend picker, which calls the workspace invite endpoint first).

Sends the "new action" Slack DM to the assignee before returning — a Slack failure fails the request even though the action was already written to DynamoDB.

List

GET /api/actions?workspaceId=ws_123&status=open&assigneeId=user_456&linkedPostId=post_789

All filter params are optional except workspaceId; all are exact-match.

// 200 Response
{ "items": [ /* action objects */ ], "count": 2 }

Get

GET /api/actions/{id}?workspaceId=ws_123

Returns the action object (same shape as Create's response).

Update

PUT /api/actions/{id}

Partial update — send only the fields you want to change, plus workspace_id (required for the membership check).

// Request — reassign and bump priority
{ "workspace_id": "ws_123", "assignee_id": "user_999", "priority": "p1_urgent" }

Reassigning (assignee_id present and different) resets assignee_response to pending, refreshes assignee_name, and sends a new "action assigned" Slack DM to the new assignee.

Update status

PUT /api/actions/{id}/status

{ "workspace_id": "ws_123", "status": "in_progress" }

status must be one of open, in_progress, completed, cancelled. Any status can transition to any other — there's no enforced workflow graph.

Setting status: "completed" additionally:

• stamps completed_at,
• emits the ActionCompleted and ActionTurnaroundSeconds metrics (turnaround = completed_at - created_at; skipped, logged, non-fatal if created_at doesn't parse),
• Slack-DMs the creator that the assignee finished the work.

Respond

PUT /api/actions/{id}/response

{ "workspace_id": "ws_123", "response": "accepted" }

Only the current assignee may call this. response must be accepted or declined. This sets assignee_response — it does not change status. Slack-DMs the creator with the outcome.

Delete

DELETE /api/actions/{id}?workspaceId=ws_123

Only the action's creator, or a caller whose JWT custom:role claim is admin, may delete.

Add attachment

POST /api/actions/{id}/attachments

// Request
{ "workspace_id": "ws_123", "filename": "hero.png", "contentType": "image/png" }

// 201 Response
{
  "uploadUrl": "https://<bucket>.s3.eu-central-1.amazonaws.com/...&X-Amz-Signature=...",
  "key": "workspaces/ws_123/actions/a1b2c3d4/hero.png",
  "expiresIn": 3600
}

filename's extension must be one of png, jpg, jpeg, svg, webp, pdf (case-insensitive). Only the basename is used in the storage key — any directory components you send are stripped server-side.

The attachment's metadata (key, filename, uploaded_at, uploaded_by) is recorded on the action immediately, before you've actually performed the PUT to uploadUrl. If your client never completes the upload, the action will still show a broken attachment entry — there is no cleanup job for abandoned presigned URLs.

List attachments

GET /api/actions/{id}/attachments?workspaceId=ws_123

// 200 Response
{
  "items": [
    {
      "key": "workspaces/ws_123/actions/a1b2c3d4/hero.png",
      "filename": "hero.png",
      "uploaded_at": "2026-07-17T12:05:00+00:00",
      "uploaded_by": "user_456",
      "downloadUrl": "https://..."
    }
  ],
  "count": 1
}

downloadUrl is generated fresh on every call (1 hour expiry) — don't cache it beyond that.

Delete attachment

DELETE /api/actions/{id}/attachments?workspaceId=ws_123&key=workspaces%2Fws_123%2Factions%2Fa1b2c3d4%2Fhero.png

Deletes the S3 object and removes the matching entry from the action's attachment list in the same call.