{
  "openapi": "3.1.0",
  "info": {
    "title": "RepoCard API",
    "version": "1.0.0",
    "description": "AI-designed social preview images for GitHub repositories. Read-only: RepoCard never writes to GitHub. Agents can also use the MCP endpoint at /mcp.",
    "license": {
      "name": "MIT",
      "identifier": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://repocard.xyz"
    }
  ],
  "paths": {
    "/card/{owner}/{repo}.png": {
      "get": {
        "operationId": "getCardPng",
        "summary": "Render a social preview as PNG (1280x640).",
        "parameters": [
          {
            "name": "owner",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "GitHub user or organization."
          },
          {
            "name": "repo",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repository name."
          },
          {
            "name": "variant",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 4,
              "default": 1
            },
            "description": "Which AI concept to render."
          },
          {
            "name": "layout",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "spotlight",
                "split",
                "editorial",
                "terminal",
                "poster",
                "minimal"
              ]
            },
            "description": "Override the layout."
          },
          {
            "name": "palette",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "midnight",
                "obsidian",
                "aurora",
                "ember",
                "nebula",
                "ocean",
                "forest",
                "terminal",
                "crimson",
                "gold",
                "paper",
                "snow",
                "mint",
                "blush",
                "sand",
                "sky"
              ]
            },
            "description": "Override the palette."
          },
          {
            "name": "font",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "modern",
                "geometric",
                "technical",
                "editorial",
                "friendly",
                "expressive"
              ]
            },
            "description": "Override the font pairing."
          },
          {
            "name": "background",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "aurora",
                "grid",
                "dots",
                "diagonal",
                "rings",
                "solid"
              ]
            },
            "description": "Override the background."
          },
          {
            "name": "mark",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "avatar",
                "monogram",
                "emoji",
                "none"
              ]
            },
            "description": "Override the mark."
          },
          {
            "name": "emoji",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Emoji used with mark=emoji."
          },
          {
            "name": "accent",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^#?[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$"
            },
            "description": "Brand color."
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 48
            },
            "description": "Override the title."
          },
          {
            "name": "tagline",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 110
            },
            "description": "Override the tagline."
          },
          {
            "name": "chips",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated keywords."
          },
          {
            "name": "stats",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            },
            "description": "0 hides repository stats."
          },
          {
            "name": "owner",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            },
            "description": "0 hides the owner."
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "auto",
                "fast"
              ]
            },
            "description": "fast never calls the LLM."
          }
        ],
        "responses": {
          "200": {
            "description": "PNG image",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "4XX": {
            "description": "An error card (PNG) describing the problem",
            "content": {
              "image/png": {}
            }
          }
        }
      }
    },
    "/card/{owner}/{repo}.svg": {
      "get": {
        "operationId": "getCardSvg",
        "summary": "Render a social preview as SVG. Accepts the same parameters as the PNG endpoint.",
        "parameters": [
          {
            "name": "owner",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "GitHub user or organization."
          },
          {
            "name": "repo",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repository name."
          }
        ],
        "responses": {
          "200": {
            "description": "SVG image",
            "content": {
              "image/svg+xml": {}
            }
          }
        }
      }
    },
    "/api/v1/cards/{owner}/{repo}": {
      "get": {
        "operationId": "getDesigns",
        "summary": "Get the 4 design concepts for a repository, with image URLs and setup steps.",
        "parameters": [
          {
            "name": "owner",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "GitHub user or organization."
          },
          {
            "name": "repo",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Repository name."
          }
        ],
        "responses": {
          "200": {
            "description": "Design concepts"
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/cards": {
      "post": {
        "operationId": "createDesigns",
        "summary": "Create (or refresh) design concepts from any repository URL.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "repo"
                ],
                "properties": {
                  "repo": {
                    "type": "string",
                    "description": "owner/repo or github.com URL"
                  },
                  "refresh": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Design concepts"
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/users/{owner}/repos": {
      "get": {
        "operationId": "listAccountCards",
        "summary": "List public repositories for an account with card URLs and settings links.",
        "parameters": [
          {
            "name": "owner",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "GitHub user or organization."
          },
          {
            "name": "forks",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            },
            "description": "Include forks. Default 0."
          },
          {
            "name": "archived",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            },
            "description": "Include archived repositories. Default 0."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 300
            },
            "description": "Default 100."
          }
        ],
        "responses": {
          "200": {
            "description": "Repositories"
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/options": {
      "get": {
        "operationId": "getOptions",
        "summary": "List all design options.",
        "responses": {
          "200": {
            "description": "Options"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "health",
        "summary": "Health check.",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "Model Context Protocol endpoint (Streamable HTTP, JSON-RPC 2.0).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {}
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          },
          "202": {
            "description": "Notification accepted"
          }
        }
      }
    }
  }
}