RomM Memory Cards API

openapi: 3.2.0
info:
  title: RomM Memory Cards API
  version: 5.4.0
tags:
- name: memory-cards
paths:
  /api/memory-cards:
    post:
      tags:
      - memory-cards
      summary: Add Memory Card
      description: 'Create an empty memory card. It hydrates onto a container at the next

        streaming claim; its data accrues as versions on save-and-exit.'
      operationId: add_memory_card_api_memory_cards_post
      security:
      - OAuth2PasswordBearer:
        - assets.write
      - HTTPBasic: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoryCardCreatePayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryCardSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - memory-cards
      summary: Get Memory Cards
      description: The caller's own cards, newest-synced first, optionally one emulator.
      operationId: get_memory_cards_api_memory_cards_get
      security:
      - OAuth2PasswordBearer:
        - assets.read
      - HTTPBasic: []
      parameters:
      - name: emulator
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Emulator
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MemoryCardSchema'
                title: Response Get Memory Cards Api Memory Cards Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/memory-cards/shared:
    get:
      tags:
      - memory-cards
      summary: Get Shared Memory Cards
      description: 'Cards for an emulator visible to the caller: their own plus other users''

        public ones. Browsing and download only: mounting a card at claim is

        owner-scoped, so the picker lists the caller''s own cards instead.'
      operationId: get_shared_memory_cards_api_memory_cards_shared_get
      security:
      - OAuth2PasswordBearer:
        - assets.read
      - HTTPBasic: []
      parameters:
      - name: emulator
        in: query
        required: true
        schema:
          type: string
          title: Emulator
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserMemoryCardSchema'
                title: Response Get Shared Memory Cards Api Memory Cards Shared Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/memory-cards/versions/{id}/content:
    get:
      tags:
      - memory-cards
      summary: Download Memory Card Version
      description: 'Download a version''s card archive. Readable if the caller owns the parent

        card or it is public.'
      operationId: download_memory_card_version_api_memory_cards_versions__id__content_get
      security:
      - OAuth2PasswordBearer:
        - assets.read
      - HTTPBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/memory-cards/{id}/content:
    get:
      tags:
      - memory-cards
      summary: Download Memory Card
      description: 'Download the card as it stands now, without going through its history.


        This is the newest version, which is also what the next claim hydrates onto

        a container, so what comes down here is what the emulator would boot with.

        A card that has never been synced has nothing to serve and 404s.'
      operationId: download_memory_card_api_memory_cards__id__content_get
      security:
      - OAuth2PasswordBearer:
        - assets.read
      - HTTPBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/memory-cards/{id}/versions:
    post:
      tags:
      - memory-cards
      summary: Upload Memory Card Version
      description: 'Store a card image the user supplied as the card''s newest version, which

        is what the next claim hydrates onto the container (owner only).


        Only the zip layout the broker exchanges is accepted. A bare card image

        (`.ps2`, `.raw`) is refused rather than stored, because nothing downstream

        would notice until hydrate pushed it and the emulator rejected the card.'
      operationId: upload_memory_card_version_api_memory_cards__id__versions_post
      security:
      - OAuth2PasswordBearer:
        - assets.write
      - HTTPBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_memory_card_version_api_memory_cards__id__versions_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryCardVersionSchema'
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '413':
          description: Content Too Large
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - memory-cards
      summary: Get Memory Card Versions
      description: A card's snapshot history, newest first.
      operationId: get_memory_card_versions_api_memory_cards__id__versions_get
      security:
      - OAuth2PasswordBearer:
        - assets.read
      - HTTPBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MemoryCardVersionSchema'
                title: Response Get Memory Card Versions Api Memory Cards  Id  Versions Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/memory-cards/{id}:
    get:
      tags:
      - memory-cards
      summary: Get Memory Card
      description: 'A single card: the caller''s own or another user''s public one.'
      operationId: get_memory_card_api_memory_cards__id__get
      security:
      - OAuth2PasswordBearer:
        - assets.read
      - HTTPBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryCardSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - memory-cards
      summary: Rename Memory Card
      description: Rename a card (owner only).
      operationId: rename_memory_card_api_memory_cards__id__put
      security:
      - OAuth2PasswordBearer:
        - assets.write
      - HTTPBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_rename_memory_card_api_memory_cards__id__put'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryCardSchema'
        '404':
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/memory-cards/{id}/visibility:
    put:
      tags:
      - memory-cards
      summary: Update Memory Card Visibility
      description: 'Toggle a card''s public/private visibility (owner only). Sharing is

        one-way: a recipient''s writes go to their own card, never back to this one.'
      operationId: update_memory_card_visibility_api_memory_cards__id__visibility_put
      security:
      - OAuth2PasswordBearer:
        - assets.write
      - HTTPBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_update_memory_card_visibility_api_memory_cards__id__visibility_put'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryCardSchema'
        '404':
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/memory-cards/delete:
    post:
      tags:
      - memory-cards
      summary: Delete Memory Cards
      description: 'Delete cards the caller owns, with their version files. Versions cascade

        in the database; their on-disk archives are removed here.'
      operationId: delete_memory_cards_api_memory_cards_delete_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_delete_memory_cards_api_memory_cards_delete_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  type: integer
                type: array
                title: Response Delete Memory Cards Api Memory Cards Delete Post
        '400':
          description: Bad Request
        '404':
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer:
        - assets.write
      - HTTPBasic: []
