{
  "openapi": "3.0.3",
  "info": {
    "title": "Digital Underground Developer Marketplace API",
    "version": "1.0.0",
    "description": "Public read endpoints for browsing approved Developer Marketplace listings (no auth), plus the Creator Listings API for submitting and managing your own listings (Bearer API key). Every new listing is screened and waits for human owner approval. MCP server: https://digitalundergroundstore.com/mcp. Human docs: https://digitalundergroundstore.com/community/api/"
  },
  "servers": [
    {
      "url": "https://digitalundergroundstore.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "duk_…"
      }
    },
    "schemas": {
      "Listing": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected",
              "unpublished"
            ]
          },
          "name": {
            "type": "string"
          },
          "stage": {
            "type": "string",
            "description": "Concept, In development, Beta / testing, Released or Discontinued"
          },
          "projectUrl": {
            "type": "string"
          },
          "pitchShort": {
            "type": "string"
          },
          "descriptionLong": {
            "type": "string"
          },
          "imageUrl": {
            "type": "string"
          },
          "videoUrl": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pendingVideo": {
            "type": "object",
            "nullable": true
          },
          "pendingRevision": {
            "type": "object",
            "nullable": true,
            "description": "An API edit to an approved listing waiting for owner approval (status: \"pending owner approval\"). The approved version stays live until the owner approves it."
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "createdAt": {
            "type": "integer"
          },
          "updatedAt": {
            "type": "integer"
          }
        }
      },
      "Create": {
        "type": "object",
        "required": [
          "name",
          "projectUrl",
          "category",
          "stage",
          "pitchShort",
          "descriptionLong",
          "terms"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 120
          },
          "projectUrl": {
            "type": "string",
            "format": "uri",
            "description": "https link to the product (checkout stays on your site)"
          },
          "category": {
            "type": "string",
            "enum": [
              "apps",
              "ai-tools",
              "games",
              "books",
              "templates",
              "other"
            ]
          },
          "pitchShort": {
            "type": "string",
            "maxLength": 280,
            "description": "One-sentence tagline"
          },
          "descriptionLong": {
            "type": "string",
            "maxLength": 4000
          },
          "stage": {
            "type": "string",
            "enum": [
              "concept",
              "development",
              "beta",
              "released",
              "discontinued"
            ],
            "description": "Required. Listing stage: concept, development (In development), beta (Beta / testing), released or discontinued. Labels are also accepted."
          },
          "priceLabel": {
            "type": "string",
            "maxLength": 40,
            "example": "$9"
          },
          "tags": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "maxItems": 6
              },
              {
                "type": "string"
              }
            ]
          },
          "makerName": {
            "type": "string",
            "maxLength": 80,
            "description": "Defaults to your account name"
          },
          "xHandle": {
            "type": "string",
            "maxLength": 16
          },
          "imageUrl": {
            "type": "string",
            "description": "https image URL (required unless imageData is sent)"
          },
          "imageData": {
            "type": "string",
            "description": "data:image/(jpeg|png|webp|gif);base64,... max ~750 KB"
          },
          "videoUrl": {
            "type": "string",
            "description": "Optional https YouTube/Vimeo/.mp4/.webm link; goes live after owner review"
          },
          "terms": {
            "type": "boolean",
            "description": "Must be true: you accept the listing terms at /community/submit/"
          }
        }
      },
      "Update": {
        "type": "object",
        "description": "Send only the fields you want to change.",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 120
          },
          "projectUrl": {
            "type": "string",
            "format": "uri",
            "description": "https link to the product (checkout stays on your site)"
          },
          "pitchShort": {
            "type": "string",
            "maxLength": 280,
            "description": "One-sentence tagline"
          },
          "descriptionLong": {
            "type": "string",
            "maxLength": 4000
          },
          "stage": {
            "type": "string",
            "enum": [
              "concept",
              "development",
              "beta",
              "released",
              "discontinued"
            ],
            "description": "Required. Listing stage: concept, development (In development), beta (Beta / testing), released or discontinued. Labels are also accepted."
          },
          "tags": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "maxItems": 6
              },
              {
                "type": "string"
              }
            ]
          },
          "imageUrl": {
            "type": "string",
            "description": "https image URL (required unless imageData is sent)"
          },
          "imageData": {
            "type": "string",
            "description": "data:image/(jpeg|png|webp|gif);base64,... max ~750 KB"
          },
          "videoUrl": {
            "type": "string",
            "description": "Optional https YouTube/Vimeo/.mp4/.webm link; goes live after owner review"
          },
          "removeMedia": {
            "type": "boolean"
          }
        }
      },
      "PublicListing": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "makerName": {
            "type": "string"
          },
          "xHandle": {
            "type": "string",
            "nullable": true
          },
          "category": {
            "type": "string"
          },
          "priceLabel": {
            "type": "string"
          },
          "pitchShort": {
            "type": "string"
          },
          "imageUrl": {
            "type": "string"
          },
          "visitUrl": {
            "type": "string"
          },
          "projectUrl": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "video": {
            "type": "object",
            "nullable": true
          }
        }
      },
      "PublicListingDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PublicListing"
          },
          {
            "type": "object",
            "properties": {
              "descriptionLong": {
                "type": "string"
              }
            }
          }
        ]
      }
    }
  },
  "security": [
    {
      "bearer": []
    }
  ],
  "paths": {
    "/api/community/listing": {
      "get": {
        "operationId": "getPublicListing",
        "summary": "One approved listing with full description (public, no auth)",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^cm_[a-z0-9_]{4,40}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "listing": {
                      "$ref": "#/components/schemas/PublicListingDetail"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/community/listings": {
      "get": {
        "operationId": "browseListings",
        "summary": "All approved marketplace listings (public, no auth)",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "listings": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PublicListing"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/listings": {
      "get": {
        "operationId": "listMyListings",
        "summary": "List your listings",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "listings": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Listing"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createListing",
        "summary": "Submit a new listing (goes to the review queue)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Create"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created (status pending or rejected)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "listing": {
                      "$ref": "#/components/schemas/Listing"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/listings/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "getListing",
        "summary": "Get one of your listings and its review status",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "listing": {
                      "$ref": "#/components/schemas/Listing"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateListing",
        "summary": "Update one of your listings (re-screened)",
        "description": "Edits to a listing that is not yet approved update it in place and it stays in the owner queue. Edits to an approved listing are stored as a pending revision: the approved version stays live unchanged, the response is 202 with status \"pending owner approval\", and the owner approves (applies) or rejects (discards) it. A newer edit replaces an older pending revision. 422 means the edit failed screening.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated (listing was not yet approved; still waiting for owner approval)"
          },
          "202": {
            "description": "Edit to an approved listing saved as a pending revision: pending owner approval"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}