{
  "openapi": "3.1.0",
  "info": {
    "title": "Nexlayer API",
    "version": "1.0.0",
    "summary": "Deploy full-stack applications, agents and AI services to Nexlayer.",
    "description": "Nexlayer is an agent-native cloud. A single nexlayer.yaml describes a whole application \u2014 frontend, backend, databases, caches, vector stores, workers and GPU-backed AI services \u2014 and this API deploys it to production, multi-container infrastructure that stays on.\n\nMost agents should use the Model Context Protocol server at https://mcp.nexlayer.ai/api/mcp instead of calling these endpoints directly: it exposes the same capability as typed tools, handles auth, and needs no schema wiring. Install with `npx @nexlayer/mcp-install`.\n\nErrors are always JSON with an `error` message, and where available a stable `code` and a `hint` describing how to recover.",
    "contact": {
      "name": "Nexlayer",
      "url": "https://nexlayer.com/contact/sales",
      "email": "sales@nexlayer.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://nexlayer.com/legal/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.nexlayer.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Nexlayer API documentation",
    "url": "https://nexlayer.com/docs/api/deployments"
  },
  "tags": [
    {
      "name": "Deployments",
      "description": "Create, update, extend and claim deployments."
    },
    {
      "name": "Configuration",
      "description": "Validate a nexlayer.yaml and fetch its JSON Schema."
    }
  ],
  "security": [
    {
      "sessionToken": []
    }
  ],
  "paths": {
    "/startUserDeployment": {
      "post": {
        "operationId": "startDeployment",
        "tags": [
          "Deployments"
        ],
        "summary": "Deploy an application",
        "description": "Deploys a full-stack application from a nexlayer.yaml. Returns a live URL and a sessionToken used to manage the deployment. No account is required to start.",
        "security": [],
        "requestBody": {
          "required": true,
          "description": "A valid nexlayer.yaml configuration.",
          "content": {
            "text/x-yaml": {
              "schema": {
                "type": "string",
                "description": "nexlayer.yaml contents"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deployment started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Live application URL."
                    },
                    "sessionToken": {
                      "type": "string",
                      "description": "Token used to update, extend or claim this deployment."
                    },
                    "applicationName": {
                      "type": "string"
                    },
                    "environment": {
                      "type": "string"
                    },
                    "status": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "string",
                          "enum": [
                            "deploying",
                            "running",
                            "failed",
                            "expired"
                          ]
                        },
                        "progress": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100
                        }
                      }
                    },
                    "extend": {
                      "type": "object",
                      "properties": {
                        "available": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The nexlayer.yaml is invalid. Validate it first with validateConfig.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Retry after the interval in the Retry-After header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/updateUserDeployment": {
      "post": {
        "operationId": "updateDeployment",
        "tags": [
          "Deployments"
        ],
        "summary": "Update a running deployment",
        "description": "Applies an updated nexlayer.yaml to an existing deployment without changing its URL.",
        "parameters": [
          {
            "name": "sessionToken",
            "in": "query",
            "required": true,
            "description": "Session token returned by startDeployment.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "text/x-yaml": {
              "schema": {
                "type": "string"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update applied.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "status": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "string",
                          "enum": [
                            "deploying",
                            "running",
                            "failed",
                            "expired"
                          ]
                        },
                        "progress": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No deployment matches that session token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/extendDeployment": {
      "post": {
        "operationId": "extendDeployment",
        "tags": [
          "Deployments"
        ],
        "summary": "Extend a deployment's lifetime",
        "description": "Extends how long a free deployment stays live. A limited number of extensions is available per deployment.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "applicationName",
                  "sessionToken"
                ],
                "properties": {
                  "applicationName": {
                    "type": "string"
                  },
                  "sessionToken": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extended.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Application not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/claimDeployment": {
      "post": {
        "operationId": "claimDeployment",
        "tags": [
          "Deployments"
        ],
        "summary": "Claim a deployment permanently",
        "description": "Returns a claim URL that attaches a temporary deployment to an account so it stops expiring.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "applicationName",
                  "sessionToken"
                ],
                "properties": {
                  "applicationName": {
                    "type": "string"
                  },
                  "sessionToken": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claim URL issued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "claimUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "claimToken": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Application not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/getReservations": {
      "get": {
        "operationId": "listDeployments",
        "tags": [
          "Deployments"
        ],
        "summary": "List deployments for a session",
        "description": "Returns every deployment reserved under a session token, with its live URL and current state.",
        "parameters": [
          {
            "name": "sessionToken",
            "in": "query",
            "required": true,
            "description": "Session token returned by startDeployment.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deployments for the session.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reservedDeployments": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "applicationName": {
                            "type": "string"
                          },
                          "environment": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "status": {
                            "type": "object",
                            "properties": {
                              "state": {
                                "type": "string",
                                "enum": [
                                  "deploying",
                                  "running",
                                  "failed",
                                  "expired"
                                ]
                              },
                              "progress": {
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 100
                              }
                            }
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown session token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/validate": {
      "post": {
        "operationId": "validateConfig",
        "tags": [
          "Configuration"
        ],
        "summary": "Validate a nexlayer.yaml",
        "description": "Checks a nexlayer.yaml against the schema and returns errors before you attempt a deployment. Call this first when generating configuration programmatically.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "text/x-yaml": {
              "schema": {
                "type": "string"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": {
                      "type": "boolean"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The payload could not be parsed as YAML.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/schema": {
      "get": {
        "operationId": "getConfigSchema",
        "tags": [
          "Configuration"
        ],
        "summary": "Get the nexlayer.yaml JSON Schema",
        "description": "Returns the complete JSON Schema for nexlayer.yaml, so an agent can generate a valid configuration without guessing field names.",
        "security": [],
        "responses": {
          "200": {
            "description": "JSON Schema document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable reason the request failed."
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code."
          },
          "hint": {
            "type": "string",
            "description": "Suggested next step to resolve the error."
          }
        }
      }
    },
    "securitySchemes": {
      "sessionToken": {
        "type": "apiKey",
        "in": "query",
        "name": "sessionToken",
        "description": "Per-deployment token returned by startDeployment. It scopes access to that deployment only \u2014 it cannot read or modify any other deployment or account data."
      }
    }
  }
}