components:
  schemas:
    Body_update_memory_card_visibility_api_memory_cards__id__visibility_put:
      properties:
        is_public:
          type: boolean
          title: Is Public
      type: object
      required:
      - is_public
      title: Body_update_memory_card_visibility_api_memory_cards__id__visibility_put
    UserMemoryCardSchema:
      properties:
        id:
          type: integer
          title: Id
        user_id:
          type: integer
          title: User Id
        emulator:
          type: string
          title: Emulator
        platform_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Platform Id
        name:
          type: string
          title: Name
        slot:
          type: integer
          title: Slot
        is_public:
          type: boolean
          title: Is Public
          default: false
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
        username:
          type: string
          title: Username
        user_avatar_path:
          type: string
          title: User Avatar Path
          default: ''
        user_updated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: User Updated At
      type: object
      required:
      - id
      - user_id
      - emulator
      - name
      - slot
      - created_at
      - updated_at
      - username
      title: UserMemoryCardSchema
      description: 'A card enriched with its owner''s username, for the shared/community

        picker. Mirrors UserStateSchema.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Body_rename_memory_card_api_memory_cards__id__put:
      properties:
        name:
          type: string
          maxLength: 255
          title: Name
      type: object
      required:
      - name
      title: Body_rename_memory_card_api_memory_cards__id__put
    Body_upload_memory_card_version_api_memory_cards__id__versions_post:
      properties:
        cardFile:
          type: string
          contentMediaType: application/octet-stream
          title: Cardfile
          description: Memory card archive to upload.
      type: object
      required:
      - cardFile
      title: Body_upload_memory_card_version_api_memory_cards__id__versions_post
    MemoryCardVersionSchema:
      properties:
        id:
          type: integer
          title: Id
        memory_card_id:
          type: integer
          title: Memory Card Id
        file_name:
          type: string
          title: File Name
        file_size_bytes:
          type: integer
          title: File Size Bytes
        content_hash:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Hash
        download_path:
          type: string
          title: Download Path
        missing_from_fs:
          type: boolean
          title: Missing From Fs
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
      type: object
      required:
      - id
      - memory_card_id
      - file_name
      - file_size_bytes
      - download_path
      - missing_from_fs
      - created_at
      - updated_at
      title: MemoryCardVersionSchema
      description: 'A single snapshot in a card''s history. Unlike the ROM-scoped assets it

        has no rom_id/user_id, so it does not reuse the shared BaseAsset schema.'
    Body_delete_memory_cards_api_memory_cards_delete_post:
      properties:
        cards:
          items:
            type: integer
          type: array
          title: Cards
          description: List of memory card ids to delete.
      type: object
      required:
      - cards
      title: Body_delete_memory_cards_api_memory_cards_delete_post
    MemoryCardCreatePayload:
      properties:
        name:
          type: string
          maxLength: 255
          title: Name
        emulator:
          type: string
          maxLength: 50
          title: Emulator
        platform_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Platform Id
        is_public:
          type: boolean
          title: Is Public
          default: false
      type: object
      required:
      - name
      - emulator
      title: MemoryCardCreatePayload
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    MemoryCardSchema:
      properties:
        id:
          type: integer
          title: Id
        user_id:
          type: integer
          title: User Id
        emulator:
          type: string
          title: Emulator
        platform_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Platform Id
        name:
          type: string
          title: Name
        slot:
          type: integer
          title: Slot
        is_public:
          type: boolean
          title: Is Public
          default: false
        created_at:
          type: string
          title: Created At
        updated_at:
          type: string
          title: Updated At
      type: object
      required:
      - id
      - user_id
      - emulator
      - name
      - slot
      - created_at
      - updated_at
      title: MemoryCardSchema
      description: 'A card''s identity. Its data lives in `versions`; the list views return

        the card without them (fetch history via the versions route) so the schema

        never touches the lazy="raise" relationship.'
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes:
            me.read: View your profile
            roms.read: View ROMs
            platforms.read: View platforms
            assets.read: View assets
            devices.read: View devices
            firmware.read: View firmware
            roms.user.read: View user-rom properties
            collections.read: View collections
            playlists.read: View music playlists
            me.write: Modify your profile
            assets.write: Modify assets
            devices.write: Modify devices
            roms.user.write: Modify user-rom properties
            collections.write: Modify collections
            playlists.write: Modify music playlists
            roms.write: Modify ROMs
            platforms.write: Modify platforms
            firmware.write: Modify firmware
            users.read: View users
            users.write: Modify users
            tasks.run: Run tasks
            logs.read: View backend logs
          tokenUrl: /token
    HTTPBasic:
      type: http
      scheme: basic