{
  "openapi": "3.1.0",
  "info": {
    "title": "Phoenix Labs API",
    "version": "1.5.0"
  },
  "servers": [
    {
      "url": "https://galaphoenixlabs.com"
    }
  ],
  "security": [
    {
      "ContributorKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ContributorKey": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "ProjectCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "description"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,63}$"
          },
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "description": {
            "type": "string",
            "maxLength": 5000
          },
          "stage": {
            "type": "string",
            "enum": [
              "grave",
              "lab",
              "risen",
              "wishlist"
            ]
          },
          "projectType": {
            "type": "string",
            "enum": [
              "game",
              "nft-collection"
            ],
            "default": "game"
          },
          "logo": {
            "type": "string"
          },
          "genre": {
            "type": "string"
          },
          "known": {
            "type": "string"
          },
          "launch": {
            "type": "string"
          },
          "ended": {
            "type": "string"
          },
          "history": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "artworkUrl": {
            "type": "string"
          },
          "sources": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": [
                "label",
                "url"
              ],
              "properties": {
                "label": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "pattern": "^https://"
                }
              }
            }
          },
          "prototypes": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": [
                "label",
                "url"
              ],
              "properties": {
                "label": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "pattern": "^https://"
                }
              }
            },
            "description": "Public HTTPS prototype links. New URLs on published projects create a community feed announcement automatically; repeated URLs do not duplicate it."
          },
          "metrics": {
            "type": "array",
            "maxItems": 30,
            "items": {
              "type": "object",
              "required": [
                "label",
                "value"
              ],
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "number"
                  ]
                },
                "asOf": {
                  "type": "string"
                },
                "sourceUrl": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "developmentUpdates": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "required": [
                "title",
                "description",
                "date"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "date": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ProjectUpdate": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,63}$"
          },
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "description": {
            "type": "string",
            "maxLength": 5000
          },
          "stage": {
            "type": "string",
            "enum": [
              "grave",
              "lab",
              "risen",
              "wishlist"
            ]
          },
          "projectType": {
            "type": "string",
            "enum": [
              "game",
              "nft-collection"
            ],
            "default": "game"
          },
          "logo": {
            "type": "string"
          },
          "genre": {
            "type": "string"
          },
          "known": {
            "type": "string"
          },
          "launch": {
            "type": "string"
          },
          "ended": {
            "type": "string"
          },
          "history": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "artworkUrl": {
            "type": "string"
          },
          "sources": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": [
                "label",
                "url"
              ],
              "properties": {
                "label": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "pattern": "^https://"
                }
              }
            }
          },
          "prototypes": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": [
                "label",
                "url"
              ],
              "properties": {
                "label": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "pattern": "^https://"
                }
              }
            },
            "description": "Public HTTPS prototype links. New URLs on published projects create a community feed announcement automatically; repeated URLs do not duplicate it."
          },
          "metrics": {
            "type": "array",
            "maxItems": 30,
            "items": {
              "type": "object",
              "required": [
                "label",
                "value"
              ],
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "string",
                    "number"
                  ]
                },
                "asOf": {
                  "type": "string"
                },
                "sourceUrl": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "developmentUpdates": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "required": [
                "title",
                "description",
                "date"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "date": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/projects": {
      "get": {
        "summary": "List contributor projects",
        "responses": {
          "200": {
            "description": "Project collection"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing, invalid, or revoked API key"
          },
          "403": {
            "description": "Project belongs to another contributor key"
          },
          "404": {
            "description": "Project not found"
          },
          "409": {
            "description": "Duplicate project ID"
          },
          "413": {
            "description": "Request too large"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      },
      "post": {
        "summary": "Create a project; real burns disabled by default",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProjectCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Project created"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing, invalid, or revoked API key"
          },
          "403": {
            "description": "Project belongs to another contributor key"
          },
          "404": {
            "description": "Project not found"
          },
          "409": {
            "description": "Duplicate project ID"
          },
          "413": {
            "description": "Request too large"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api/v1/projects/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "Read a project",
        "responses": {
          "200": {
            "description": "Project data"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing, invalid, or revoked API key"
          },
          "403": {
            "description": "Project belongs to another contributor key"
          },
          "404": {
            "description": "Project not found"
          },
          "409": {
            "description": "Duplicate project ID"
          },
          "413": {
            "description": "Request too large"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      },
      "patch": {
        "summary": "Update a project created by this key",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProjectUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Project updated"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing, invalid, or revoked API key"
          },
          "403": {
            "description": "Project belongs to another contributor key"
          },
          "404": {
            "description": "Project not found"
          },
          "409": {
            "description": "Duplicate project ID"
          },
          "413": {
            "description": "Request too large"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      },
      "delete": {
        "summary": "Delete a project created by this key",
        "description": "Removes the public listing and disables new burns. Cancels unsigned prepared requests. Historical records and submitted transactions are retained. Repeating deletion with the owner key succeeds. The project ID cannot be reused.",
        "responses": {
          "200": {
            "description": "Project removed; history preserved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "const": true
                    },
                    "id": {
                      "type": "string"
                    },
                    "deletedAt": {
                      "type": "integer"
                    },
                    "historyPreserved": {
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing, invalid, or revoked API key"
          },
          "403": {
            "description": "Project belongs to another contributor key"
          },
          "404": {
            "description": "Project not found"
          },
          "409": {
            "description": "Duplicate project ID"
          },
          "413": {
            "description": "Request too large"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api/phoenix/leaderboard": {
      "get": {
        "summary": "Public per-game community leaderboards",
        "security": [],
        "parameters": [
          {
            "name": "game",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "walking-dead"
          }
        ],
        "description": "Top 100 all-time verified accounts. Top voters counts confirmed gross GALA voting weight across linked wallets. Most supported counts others’ confirmed backing of eligible recommendations, excluding self-support. Private account identifiers are omitted.",
        "responses": {
          "200": {
            "description": "Public game rankings and readable recommendations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "game",
                    "period",
                    "limit",
                    "basis",
                    "topVoters",
                    "mostSupported"
                  ],
                  "properties": {
                    "game": {
                      "type": "string"
                    },
                    "period": {
                      "const": "all-time"
                    },
                    "limit": {
                      "const": 100
                    },
                    "basis": {
                      "const": "confirmed-gross-contribution"
                    },
                    "topVoters": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "mostSupported": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Game not found or not public"
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "summary": "Read dashboard statistics with a stats:read API key",
        "description": "Read-only. Requires a Stats only or Projects & stats key. Existing contributor keys retain their previous scopes. Traffic is approximate; confirmed financial records are authoritative. Some fields are explicitly all-time. 60 requests/minute/key.",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                7,
                30,
                90
              ],
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dashboard metrics summary (kpis, daily, networks, leaders, eventCounts, burnErrors, statuses, alerts, recentBurns)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid reporting period"
          },
          "401": {
            "description": "Missing or revoked key"
          },
          "403": {
            "description": "Key lacks stats:read"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api/phoenix/prototypes": {
      "get": {
        "summary": "List a public game’s prototypes by confirmed GALA voting weight",
        "security": [],
        "parameters": [
          {
            "name": "game",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published prototype collection"
          },
          "404": {
            "description": "Game not public"
          }
        }
      },
      "post": {
        "summary": "Post a prototype as a guest from the website",
        "security": [],
        "description": "Same-origin JSON request. Server establishes a guest session; no wallet required. HTTPS public link and rights confirmation required. Five submissions/hour/identity plus per-connection guest limits. Creates one feed announcement atomically.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "game",
                  "title",
                  "url",
                  "description",
                  "clientKey",
                  "rightsConfirmed"
                ],
                "properties": {
                  "game": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 100
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "description": {
                    "type": "string",
                    "minLength": 20,
                    "maxLength": 2000
                  },
                  "clientKey": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "displayName": {
                    "type": "string",
                    "maxLength": 32
                  },
                  "rightsConfirmed": {
                    "const": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Posted or idempotent retry"
          },
          "400": {
            "description": "Invalid submission"
          },
          "403": {
            "description": "Foreign origin"
          },
          "409": {
            "description": "Duplicate link or retry identifier conflict"
          },
          "429": {
            "description": "Submission rate limit"
          }
        }
      }
    }
  }
}