{
  "openapi": "3.1.0",
  "info": {
    "title": "My Custom API — Admin",
    "version": "1.0.0",
    "description": "Manage public mock endpoints. Each token only sees its own set (user tokens: https://mycustomapi.online/api/u/<userId>/<slug>; ADMIN_TOKEN: https://mycustomapi.online/api/<slug>). Endpoints can optionally require an API key (see keys). See https://mycustomapi.online/llms.txt"
  },
  "servers": [
    {
      "url": "https://mycustomapi.online"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/_admin/me": {
      "get": {
        "operationId": "whoAmI",
        "summary": "Endpoint set managed by this token and its public URL prefix",
        "responses": {
          "200": {
            "description": "Scope",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "scope": {
                      "type": "string",
                      "enum": [
                        "global",
                        "user"
                      ]
                    },
                    "email": {
                      "type": "string"
                    },
                    "publicBase": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/_admin/keys": {
      "get": {
        "operationId": "listKeys",
        "summary": "List API keys (values are never returned)",
        "responses": {
          "200": {
            "description": "List",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ApiKey"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createKey",
        "summary": "Create an API key. The value is returned only in this response.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "value": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 200,
                    "description": "Optional; generated if omitted"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ApiKey"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "value": {
                          "type": "string"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/_admin/keys/{id}": {
      "delete": {
        "operationId": "deleteKey",
        "summary": "Delete an API key (409 if endpoints still use it)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted"
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/_admin/endpoints": {
      "get": {
        "operationId": "listEndpoints",
        "summary": "List all endpoints",
        "responses": {
          "200": {
            "description": "List",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Endpoint"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createEndpoint",
        "summary": "Create an endpoint",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EndpointInput"
                  },
                  {
                    "required": [
                      "slug",
                      "body"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Endpoint"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/_admin/endpoints/{slug}": {
      "parameters": [
        {
          "name": "slug",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Endpoint slug. URL-encode '/' as %2F or pass it as path segments."
        }
      ],
      "get": {
        "operationId": "getEndpoint",
        "summary": "Get one endpoint",
        "responses": {
          "200": {
            "description": "Endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Endpoint"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateEndpoint",
        "summary": "Partially update an endpoint (send slug to rename)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/EndpointInput"
                  },
                  {
                    "required": []
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Endpoint"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteEndpoint",
        "summary": "Delete an endpoint",
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "ADMIN_TOKEN or a personal user token (mca_…)"
      }
    },
    "schemas": {
      "EndpointInput": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "example": "users/list",
            "description": "Path after the public base returned by GET /_admin/me"
          },
          "method": {
            "type": "string",
            "enum": [
              "ANY",
              "GET",
              "POST",
              "PUT",
              "PATCH",
              "DELETE"
            ],
            "default": "ANY"
          },
          "status": {
            "type": "integer",
            "minimum": 200,
            "maximum": 599,
            "default": 200
          },
          "format": {
            "type": "string",
            "enum": [
              "json",
              "text",
              "html",
              "xml",
              "csv",
              "custom"
            ],
            "default": "json"
          },
          "contentType": {
            "type": "string",
            "description": "Required when format is 'custom'"
          },
          "body": {
            "type": "string",
            "description": "Raw response body. Valid JSON if format is 'json'."
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "delayMs": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000,
            "default": 0
          },
          "description": {
            "type": "string"
          },
          "protection": {
            "type": [
              "object",
              "null"
            ],
            "description": "Require an API key from /_admin/keys to call this endpoint. null/absent = public.",
            "properties": {
              "keyId": {
                "type": "string"
              },
              "header": {
                "type": "string",
                "default": "Authorization",
                "description": "Authorization expects 'Bearer <key>'; other headers expect the raw key."
              }
            },
            "required": [
              "keyId"
            ]
          }
        }
      },
      "Endpoint": {
        "allOf": [
          {
            "$ref": "#/components/schemas/EndpointInput"
          },
          {
            "type": "object",
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "hint": {
            "type": "string",
            "description": "Last 4 characters"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}