thamanyah/cms/docs/swagger.yaml

basePath: /
definitions:
  api.CategoriesResponse:
    properties:
      categories:
        items:
          $ref: '#/definitions/api.Category'
        type: array
    type: object
  api.Category:
    properties:
      id:
        example: 1
        type: integer
      name:
        example: documentary
        type: string
    type: object
  api.CompleteRequest:
    properties:
      categoryIds:
        example:
        - 1
        - 2
        items:
          type: integer
        type: array
      description:
        example: A behind-the-scenes look at the evening bulletin.
        type: string
      fileName:
        example: interview-cut.mov
        type: string
      key:
        example: videos/a1b2c3d4e5f6.mov
        type: string
      tags:
        example: media, press, riyadh
        type: string
      title:
        example: Inside the Newsroom
        type: string
    type: object
  api.CompleteResponse:
    properties:
      categoryIds:
        example:
        - 1
        - 2
        items:
          type: integer
        type: array
      createdAt:
        type: string
      description:
        example: A behind-the-scenes look at the evening bulletin.
        type: string
      fileName:
        example: interview-cut.mov
        type: string
      id:
        example: 0199f3a1-7c2e-7b21-9f0d-1a2b3c4d5e6f
        type: string
      mediaConvertJobId:
        example: 1755300000000-abcdef
        type: string
      sizeBytes:
        example: 60
        type: integer
      status:
        enum:
        - processing
        - ready
        - failed
        example: processing
        type: string
      storageKey:
        example: videos/a1b2c3d4e5f6.mov
        type: string
      tags:
        example: media, press, riyadh
        type: string
      title:
        example: Inside the Newsroom
        type: string
      updatedAt:
        type: string
    type: object
  api.HealthResponse:
    properties:
      status:
        example: ok
        type: string
    type: object
  api.PresignRequest:
    properties:
      contentType:
        enum:
        - video/mp4
        - video/quicktime
        example: video/quicktime
        type: string
      fileName:
        example: interview-cut.mov
        type: string
    type: object
  api.PresignResponse:
    properties:
      key:
        example: videos/a1b2c3d4e5f6.mov
        type: string
      uploadUrl:
        example: https://raw-uploads-bucket.s3.amazonaws.com/videos/a1b2....mov?X-Amz-Signature=...
        type: string
    type: object
  api.ProblemDetails:
    properties:
      detail:
        example: The 'title' field was absent or contained only whitespace. Every
          video needs a non-empty title.
        type: string
      status:
        example: 422
        type: integer
      title:
        example: Title is required.
        type: string
      type:
        example: about:blank
        type: string
    type: object
info:
  contact: {}
  description: 'JSON API for ingesting videos into the Thamanyah catalogue. Uploads
    are two-step: presign, PUT the file straight to S3, then register the video to
    queue transcoding.'
  title: Thamanyah CMS API
  version: "1.0"
paths:
  /api/categories:
    get:
      description: Returns the fixed lookup set of categories a video can belong to,
        each with the id used to reference it. The `id` values from this list are
        the only ones accepted in the `categoryIds` field of POST /api/videos.
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/api.CategoriesResponse'
        "500":
          description: Categories could not be read from the database
          schema:
            $ref: '#/definitions/api.ProblemDetails'
      summary: List video categories
      tags:
      - categories
  /api/videos:
    post:
      consumes:
      - application/json
      description: Step 2 of the upload flow. Takes the storage key returned by POST
        /api/videos/presign — after the file has been PUT to the presigned URL — submits
        a MediaConvert transcoding job, and persists the video with its category links.
        The returned record has status "processing" — one of the states "processing",
        "ready" or "failed" — though nothing currently moves it on once transcoding
        finishes.
      parameters:
      - description: Video metadata plus the storage key from the presign step. title,
          key and categoryIds are required; categoryIds must hold at least one id
          from GET /api/categories.
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.CompleteRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/api.CompleteResponse'
        "400":
          description: Request body was not valid JSON
          schema:
            $ref: '#/definitions/api.ProblemDetails'
        "422":
          description: title was empty, key was missing or not a key issued by this
            API, or categoryIds was empty or contained an id that does not exist
          schema:
            $ref: '#/definitions/api.ProblemDetails'
        "500":
          description: Categories could not be read, the transcoding job could not
            be queued, or the video record could not be saved
          schema:
            $ref: '#/definitions/api.ProblemDetails'
      summary: Register an uploaded video
      tags:
      - videos
  /api/videos/presign:
    post:
      consumes:
      - application/json
      description: Step 1 of the upload flow. Returns a short-lived presigned S3 URL
        that the client PUTs the video file to directly, plus the storage key identifying
        it. The submitted contentType is signed into that URL, so the PUT must carry
        an identical Content-Type header or S3 rejects it as a signature mismatch.
        Once the PUT succeeds, pass the key to POST /api/videos to register the video
        and start transcoding. The file itself never passes through this API.
      parameters:
      - description: Name and media type of the file to be uploaded. contentType must
          be exactly 'video/mp4' or 'video/quicktime'.
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.PresignRequest'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/api.PresignResponse'
        "400":
          description: Request body was not valid JSON
          schema:
            $ref: '#/definitions/api.ProblemDetails'
        "422":
          description: contentType was not 'video/mp4' or 'video/quicktime'
          schema:
            $ref: '#/definitions/api.ProblemDetails'
        "500":
          description: Upload URL could not be issued
          schema:
            $ref: '#/definitions/api.ProblemDetails'
      summary: Create a presigned upload URL
      tags:
      - videos
  /health:
    get:
      description: Reports that the service is up and serving. Used as the ALB target
        group health check; it does not verify the database or S3 connections.
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/api.HealthResponse'
      summary: Health check
      tags:
      - system
swagger: "2.0"