openapi.yaml

openapi: 3.0.3
info:
  title: Builder Server API
  version: 2.10.0
  description: |
    ## Overview

    The Builder Server API provides backend services for the Decentraland Builder application.
    It enables management of scene projects, wearable/emote collections, asset packs, and more.

    ## Authentication

    Most endpoints require authentication using Decentraland's Signed Fetch mechanism (ADR-44).
    Authentication is provided via the `X-Identity-Auth-Chain-*` headers.

    ## Base URL

    The API version prefix is configurable via the `API_VERSION` environment variable (default: `v1`).
    All endpoints are prefixed with `/{API_VERSION}/`.

  contact:
    name: Decentraland Foundation
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: https://builder-api.decentraland.org/v1
    description: Production environment
    variables: {}
  - url: https://builder-api.decentraland.zone/v1
    description: Development environment
    variables: {}

tags:
  - name: App
    description: Application info and health check
  - name: Projects
    description: Scene project management
  - name: Pools
    description: Public scene pools for community sharing
  - name: Pool Groups
    description: Pool categorization and grouping
  - name: Pool Likes
    description: Pool like management
  - name: Collections
    description: Wearable and emote collection management
  - name: Items
    description: Wearable and emote item management
  - name: Curations
    description: Collection and item curation workflow
  - name: Committee
    description: Committee member operations
  - name: Third Party
    description: Third-party collection management
  - name: Rarities
    description: Item rarity definitions
  - name: Forum
    description: Discourse forum integration
  - name: Asset Packs
    description: Asset pack management
  - name: Assets
    description: Individual 3D asset management
  - name: Manifest
    description: Project manifest operations
  - name: Deployments
    description: Scene deployment tracking
  - name: Storage
    description: S3 storage proxy endpoints
  - name: Share
    description: Share link generation
  - name: Analytics
    description: Analytics endpoints
  - name: NFT
    description: NFT-related operations
  - name: LAND
    description: LAND parcel operations
  - name: Newsletter
    description: Newsletter subscription management

security:
  - SignedFetch: []

