API Documentation | Week Blast

Authentication

All API endpoints require authentication. The recommended approach for programmatic access is an API key.

API Key (recommended)

Generate a key from your Settings page, then pass it in the X-API-Key header:

        # API key

        curl -H "X-API-Key: wb_..." https://weekblast.com/api/blasts

Cookie / Bearer token

Browser sessions use cookie-based auth automatically. You can also pass a Supabase JWT in the Authorization header:

        # Cookie-based (browser sessions)

        Cookie: access_token=<your-jwt>

        # Bearer token

        Authorization: Bearer <your-jwt>

Unauthenticated requests receive a 401 Unauthorized JSON response.

Base URL

https://weekblast.com/api

All endpoint paths below are relative to this base.

Blast CRUD

Create, read, update, and delete your weekly blasts.

GET /blasts AUTH List your blasts

Returns a paginated list of your blasts, newest first.

Query Parameters

Name	Type	Description
offset	int optional	Records to skip (default 0)
limit	int optional	Max records (1-100, default 20)

Example Response

{

  "data": [

    {

      "id": "uuid",

      "user_id": "uuid",

      "week_start_date": "2026-02-02",

      "content_markdown": "- Shipped new API...",

      "is_public": false,

      "counts_towards_streak": true,

      "line_count": 5,

      "word_count": 42,

      "submitted_at": null,

      "created_at": "2026-02-03T10:00:00",

      "updated_at": "2026-02-03T10:00:00"

    }

  ],

  "offset": 0,

  "limit": 20,

  "total": 1

}

GET /blasts/current AUTH Current week blast

Returns your blast for the current week (based on your timezone). Returns null if no blast exists yet.

GET /blasts/week/{week_start_date} AUTH Blast by week

Returns your blast for a specific week. The week_start_date must be a Monday in YYYY-MM-DD format.

GET /blasts/{blast_id} AUTH Get blast by ID

Fetch a single blast by UUID. Only your own blasts are accessible. Returns 403 for other users' blasts.

POST /blasts AUTH Create a blast

Create a new blast for a given week. Returns 409 Conflict if one already exists for that week.

Request Body (JSON)

Field	Type	Description
week_start_date	date required	Monday of the week (YYYY-MM-DD)
content_markdown	string required	Blast content in Markdown
is_public	bool optional	Make publicly visible (default false)

Example Request

POST /api/blasts

Content-Type: application/json

{

  "week_start_date": "2026-02-02",

  "content_markdown": "- Shipped REST API\n- Fixed 3 bugs",

  "is_public": false

}

PUT /blasts/{blast_id} AUTH Update a blast

Partial update — only send the fields you want to change. If content_markdown is set to empty or whitespace, the blast is deleted and the response is null.

Request Body (JSON)

Field	Type	Description
content_markdown	string optional	Updated content
is_public	bool optional	Updated visibility

DELETE /blasts/{blast_id} AUTH Delete a blast

Permanently delete a blast. Returns 204 No Content on success.

POST /blasts/current/append AUTH Append to current week

Append content to the current week's blast. If no blast exists yet, one is created. If a blast already exists, the new content is appended after a newline. This is a convenience endpoint so you don't have to fetch, concatenate, and update separately.

Request Body (JSON)

Field	Type	Description
content_markdown	string required	Content to append

Example Request

POST /api/blasts/current/append

Content-Type: application/json

{

  "content_markdown": "- Fixed login bug\n- Updated docs"

}

Returns the full updated (or newly created) blast.

Archived Blasts

Browse your past blasts (the Vault).

GET /blasts/archive/list AUTH List archived blasts

Returns your past blasts (before the current week), newest first. Supports date-range filtering.

Query Parameters

Name	Type	Description
offset	int optional	Records to skip (default 0)
limit	int optional	Max records (1-100, default 20)
date_from	date optional	Only blasts on or after this date
date_to	date optional	Only blasts on or before this date

Example

GET /api/blasts/archive/list?limit=10&date_from=2025-01-01

Coworker Blasts

See what your crew shipped this week.

GET /blasts/coworkers/latest AUTH Latest per coworker

Returns the most recent blast from each coworker in your organization(s). One blast per person — great for a grid/dashboard view.

Example Response

[
  {
    "id": "uuid",
    "user_id": "uuid",
    "week_start_date": "2026-02-02",
    "content_markdown": "- Redesigned dashboard...",
    "is_public": true,
    "line_count": 4,
    "word_count": 28,
    "created_at": "...",
    "updated_at": "...",
    "user_name": "Alice",
    "user_email": "[email protected]",
    "user_avatar_url": "https://..."
  }
]

GET /blasts/coworkers/feed AUTH Coworker feed

Paginated feed of all coworker blasts. Supports filtering by user, text search, and date range.

Query Parameters

Name	Type	Description
offset	int optional	Records to skip (default 0)
limit	int optional	Max records (1-100, default 20)
user_id	string optional	Filter to a specific coworker's UUID
query	string optional	Full-text search within content
date_from	date optional	Only blasts on or after this date
date_to	date optional	Only blasts on or before this date

Example

GET /api/blasts/coworkers/feed?query=shipped&limit=10

Error Handling

All errors return JSON with a detail field.

Status	Meaning	Example
`400`	Invalid request body or query params	`{"detail": "..."}`
`401`	Missing or invalid authentication	`{"detail": "Not authenticated"}`
`403`	Accessing another user's resource	`{"detail": "Not your blast"}`
`404`	Resource not found	`{"detail": "Blast not found"}`
`409`	Conflict (e.g. blast already exists for week)	`{"detail": "..."}`
`422`	Validation error (FastAPI auto-generated)	`{"detail": [...]}`