Media API

Endpoints for managing image and video media. Besides user uploads, thumbnail images produced by the thumbnail_generation Lambda are managed in this collection too.

Media schema

Field	Type	Notes
id	string	`_id`
name	string	Unique; also used as the S3 object key
mime_type	enum	`image` / `video`
s3_url	string	Reference URL. Read endpoints return a freshly generated presigned URL valid for one hour
size	number	Bytes
race_id	string \| null	`_id` of the linked race. Set only for race-derived media such as thumbnails; `null` for general uploads
created_at	number	UNIX timestamp (ms)
updated_at	number	UNIX timestamp (ms)

race_id cannot be set through the API

race_id is set only when the thumbnail_generation Lambda stores a thumbnail. It cannot be supplied when creating or updating media through the Media API.

POST /v1/medias

Overview

Registers new media.

Request and Response

Headers

Request Headers

Content-Type: multipart/form-data

Response Headers

Content-Type: application/json

URI

POST /v1/medias

Request Body

Send file and metadata in multipart/form-data format.

Field	Type	Required	Notes
name	string	◯	Unique
mime_type	enum	◯	`image` / `video`
file	binary	◯	File to upload

Response

201 Created

{
  "id": "string",
  "name": "string",
  "mime_type": "image",
  "s3_url": "string",
  "size": 1024,
  "race_id": null,
  "created_at": 1234567890000,
  "updated_at": 1234567890000
}

Error Handling

Description	Status Code	Status Name
Invalid request body	422	Unprocessable Entity
name already exists	409	Conflict
S3 upload failure	500	Internal Server Error
Internal server error	500	Internal Server Error

Processing Flow

Receive the request
Validate the request
Check for duplicate name
Upload the file to S3
Save the URL and file size returned from S3 to the DB
Return the created media

flowchart TD
    Start([POST /v1/medias]) --> Validate[Request validation]
    Validate -->|invalid| E422[422 Unprocessable Entity]
    Validate -->|valid| NameCheck[Check name duplicate]
    NameCheck -->|duplicate| E409[409 Conflict]
    NameCheck -->|no duplicate| S3Upload[Upload to S3]
    S3Upload -->|failure| E500[500 Internal Server Error]
    S3Upload -->|success, get URL & size| Save[Save to DB]
    Save --> Success[201 Created]

GET /v1/medias

Overview

Retrieves a list of media.

Request and Response

URI

GET /v1/medias

Query Parameters

Parameter	Type	Notes
mime_type	enum	Filter by `image` / `video`
page	number	Page number to retrieve. Default: `1`
size	number	Items per page. Default: `10`
order	enum	`asc` / `desc` (by `updated_at`). Default: `desc`

Request Body

None

Response

200 OK

{
  "list": [
    {
      "id": "string",
      "name": "string",
      "mime_type": "image",
      "s3_url": "string",
      "size": 1024,
      "race_id": null,
      "created_at": 1234567890000,
      "updated_at": 1234567890000
    }
  ],
  "current_page": 1,
  "total_count": 10
}

Error Handling

Description	Status Code	Status Name
Internal server error	500	Internal Server Error

Processing Flow

Receive the request
Fetch the media list filtered by query parameters
Return the list

flowchart TD
    Start([GET /v1/medias]) --> Fetch[Fetch media list from DB]
    Fetch --> Success[200 OK]

GET /v1/medias/{media_id}

Overview

Retrieves the specified media.

Request and Response

URI

GET /v1/medias/{media_id}

Path Parameter	Type	Notes
media_id	string	`_id`

Request Body

None

Response

200 OK

{
  "id": "string",
  "name": "string",
  "mime_type": "image",
  "s3_url": "string",
  "size": 1024,
  "race_id": null,
  "created_at": 1234567890000,
  "updated_at": 1234567890000
}

Error Handling

Description	Status Code	Status Name
Media not found	404	Not Found
Internal server error	500	Internal Server Error

Processing Flow

Receive the request
Search for media by media_id
Return the media

flowchart TD
    Start([GET /v1/medias/media_id]) --> Fetch[Search in DB]
    Fetch -->|not found| E404[404 Not Found]
    Fetch -->|found| Success[200 OK]

PUT /v1/medias/{media_id}

Overview

Updates the specified media.

Request and Response

Headers

Request Headers

Content-Type: multipart/form-data

Response Headers

Content-Type: application/json

URI

PUT /v1/medias/{media_id}

Path Parameter	Type	Notes
media_id	string	`_id`

Request Body

Send in multipart/form-data format. If file is omitted, only metadata is updated.

Field	Type	Notes
name	string	Unique
mime_type	enum	`image` / `video`
file	binary	Replacement file. If specified, overwrites the file in S3

Response

200 OK

{
  "id": "string",
  "name": "string",
  "mime_type": "image",
  "s3_url": "string",
  "size": 1024,
  "race_id": null,
  "created_at": 1234567890000,
  "updated_at": 1234567890000
}

Error Handling

Description	Status Code	Status Name
Invalid request body	422	Unprocessable Entity
Media not found	404	Not Found
name already exists	409	Conflict
S3 upload failure	500	Internal Server Error
Internal server error	500	Internal Server Error

Processing Flow

Receive the request
Validate the request
Verify the media exists
If name is being changed, check for duplicates
If file is specified, overwrite-upload to S3 and update the URL and size
Update and save the media
Return the updated media

flowchart TD
    Start([PUT /v1/medias/media_id]) --> Validate[Request validation]
    Validate -->|invalid| E422[422 Unprocessable Entity]
    Validate -->|valid| Fetch[Search in DB]
    Fetch -->|not found| E404[404 Not Found]
    Fetch -->|found| NameCheck[Check name duplicate]
    NameCheck -->|duplicate| E409[409 Conflict]
    NameCheck -->|no duplicate| FileCheck{file specified?}
    FileCheck -->|yes| S3Upload[Overwrite upload to S3]
    S3Upload -->|failure| E500[500 Internal Server Error]
    S3Upload -->|success, update URL & size| Save[Save to DB]
    FileCheck -->|no| Save
    Save --> Success[200 OK]

DELETE /v1/medias/{media_id}

Overview

Soft-deletes the specified media.

Request and Response

URI

DELETE /v1/medias/{media_id}

Path Parameter	Type	Notes
media_id	string	`_id`

Request Body

None

Response

204 No Content

Error Handling

Description	Status Code	Status Name
Media not found	404	Not Found
Internal server error	500	Internal Server Error

Processing Flow

Receive the request
Verify the media exists
Set deleted_at to the current time and save (soft delete)
Return 204

flowchart TD
    Start([DELETE /v1/medias/media_id]) --> Fetch[Search in DB]
    Fetch -->|not found| E404[404 Not Found]
    Fetch -->|found| Delete[Set deleted_at]
    Delete --> Success[204 No Content]