paths:
  # App endpoints
  /info:
    get:
      operationId: getServerInfo
      tags: [App]
      summary: Get server version
      description: Returns the current server version
      security: []
      responses:
        '200':
          description: Server version information
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                    properties:
                      version:
                        type: string

  # Project endpoints
  /templates:
    get:
      operationId: getProjectTemplates
      tags: [Projects]
      summary: Get all project templates
      description: Returns all public project templates
      security: []
      responses:
        '200':
          description: List of project templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectListResponse'

  /projects:
    get:
      operationId: getProjects
      tags: [Projects]
      summary: Get all projects
      description: Returns all projects for the authenticated user
      responses:
        '200':
          description: List of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /projects/{id}:
    get:
      operationId: getProject
      tags: [Projects]
      summary: Get a project
      description: Returns a specific project by ID
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: upsertProject
      tags: [Projects]
      summary: Create or update a project
      description: Creates a new project or updates an existing one
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectInput'
      responses:
        '200':
          description: Project created/updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteProject
      tags: [Projects]
      summary: Delete a project
      description: Soft deletes a project
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Project deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /projects/{id}/public:
    get:
      operationId: getPublicProject
      tags: [Projects]
      summary: Get a public project
      description: Returns a public project by ID (no authentication required)
      security: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Public project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /projects/{id}/media:
    post:
      operationId: uploadProjectMedia
      tags: [Projects]
      summary: Upload project media
      description: Uploads media files (thumbnails, previews) for a project
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                thumbnail:
                  type: string
                  format: binary
                preview:
                  type: string
                  format: binary
                north:
                  type: string
                  format: binary
                east:
                  type: string
                  format: binary
                south:
                  type: string
                  format: binary
                west:
                  type: string
                  format: binary
      responses:
        '200':
          description: Media uploaded successfully
        '401':
          $ref: '#/components/responses/Unauthorized'

  /projects/{id}/media/{filename}:
    get:
      operationId: getProjectMediaFile
      tags: [Projects]
      summary: Get project media file
      description: Redirects to the S3 URL for the media file
      security: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: filename
          in: path
          required: true
          schema:
            type: string
      responses:
        '301':
          description: Redirect to S3 URL
        '404':
          $ref: '#/components/responses/NotFound'

  /projects/{id}/contents/{content}:
    get:
      operationId: getProjectContent
      tags: [Projects]
      summary: Get project content
      description: Returns project content by hash. For preview hash, returns entity object. For CRDT hash, redirects to CRDT file.
      security: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - name: content
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Entity object (for preview hash)
          content:
            application/json:
              schema:
                type: object
        '301':
          description: Redirect to content URL
        '302':
          description: Redirect to CRDT file
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'

  /projects/{id}/about:
    get:
      operationId: getProjectPreviewInfo
      tags: [Projects]
      summary: Get project preview info
      description: Returns realm configuration for project preview
      security: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Preview configuration
          content:
            application/json:
              schema:
                type: object

  /projects/{id}/crdt:
    get:
      operationId: getProjectCrdt
      tags: [Projects]
      summary: Get project CRDT
      description: Returns the CRDT file for the project
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '302':
          description: Redirect to CRDT file
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: uploadProjectCrdt
      tags: [Projects]
      summary: Upload project CRDT
      description: Uploads the CRDT file for a project
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: CRDT uploaded successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /projects/{coords}/coords:
    delete:
      operationId: removeProjectCoords
      tags: [Projects]
      summary: Remove coords from projects
      description: Removes creation coordinates from all projects with the given coords
      parameters:
        - name: coords
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Coordinates removed successfully
        '401':
          $ref: '#/components/responses/Unauthorized'

  # Pool endpoints
  /pools:
    get:
      operationId: getPools
      tags: [Pools]
      summary: Get all pools
      description: Returns all public scene pools with filtering and pagination
      security: []
      parameters:
        - name: eth_address
          in: query
          schema:
            type: string
        - name: group
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/SortBy'
        - $ref: '#/components/parameters/SortOrder'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: List of pools
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoolListResponse'

  /projects/{id}/pool:
    get:
      operationId: getPool
      tags: [Pools]
      summary: Get a pool
      description: Returns a pool by project ID
      security: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Pool details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoolResponse'
    put:
      operationId: upsertPool
      tags: [Pools]
      summary: Create or update a pool
      description: Creates a pool from a project or updates an existing pool
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                groups:
                  type: array
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Pool created/updated successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  # Pool Group endpoints
  /pools/groups:
    get:
      operationId: getPoolGroups
      tags: [Pool Groups]
      summary: Get all pool groups
      description: Returns all pool groups
      security: []
      parameters:
        - name: active_only
          in: query
          schema:
            type: boolean
            default: false
          description: Filter to only active groups
      responses:
        '200':
          description: List of pool groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PoolGroup'

  # Pool Like endpoints
  /pools/{id}/likes:
    get:
      operationId: getPoolLikes
      tags: [Pool Likes]
      summary: Get pool likes count
      description: Returns the total number of likes for a pool
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: address
          in: query
          schema:
            type: string
          description: Filter by user address (use "me" for current user)
      responses:
        '200':
          description: Pool likes count
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: integer
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: likePool
      tags: [Pool Likes]
      summary: Like a pool
      description: Adds a like to a pool
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Pool liked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: integer
                    description: New total likes count
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: unlikePool
      tags: [Pool Likes]
      summary: Unlike a pool
      description: Removes a like from a pool
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Pool unliked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: integer
                    description: New total likes count
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  # Collection endpoints
  /collections:
    get:
      operationId: getCollections
      tags: [Collections]
      summary: Get all collections
      description: |
        Returns collections with filtering and pagination. Committee members see every collection; anyone else
        needs `q` and `is_published=true`.
      parameters:
        - name: q
          in: query
          schema:
            type: string
          description: Search by collection name
        - name: assignee
          in: query
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: Curator addresses and/or `unassigned`, any of them matches. Up to 20; repeat the param.
        - name: status
          in: query
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/CurationStatusFilter'
          description: Review statuses, any of them matches. Repeat the param.
        - name: review_type
          in: query
          schema:
            type: string
            enum: [new, updates]
          description: Only collections never approved (`new`), or only changes to ones approved before (`updates`)
        - name: type
          in: query
          schema:
            type: string
            enum: [standard, third_party]
        - name: is_published
          in: query
          schema:
            type: string
            enum: ['true', 'false']
        - name: sort
          in: query
          schema:
            type: string
            enum:
              [
                MOST_RELEVANT,
                CREATED_AT_DESC,
                CREATED_AT_ASC,
                NAME_DESC,
                NAME_ASC,
                UPDATED_AT_DESC,
                UPDATED_AT_ASC,
                LAST_ACTIVITY_DESC,
                LAST_ACTIVITY_ASC,
                REQUESTED_AT_DESC,
                REQUESTED_AT_ASC,
              ]
          description: |
            `MOST_RELEVANT` puts the collections waiting for a curator first. `LAST_ACTIVITY_*` orders by the last
            change to the collection, its items or its review; `REQUESTED_AT_*` by when its review was requested.
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: List of collections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /{address}/collections:
    get:
      operationId: getCollectionsByAddress
      tags: [Collections]
      summary: Get collections by address
      description: |
        Returns the collections the signed-in address created or collaborates on (the path address must be the
        signed-in one).

        `status` filters standard collections by the status the creator sees:
        - `draft`: not published yet.
        - `under_review`: waiting for the curation committee, either its first review or changes sent after approval.
        - `published`: approved and live, with nothing waiting for review.
        - `rejected`: the committee rejected its last review.
        - `disabled`: approved before, then disabled by the committee.

        Paginated responses also include `counts`: how many collections are in each status, following the
        search and type filters but not the status filter.
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, under_review, published, rejected, disabled]
        - name: type
          in: query
          schema:
            type: string
            enum: [standard, third_party]
        - name: q
          in: query
          description: Case-insensitive search on the collection name
          schema:
            type: string
        - name: is_published
          in: query
          schema:
            type: string
        - name: sort
          in: query
          description: |
            Defaults to `CREATED_AT_DESC`. `LAST_ACTIVITY_*` orders by the last time the collection, its items or
            its review changed. `REQUESTED_AT_*` orders by when the latest review was requested, or the collection
            was created when it was never reviewed.
          schema:
            type: string
            enum:
              - MOST_RELEVANT
              - CREATED_AT_DESC
              - CREATED_AT_ASC
              - NAME_DESC
              - NAME_ASC
              - UPDATED_AT_DESC
              - UPDATED_AT_ASC
              - LAST_ACTIVITY_DESC
              - LAST_ACTIVITY_ASC
              - REQUESTED_AT_DESC
              - REQUESTED_AT_ASC
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: List of collections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressCollectionListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /collections/{id}:
    get:
      operationId: getCollection
      tags: [Collections]
      summary: Get a collection
      description: Returns a collection by ID
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      responses:
        '200':
          description: Collection details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: upsertCollection
      tags: [Collections]
      summary: Create or update a collection
      description: Creates a new collection or updates an existing one
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionInput'
      responses:
        '200':
          description: Collection created/updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '423':
          $ref: '#/components/responses/Locked'
    delete:
      operationId: deleteCollection
      tags: [Collections]
      summary: Delete a collection
      description: Deletes a collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      responses:
        '200':
          description: Collection deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '423':
          $ref: '#/components/responses/Locked'

  /collections/{id}/publish:
    post:
      operationId: publishCollection
      tags: [Collections]
      summary: Publish a collection
      description: Publishes a collection to the blockchain
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                itemIds:
                  type: array
                  items:
                    type: string
                cheque:
                  $ref: '#/components/schemas/Cheque'
      responses:
        '200':
          description: Collection published successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'

  /collections/{id}/lock:
    post:
      operationId: lockCollection
      tags: [Collections]
      summary: Lock a collection
      description: Locks a collection until publication
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      responses:
        '200':
          description: Collection locked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: string
                    format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /collections/{id}/tos:
    post:
      operationId: saveCollectionTos
      tags: [Collections]
      summary: Save Terms of Service
      description: Records Terms of Service acceptance for collection publication
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                event:
                  type: string
                  enum: [publish_collection_tos, publish_third_party_items_tos]
                hashes:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: TOS recorded successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /collections/{id}/approvalData:
    get:
      operationId: getCollectionApprovalData
      tags: [Collections]
      summary: Get approval data
      description: Returns data needed to approve a third-party collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      responses:
        '200':
          description: Approval data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemApprovalData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /addresses:
    get:
      operationId: getCollectionAddresses
      tags: [Collections]
      summary: Get collection addresses
      description: Returns the contract addresses of standard collections, with the same filters and sorts as `GET /collections`.
      security: []
      parameters:
        - name: assignee
          in: query
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: Curator addresses and/or `unassigned`, any of them matches. Up to 20; repeat the param.
        - name: status
          in: query
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/CurationStatusFilter'
          description: Review statuses, any of them matches. Repeat the param.
        - name: review_type
          in: query
          schema:
            type: string
            enum: [new, updates]
          description: Only collections never approved (`new`), or only changes to ones approved before (`updates`)
        - name: sort
          in: query
          schema:
            type: string
            enum:
              [
                MOST_RELEVANT,
                CREATED_AT_DESC,
                CREATED_AT_ASC,
                NAME_DESC,
                NAME_ASC,
                UPDATED_AT_DESC,
                UPDATED_AT_ASC,
                LAST_ACTIVITY_DESC,
                LAST_ACTIVITY_ASC,
                REQUESTED_AT_DESC,
                REQUESTED_AT_ASC,
              ]
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: List of addresses
        '400':
          $ref: '#/components/responses/BadRequest'

  # Item endpoints
  /items:
    get:
      operationId: getItems
      tags: [Items]
      summary: Get all items
      description: Returns all items (committee members only)
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /{address}/items:
    get:
      operationId: getItemsByAddress
      tags: [Items]
      summary: Get items by address
      description: Returns items for a specific address
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: collectionId
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /items/{id}:
    get:
      operationId: getItem
      tags: [Items]
      summary: Get an item
      description: Returns an item by ID
      parameters:
        - $ref: '#/components/parameters/ItemId'
      responses:
        '200':
          description: Item details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      operationId: upsertItem
      tags: [Items]
      summary: Create or update an item
      description: Creates a new item or updates an existing one (by ID or URN)
      parameters:
        - name: id
          description: Item UUID or URN
          in: path
          required: true
          schema:
            oneOf:
              - type: string
                format: uuid
              - type: string
                pattern: '^(urn:decentraland:(mainnet|goerli|sepolia|matic|mumbai|amoy):collections-thirdparty:[^:|\\s]+):([^:|\\s]+):([^:|\\s]+)$'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemInput'
      responses:
        '200':
          description: Item created/updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '423':
          $ref: '#/components/responses/Locked'
    delete:
      operationId: deleteItem
      tags: [Items]
      summary: Delete an item
      description: Deletes an item
      parameters:
        - $ref: '#/components/parameters/ItemId'
      responses:
        '200':
          description: Item deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '423':
          $ref: '#/components/responses/Locked'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /collections/{id}/items:
    get:
      operationId: getCollectionItems
      tags: [Items]
      summary: Get collection items
      description: Returns items for a specific collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/CurationStatus'
        - name: synced
          in: query
          schema:
            type: string
        - name: mappingStatus
          in: query
          schema:
            type: string
            enum: [missing_mapping, unpublished_mapping]
        - name: name
          in: query
          schema:
            type: string
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: List of items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /items/{id}/files:
    post:
      operationId: uploadItemFiles
      tags: [Items]
      summary: Upload item files
      description: Uploads content files for an item
      parameters:
        - $ref: '#/components/parameters/ItemId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        '200':
          description: Files uploaded successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /items/{id}/videos:
    post:
      operationId: uploadItemVideo
      tags: [Items]
      summary: Upload item video
      description: Uploads a video file for an item (max 250MB)
      parameters:
        - $ref: '#/components/parameters/ItemId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        '200':
          description: Video uploaded successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /items/{collectionAddress}/{itemId}/contents:
    get:
      operationId: getItemContents
      tags: [Items]
      summary: Get item contents
      description: Returns item contents by contract address and item ID
      security: []
      parameters:
        - name: collectionAddress
          in: path
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Item contents
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /published-collections/{address}/items/{id}/utility:
    get:
      operationId: getItemUtility
      tags: [Items]
      summary: Get item utility
      description: Returns the utility field for a published item
      security: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Item utility
          content:
            application/json:
              schema:
                type: object
                properties:
                  utility:
                    type: string
                    nullable: true
        '404':
          $ref: '#/components/responses/NotFound'

  # Curation endpoints
  /curations:
    get:
      operationId: getCollectionCurations
      tags: [Curations]
      summary: Get all collection curations
      description: Returns all collection curations
      responses:
        '200':
          description: List of curations
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollectionCuration'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /collections/{id}/curation:
    get:
      operationId: getCollectionCuration
      tags: [Curations]
      summary: Get collection curation
      description: Returns the curation for a collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      responses:
        '200':
          description: Collection curation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionCurationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    post:
      operationId: createCollectionCuration
      tags: [Curations]
      summary: Create collection curation
      description: |
        Opens a new review request for a published collection: the creator's "publish changes" or "request review
        again", or a committee member picking a never-requested collection up. Answers 400 while one is pending.
        A creator's request is announced in the curators' Slack channel.
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                assignee:
                  type: string
                  description: Committee member to assign. Only committee members may send it.
      responses:
        '200':
          description: Curation created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateCollectionCuration
      tags: [Curations]
      summary: Update collection curation
      description: |
        Updates the latest curation of a collection. Approving, rejecting and changing the assignee (including
        clearing it) are committee-only and answer 401 otherwise. A change of assignee or verdict is announced in
        the curators' Slack channel; repeating the current value is not.
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/CurationStatus'
                assignee:
                  type: string
                  nullable: true
                  description: Committee member to assign; `null` or an empty string clears the assignment.
      responses:
        '200':
          description: Curation updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /collections/{id}/curation/post:
    post:
      operationId: createCurationForumPost
      tags: [Curations]
      summary: Create curation forum post
      description: Creates a forum post for curation assignee change
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Forum post created successfully
        '401':
          $ref: '#/components/responses/Unauthorized'

  /collections/{id}/validation-result:
    post:
      operationId: receiveValidationResult
      tags: [Curations]
      summary: Receive a wearable-validator result
      description: |
        Callback of the wearable-validator job with the result of an automatic review. Authenticated by the HMAC
        of the raw body (`x-wearable-validator-signature`, `sha256=<hex>` over `<timestamp>.<body>` with the shared
        secret) and `x-wearable-validator-timestamp` (epoch milliseconds, at most 5 minutes off). The result is
        logged only; the job posts its findings to the curators' Slack channel. Unknown fields are dropped.
      security: []
      parameters:
        - $ref: '#/components/parameters/CollectionId'
        - name: x-wearable-validator-signature
          in: header
          required: true
          schema:
            type: string
            pattern: '^sha256=[0-9a-f]{64}$'
          description: HMAC-SHA256 of `<timestamp>.<raw body>` with the shared secret
        - name: x-wearable-validator-timestamp
          in: header
          required: true
          schema:
            type: string
          description: Epoch milliseconds when the request was signed, at most 5 minutes off the server clock
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [validationId, collectionId, verdict, rulesVersion, items]
              properties:
                validationId:
                  type: string
                collectionId:
                  type: string
                  description: Must match the path id
                verdict:
                  type: string
                  enum: [passed, rejected, error]
                reason:
                  type: string
                  description: Only with verdict `error`
                retryable:
                  type: boolean
                  description: Only with verdict `error`
                rulesVersion:
                  type: string
                items:
                  type: array
                  maxItems: 50
                  items:
                    type: object
                    required: [itemId, contentHash, passed, findings]
                    properties:
                      itemId:
                        type: string
                      contentHash:
                        type: string
                      passed:
                        type: boolean
                        nullable: true
                      findings:
                        type: array
                        items:
                          type: object
                          required: [rule, check, severity, message]
                          properties:
                            rule:
                              type: string
                            check:
                              type: string
                            severity:
                              type: string
                              enum: [error, warning]
                            message:
                              type: string
                            where:
                              type: string
                            bodyShape:
                              type: string
                              enum: [male, female]
                            measured:
                              type: number
                            limit:
                              type: number
                            fix:
                              type: string
                            docs:
                              type: string
                      visualSummary:
                        type: string
                      unsupported:
                        type: boolean
                      error:
                        type: string
      responses:
        '204':
          description: Result received
        '400':
          description: Invalid body, or the result belongs to another collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, stale or invalid signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /collections/{id}/itemCurations:
    get:
      operationId: getCollectionItemCurations
      tags: [Curations]
      summary: Get collection item curations
      description: Returns item curations for a collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
        - name: itemIds
          in: query
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: List of item curations
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /items/{id}/curation:
    get:
      operationId: getItemCuration
      tags: [Curations]
      summary: Get item curation
      description: Returns the curation for an item
      parameters:
        - $ref: '#/components/parameters/ItemId'
      responses:
        '200':
          description: Item curation
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createItemCuration
      tags: [Curations]
      summary: Create item curation
      description: Creates a new curation for an item
      parameters:
        - $ref: '#/components/parameters/ItemId'
      responses:
        '200':
          description: Curation created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    patch:
      operationId: updateItemCuration
      tags: [Curations]
      summary: Update item curation
      description: Updates an item curation
      parameters:
        - $ref: '#/components/parameters/ItemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/CurationStatus'
      responses:
        '200':
          description: Curation updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  # Committee endpoints
  /committee:
    get:
      operationId: getCommittee
      tags: [Committee]
      summary: Check committee membership
      description: Returns the committee members
      security: []
      responses:
        '200':
          description: Committee members
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        address:
                          type: string

  # Third Party endpoints
  /thirdParties:
    get:
      operationId: getThirdParties
      tags: [Third Party]
      summary: Get third parties
      description: Returns the third parties managed by the authenticated wallet
      responses:
        '200':
          description: List of third parties
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ThirdParty'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /thirdParties/{id}:
    get:
      operationId: getThirdParty
      tags: [Third Party]
      summary: Get a third party
      description: >-
        Returns a third party by ID. Requires authentication. An unpublished
        (draft) third party is only returned to one of its managers; otherwise
        the response is 404.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Third party details
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/ThirdParty'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteThirdParty
      tags: [Third Party]
      summary: Remove virtual third party
      description: Removes a virtual third party after it's on the graph
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Third party removed successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateThirdParty
      tags: [Third Party]
      summary: Update third party
      description: Updates a virtual third party
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Third party updated successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /thirdParties/{id}/slots:
    get:
      operationId: getThirdPartySlots
      tags: [Third Party]
      summary: Get available slots
      description: Returns the number of available slots for a third party
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Available slots count
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'

  # Rarity endpoints
  /rarities:
    get:
      operationId: getRarities
      tags: [Rarities]
      summary: Get all rarities
      description: Returns all available item rarities with prices
      security: []
      responses:
        '200':
          description: List of rarities
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Rarity'

  /rarities/{name}:
    get:
      operationId: getRarity
      tags: [Rarities]
      summary: Get a rarity
      description: Returns a specific rarity by name
      security: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Rarity details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RarityResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  # Forum endpoints
  /collections/{id}/post:
    post:
      operationId: createCollectionForumPost
      tags: [Forum]
      summary: Create collection forum post
      description: Creates a forum post for a collection
      parameters:
        - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                forumPost:
                  type: object
                  properties:
                    title:
                      type: string
                    raw:
                      type: string
      responses:
        '200':
          description: Forum post created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: string
                    description: Forum link
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # Asset Pack endpoints
  /assetPacks:
    get:
      operationId: getAssetPacks
      tags: [Asset Packs]
      summary: Get all asset packs
      description: Returns asset packs for the user or default packs
      security: []
      parameters:
        - name: owner
          in: query
          schema:
            type: string
            description: 'Use "default" for default packs or user address'
      responses:
        '200':
          description: List of asset packs
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AssetPack'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /assetPacks/{id}:
    get:
      operationId: getAssetPack
      tags: [Asset Packs]
      summary: Get an asset pack
      description: Returns an asset pack by ID
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Asset pack details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetPackResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: upsertAssetPack
      tags: [Asset Packs]
      summary: Create or update an asset pack
      description: Creates a new asset pack or updates an existing one
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetPackInput'
      responses:
        '200':
          description: Asset pack created/updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteAssetPack
      tags: [Asset Packs]
      summary: Delete an asset pack
      description: Deletes an asset pack
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Asset pack deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /assetPacks/{id}/thumbnail:
    post:
      operationId: uploadAssetPackThumbnail
      tags: [Asset Packs]
      summary: Upload asset pack thumbnail
      description: Uploads a thumbnail for an asset pack
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                thumbnail:
                  type: string
                  format: binary
      responses:
        '200':
          description: Thumbnail uploaded successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  # Asset endpoints
  /assetPacks/{assetPackId}/assets/{id}/files:
    post:
      operationId: uploadAssetFiles
      tags: [Assets]
      summary: Upload asset files
      description: Uploads files for an asset in an asset pack
      parameters:
        - name: assetPackId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        '200':
          description: Files uploaded successfully
        '401':
          $ref: '#/components/responses/Unauthorized'

  /assets/{id}:
    get:
      operationId: getAsset
      tags: [Assets]
      summary: Get a single asset
      description: Returns an asset by ID
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Asset details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetPackResponse'
        '404':
          $ref: '#/components/responses/NotFound'

  /assets:
    get:
      operationId: getAssets
      tags: [Assets]
      summary: Get multiple assets
      description: Returns multiple assets by IDs
      security: []
      parameters:
        - name: id
          in: query
          required: true
          schema:
            oneOf:
              - type: string
                format: uuid
              - type: array
                items:
                  type: string
                  format: uuid
      responses:
        '200':
          description: List of assets
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'

  # Manifest endpoints
  /projects/{id}/manifest:
    get:
      operationId: getProjectManifest
      tags: [Manifest]
      summary: Get project manifest
      description: Returns the manifest for a project
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '301':
          description: Redirect to S3 manifest URL
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: upsertProjectManifest
      tags: [Manifest]
      summary: Upsert project manifest
      description: Creates or updates the manifest for a project
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                manifest:
                  type: object
      responses:
        '200':
          description: Manifest upserted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteProjectManifest
      tags: [Manifest]
      summary: Delete project manifest
      description: Deletes the manifest for a project
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Manifest deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'

  /manifests:
    get:
      operationId: getManifests
      tags: [Manifest]
      summary: Get all manifests
      description: Returns all manifests for the authenticated user
      responses:
        '200':
          description: List of manifests
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'

  /publics/{id}/manifest:
    get:
      operationId: getPublicProjectManifest
      tags: [Manifest]
      summary: Get public project manifest
      description: Returns the manifest for a public project
      security: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '301':
          description: Redirect to S3 manifest URL
        '404':
          $ref: '#/components/responses/NotFound'

  /templates/{id}/manifest:
    get:
      operationId: getTemplateManifest
      tags: [Manifest]
      summary: Get template manifest
      description: Returns the manifest for a template project
      security: []
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '301':
          description: Redirect to S3 manifest URL
        '404':
          $ref: '#/components/responses/NotFound'

  /pools/{id}/manifest:
    get:
      operationId: getPoolManifest
      tags: [Manifest]
      summary: Get pool manifest
      description: Returns the manifest for a pool
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '301':
          description: Redirect to S3 manifest URL
        '404':
          $ref: '#/components/responses/NotFound'

  # Deployment endpoints
  /deployments:
    get:
      operationId: getDeployments
      tags: [Deployments]
      summary: Get all deployments
      description: Returns all deployments for the authenticated user
      responses:
        '200':
          description: List of deployments
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'

  /projects/{id}/deployment:
    get:
      operationId: getProjectDeployment
      tags: [Deployments]
      summary: Get project deployment
      description: Returns deployment info for a project
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Deployment details
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: upsertProjectDeployment
      tags: [Deployments]
      summary: Create or update deployment
      description: Creates or updates deployment info for a project
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deployment:
                  type: object
      responses:
        '200':
          description: Deployment updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteProjectDeployment
      tags: [Deployments]
      summary: Delete deployment
      description: Deletes deployment info for a project
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Deployment deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  # Storage endpoints
  /storage/assetPacks/{filename}:
    get:
      operationId: getAssetPackFile
      tags: [Storage]
      summary: Get asset pack file
      description: Redirects to S3 URL for asset pack file
      security: []
      parameters:
        - name: filename
          in: path
          required: true
          schema:
            type: string
      responses:
        '301':
          description: Redirect to S3 URL

  /storage/contents/{hash}:
    get:
      operationId: getContentByHash
      tags: [Storage]
      summary: Get content by hash
      description: Redirects to S3 URL for content file
      security: []
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '301':
          description: Redirect to S3 URL
    head:
      operationId: getContentHeaders
      tags: [Storage]
      summary: Get content headers
      description: Returns headers for content file without body
      security: []
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '301':
          description: Redirect to S3 URL

  /storage/contents/{hash}/exists:
    get:
      operationId: checkContentExists
      tags: [Storage]
      summary: Check if content exists
      description: Returns whether a file exists in storage without downloading it
      security: []
      parameters:
        - name: hash
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: File exists
        '404':
          description: File does not exist

  /storage/upload:
    post:
      operationId: uploadContent
      tags: [Storage]
      summary: Upload content file
      description: Uploads a file to storage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                    properties:
                      hash:
                        type: string
        '401':
          $ref: '#/components/responses/Unauthorized'

  # Share endpoints
  /share/{type}/{id}:
    get:
      operationId: getSharePage
      tags: [Share]
      summary: Get share page
      description: Returns an HTML share page for a project or pool. Redirects to Builder if not a social agent.
      security: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum: [scene, pool]
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Share HTML page
          content:
            text/html:
              schema:
                type: string
        '301':
          description: Redirect to Builder URL
        '404':
          description: Resource not found

  # Analytics endpoints
  /analytics/weekly:
    get:
      operationId: getWeeklyAnalytics
      tags: [Analytics]
      summary: Get weekly analytics
      description: Returns weekly statistics
      security: []
      parameters:
        - name: base
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Weekly analytics data
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object

  /analytics/status:
    get:
      operationId: getAnalyticsStatus
      tags: [Analytics]
      summary: Get analytics status
      description: Returns current analytics status
      security: []
      responses:
        '200':
          description: Analytics status
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object

  # NFT endpoints
  /nfts:
    get:
      operationId: getNfts
      tags: [NFT]
      summary: Get NFTs
      description: Returns NFTs for an address
      security: []
      parameters:
        - name: owner
          in: query
          required: true
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
        - name: first
          in: query
          schema:
            type: integer
            minimum: 1
        - name: skip
          in: query
          schema:
            type: integer
            minimum: 0
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of NFTs
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /nfts/{contractAddress}/{tokenId}:
    get:
      operationId: getNft
      tags: [NFT]
      summary: Get single NFT
      description: Returns a specific NFT by contract address and token ID
      security: []
      parameters:
        - name: contractAddress
          in: path
          required: true
          schema:
            type: string
            pattern: '^0x[a-fA-F0-9]{40}$'
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: NFT details
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # LAND endpoints
  /lands/redirectionHashes:
    get:
      operationId: getRedirectionHashes
      tags: [LAND]
      summary: Get redirection hashes
      description: Returns IPFS hashes for LAND redirection files
      security: []
      parameters:
        - name: coords
          in: query
          required: true
          schema:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
      responses:
        '200':
          description: Redirection hashes
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        x:
                          type: integer
                        y:
                          type: integer
                        ipfsHash:
                          type: string
                        contentHash:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequest'

  /lands/{coords}/redirection:
    post:
      operationId: uploadLandRedirection
      tags: [LAND]
      summary: Upload LAND redirection
      description: Uploads a redirection file to IPFS
      security: []
      parameters:
        - name: coords
          in: path
          required: true
          schema:
            type: string
            pattern: '^-?[0-9]+,-?[0-9]+$'
      responses:
        '200':
          description: Redirection uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
                    properties:
                      ipfsHash:
                        type: string
                      contentHash:
                        type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  # Newsletter endpoints
  /newsletter:
    post:
      operationId: subscribeToNewsletter
      tags: [Newsletter]
      summary: Subscribe to newsletter
      description: Subscribes an email to the newsletter
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                source:
                  type: string
      responses:
        '200':
          description: Subscribed successfully

  /newsletter/{subscriptionId}:
    get:
      operationId: getNewsletterSubscription
      tags: [Newsletter]
      summary: Get subscription
      description: Returns a newsletter subscription by ID
      security: []
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  data:
                    type: object
    delete:
      operationId: deleteNewsletterSubscription
      tags: [Newsletter]
      summary: Delete subscription
      description: Deletes a newsletter subscription
      security: []
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Subscription deleted successfully

components:
  securitySchemes:
    SignedFetch:
      type: apiKey
      in: header
      name: X-Identity-Auth-Chain-*
      description: |
        Signed fetch authentication using Decentraland's ADR-44 specification.
        Multiple headers are used to provide the authentication chain.

  parameters:
    ProjectId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Project UUID

    CollectionId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Collection UUID

    ItemId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Item UUID

    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number for pagination

    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: Number of items per page

    Offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
      description: Offset for pagination

    SortBy:
      name: sort_by
      in: query
      schema:
        type: string
      description: Field to sort by

    SortOrder:
      name: sort_order
      in: query
      schema:
        type: string
        enum: [asc, desc]
      description: Sort order

  responses:
    BadRequest:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    Unauthorized:
      description: Unauthorized - authentication required or insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    Conflict:
      description: Conflict - resource already exists or is in an invalid state
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    Locked:
      description: Resource is locked and cannot be modified
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    ErrorResponse:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: string
        data:
          type: object

    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        thumbnail:
          type: string
        scene_id:
          type: string
          format: uuid
        eth_address:
          type: string
        cols:
          type: integer
        rows:
          type: integer
        parcels:
          type: integer
        transforms:
          type: integer
        gltf_shapes:
          type: integer
        nft_shapes:
          type: integer
        scripts:
          type: integer
        entities:
          type: integer
        is_deleted:
          type: boolean
        is_public:
          type: boolean
        is_template:
          type: boolean
        creation_coords:
          type: string
        template_status:
          type: string
          enum: [active, coming_soon]
        video:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ProjectInput:
      type: object
      required:
        - id
        - title
        - description
        - scene_id
        - cols
        - rows
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        thumbnail:
          type: string
        scene_id:
          type: string
          format: uuid
        cols:
          type: integer
        rows:
          type: integer
        is_public:
          type: boolean
        creation_coords:
          type: string
        is_template:
          type: boolean
        template_status:
          type: string
          enum: [active, coming_soon]
        video:
          type: string

    ProjectResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          $ref: '#/components/schemas/Project'

    ProjectListResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Project'

    Pool:
      type: object
      allOf:
        - $ref: '#/components/schemas/Project'
        - type: object
          properties:
            groups:
              type: array
              items:
                type: string
                format: uuid
            likes:
              type: integer
            like:
              type: boolean

    PoolResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          $ref: '#/components/schemas/Pool'

    PoolListResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Pool'

    PoolGroup:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Collection:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        eth_address:
          type: string
        salt:
          type: string
        contract_address:
          type: string
        urn:
          type: string
        is_published:
          type: boolean
        is_approved:
          type: boolean
        minters:
          type: array
          items:
            type: string
        managers:
          type: array
          items:
            type: string
        forum_link:
          type: string
        forum_id:
          type: integer
        lock:
          type: string
          format: date-time
        reviewed_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        curation_status:
          type: string
          nullable: true
          enum: [pending, approved, rejected]
          description: Status of the collection's latest review. Only in the creator's collection list.
        last_activity_at:
          type: string
          format: date-time
          description: Last time the collection, its items or its review changed. Only in the creator's collection list.

    CollectionInput:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        urn:
          type: string

    CollectionResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          $ref: '#/components/schemas/Collection'

    CollectionListResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/Collection'
            - $ref: '#/components/schemas/PaginatedResponse'

    AddressCollectionListResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/Collection'
            - allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    counts:
                      $ref: '#/components/schemas/CollectionStatusCounts'

    CollectionStatusCounts:
      type: object
      description: How many collections are in each status.
      properties:
        draft:
          type: integer
        under_review:
          type: integer
        published:
          type: integer
        rejected:
          type: integer
        disabled:
          type: integer

    Item:
      type: object
      properties:
        id:
          type: string
          format: uuid
        urn:
          type: string
        name:
          type: string
        description:
          type: string
        thumbnail:
          type: string
        video:
          type: string
        eth_address:
          type: string
        collection_id:
          type: string
          format: uuid
        blockchain_item_id:
          type: string
        price:
          type: string
        beneficiary:
          type: string
        rarity:
          type: string
          enum: [common, uncommon, rare, epic, legendary, mythic, unique]
        type:
          type: string
          enum: [wearable, emote]
        data:
          type: object
        metrics:
          type: object
        utility:
          type: string
        contents:
          type: object
          additionalProperties:
            type: string
        mappings:
          type: object
        is_published:
          type: boolean
        is_approved:
          type: boolean
        in_catalyst:
          type: boolean
        total_supply:
          type: integer
        content_hash:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ItemInput:
      type: object
      required:
        - id
        - name
        - description
        - rarity
        - type
        - data
        - contents
      properties:
        id:
          type: string
          format: uuid
        urn:
          type: string
        name:
          type: string
        description:
          type: string
        collection_id:
          type: string
          format: uuid
        rarity:
          type: string
        type:
          type: string
          enum: [wearable, emote]
        data:
          type: object
        contents:
          type: object
        utility:
          type: string
        mappings:
          type: object

    ItemResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          $ref: '#/components/schemas/Item'

    ItemListResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/Item'
            - $ref: '#/components/schemas/PaginatedResponse'

    ItemApprovalData:
      type: object
      properties:
        cheque:
          $ref: '#/components/schemas/Cheque'
        content_hashes:
          type: object
          additionalProperties:
            type: string
        chequeWasConsumed:
          type: boolean
        root:
          type: string

    Cheque:
      type: object
      properties:
        qty:
          type: integer
        salt:
          type: string
        signature:
          type: string

    CurationStatus:
      type: string
      enum: [pending, approved, rejected, to_review, under_review]

    CurationStatusFilter:
      type: string
      description: |
        A collection's review status. `to_review` is waiting for a curator, `under_review` has one assigned,
        `approved` and `rejected` carry the committee's latest decision, `disabled` was turned off by the
        committee after an approval. `pending` is the legacy name for a collection waiting for its first approval.
      enum: [pending, approved, rejected, to_review, under_review, disabled]

    CollectionCuration:
      type: object
      properties:
        id:
          type: string
          format: uuid
        collection_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/CurationStatus'
        assignee:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CollectionCurationResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          $ref: '#/components/schemas/CollectionCuration'

    ItemCuration:
      type: object
      properties:
        id:
          type: string
          format: uuid
        item_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/CurationStatus'
        content_hash:
          type: string
        is_mapping_complete:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ThirdParty:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        managers:
          type: array
          items:
            type: string
        maxItems:
          type: string
        totalItems:
          type: string
        contracts:
          type: array
          items:
            type: object

    Rarity:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        price:
          type: string
        maxSupply:
          type: string
        prices:
          type: object
          properties:
            MANA:
              type: string
            USD:
              type: string

    RarityResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          $ref: '#/components/schemas/Rarity'

    AssetPack:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        thumbnail:
          type: string
        eth_address:
          type: string
        assets:
          type: array
          items:
            $ref: '#/components/schemas/Asset'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    AssetPackInput:
      type: object
      required:
        - id
        - title
        - assets
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        assets:
          type: array
          items:
            $ref: '#/components/schemas/AssetInput'

    AssetPackResponse:
      type: object
      properties:
        ok:
          type: boolean
        data:
          $ref: '#/components/schemas/AssetPack'

    Asset:
      type: object
      properties:
        id:
          type: string
          format: uuid
        asset_pack_id:
          type: string
          format: uuid
        name:
          type: string
        model:
          type: string
        script:
          type: string
        thumbnail:
          type: string
        tags:
          type: array
          items:
            type: string
        category:
          type: string
        contents:
          type: object
        metrics:
          type: object
        parameters:
          type: array
        actions:
          type: array

    AssetInput:
      type: object
      required:
        - id
        - name
        - model
      properties:
        id:
          type: string
          format: uuid
        asset_pack_id:
          type: string
          format: uuid
        name:
          type: string
        model:
          type: string
        script:
          type: string
        thumbnail:
          type: string
        tags:
          type: array
          items:
            type: string
        category:
          type: string
        contents:
          type: object
        metrics:
          type: object

    PaginatedResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
        total:
          type: integer
        page:
          type: integer
        pages:
          type: integer
        limit:
          type: integer