> For the complete documentation index, see [llms.txt](https://docs.appear.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appear.sh/api/servers.md).

# Servers

## List Servers

> List all Servers items.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"versionId":{"schema":{"$ref":"#/components/schemas/versionId"},"required":true,"description":"Catalog version identifier","in":"path","name":"versionId"}},"schemas":{"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Catalog version identifier"},"Server":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6ss7d6dtqk4","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}},"required":["url","versionId"],"description":"Server is an URL endpoint template attached to a service, path, or operation, including variables when needed."},"ServerVariable":{"type":"object","properties":{"enum":{"type":"array","items":{"type":"string"},"minItems":1},"default":{"type":"string"},"description":{"type":"string"}},"required":["default"],"description":"Variable in the server URL, with a default value and optional allowed values."},"PaginationMetadata":{"type":"object","properties":{"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["nextCursor","hasMore","limit"],"description":"Pagination metadata"}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/versions/{versionId}/servers":{"get":{"summary":"List Servers","description":"List all Servers items.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"list-servers","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","description":"Cursor for pagination (item ID)"},"required":false,"description":"Cursor for pagination (item ID)","name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":50,"description":"Maximum number of items to return (default: 50, max: 1000)"},"required":false,"description":"Maximum number of items to return (default: 50, max: 1000)","name":"limit","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Sort order. Use 'prop' for ascending, '-prop' for descending. Multiple params supported (e.g. sort=name&sort=-createdAt)"},"required":false,"description":"Sort order. Use 'prop' for ascending, '-prop' for descending. Multiple params supported (e.g. sort=name&sort=-createdAt)","name":"sort","in":"query"}],"responses":{"200":{"description":"List of Servers","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Server"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["items","pagination"],"description":"Servers collection"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Create Server

> Create a new Server item.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"versionId":{"schema":{"$ref":"#/components/schemas/versionId"},"required":true,"description":"Catalog version identifier","in":"path","name":"versionId"}},"schemas":{"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Catalog version identifier"},"Server":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6ss7d6dtqk4","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}},"required":["url","versionId"],"description":"Server is an URL endpoint template attached to a service, path, or operation, including variables when needed."},"ServerVariable":{"type":"object","properties":{"enum":{"type":"array","items":{"type":"string"},"minItems":1},"default":{"type":"string"},"description":{"type":"string"}},"required":["default"],"description":"Variable in the server URL, with a default value and optional allowed values."}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ConflictError":{"description":"Conflict","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/versions/{versionId}/servers":{"post":{"summary":"Create Server","description":"Create a new Server item.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"create-server","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/versionId"}],"requestBody":{"description":"Payload to create a new Server item","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"responses":{"201":{"description":"Server created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"409":{"$ref":"#/components/responses/ConflictError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Get Server

> Get a Server item by its id.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"versionId":{"schema":{"$ref":"#/components/schemas/versionId"},"required":true,"description":"Catalog version identifier","in":"path","name":"versionId"}},"schemas":{"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Catalog version identifier"},"Server":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6ss7d6dtqk4","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}},"required":["url","versionId"],"description":"Server is an URL endpoint template attached to a service, path, or operation, including variables when needed."},"ServerVariable":{"type":"object","properties":{"enum":{"type":"array","items":{"type":"string"},"minItems":1},"default":{"type":"string"},"description":{"type":"string"}},"required":["default"],"description":"Variable in the server URL, with a default value and optional allowed values."}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"NotFoundErrorServer":{"description":"Server not found","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/versions/{versionId}/servers/{id}":{"get":{"summary":"Get Server","description":"Get a Server item by its id.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"get-server-by-id","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Server identifier"},"required":true,"description":"Server identifier","name":"id","in":"path"}],"responses":{"200":{"description":"Server details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorServer"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Replace Server

> Completely replaces a Server item by its id.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"versionId":{"schema":{"$ref":"#/components/schemas/versionId"},"required":true,"description":"Catalog version identifier","in":"path","name":"versionId"}},"schemas":{"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Catalog version identifier"},"Server":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6ss7d6dtqk4","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}},"required":["url","versionId"],"description":"Server is an URL endpoint template attached to a service, path, or operation, including variables when needed."},"ServerVariable":{"type":"object","properties":{"enum":{"type":"array","items":{"type":"string"},"minItems":1},"default":{"type":"string"},"description":{"type":"string"}},"required":["default"],"description":"Variable in the server URL, with a default value and optional allowed values."}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"NotFoundErrorServer":{"description":"Server not found","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/versions/{versionId}/servers/{id}":{"post":{"summary":"Replace Server","description":"Completely replaces a Server item by its id.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"replace-server-by-id","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Server identifier"},"required":true,"description":"Server identifier","name":"id","in":"path"}],"requestBody":{"description":"Payload to replace the Server item by its id","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"responses":{"200":{"description":"Server replaced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"201":{"description":"Server created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorServer"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Delete Server

> Delete a Server item by its id.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"versionId":{"schema":{"$ref":"#/components/schemas/versionId"},"required":true,"description":"Catalog version identifier","in":"path","name":"versionId"}},"schemas":{"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Catalog version identifier"}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"NotFoundErrorServer":{"description":"Server not found","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/versions/{versionId}/servers/{id}":{"delete":{"summary":"Delete Server","description":"Delete a Server item by its id.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"delete-server-by-id","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Server identifier"},"required":true,"description":"Server identifier","name":"id","in":"path"}],"responses":{"204":{"description":"Server deleted"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorServer"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Update Server

> Partially updates a Server item by its id.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"versionId":{"schema":{"$ref":"#/components/schemas/versionId"},"required":true,"description":"Catalog version identifier","in":"path","name":"versionId"}},"schemas":{"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Catalog version identifier"},"ServerVariable":{"type":"object","properties":{"enum":{"type":"array","items":{"type":"string"},"minItems":1},"default":{"type":"string"},"description":{"type":"string"}},"required":["default"],"description":"Variable in the server URL, with a default value and optional allowed values."},"Server":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6ss7d6dtqk4","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}},"required":["url","versionId"],"description":"Server is an URL endpoint template attached to a service, path, or operation, including variables when needed."}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"NotFoundErrorServer":{"description":"Server not found","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/versions/{versionId}/servers/{id}":{"patch":{"summary":"Update Server","description":"Partially updates a Server item by its id.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"update-server-by-id","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Server identifier"},"required":true,"description":"Server identifier","name":"id","in":"path"}],"requestBody":{"description":"Partial payload to update the Server item by its id","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6tz2wegacie","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}}}}}},"responses":{"200":{"description":"Server updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorServer"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## List Servers

> List all Servers items.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"projectRef":{"schema":{"$ref":"#/components/schemas/projectRef"},"required":true,"description":"Project slug or project id (proj_*)","in":"path","name":"projectRef"},"versionType":{"schema":{"$ref":"#/components/schemas/versionType"},"required":true,"description":"Version type, can be either 'branch' or 'environment'","in":"path","name":"versionType"},"versionSlug":{"schema":{"$ref":"#/components/schemas/versionSlug"},"required":true,"description":"Version slug","in":"path","name":"versionSlug"}},"schemas":{"projectRef":{"anyOf":[{"type":"string","minLength":31,"maxLength":31,"description":"Object ID with prefix \"proj_\""},{"type":"string","minLength":1}],"description":"Project slug or project id (proj_*)"},"versionType":{"type":"string","enum":["branch","environment"],"description":"Version type, can be either 'branch' or 'environment'"},"versionSlug":{"type":"string","minLength":1,"description":"Version slug"},"Server":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6ss7d6dtqk4","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}},"required":["url","versionId"],"description":"Server is an URL endpoint template attached to a service, path, or operation, including variables when needed."},"ServerVariable":{"type":"object","properties":{"enum":{"type":"array","items":{"type":"string"},"minItems":1},"default":{"type":"string"},"description":{"type":"string"}},"required":["default"],"description":"Variable in the server URL, with a default value and optional allowed values."},"PaginationMetadata":{"type":"object","properties":{"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"limit":{"type":"number"}},"required":["nextCursor","hasMore","limit"],"description":"Pagination metadata"}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/servers":{"get":{"summary":"List Servers","description":"List all Servers items.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"list-servers1","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","description":"Cursor for pagination (item ID)"},"required":false,"description":"Cursor for pagination (item ID)","name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":50,"description":"Maximum number of items to return (default: 50, max: 1000)"},"required":false,"description":"Maximum number of items to return (default: 50, max: 1000)","name":"limit","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Sort order. Use 'prop' for ascending, '-prop' for descending. Multiple params supported (e.g. sort=name&sort=-createdAt)"},"required":false,"description":"Sort order. Use 'prop' for ascending, '-prop' for descending. Multiple params supported (e.g. sort=name&sort=-createdAt)","name":"sort","in":"query"}],"responses":{"200":{"description":"List of Servers","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Server"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["items","pagination"],"description":"Servers collection"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Create Server

> Create a new Server item.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"projectRef":{"schema":{"$ref":"#/components/schemas/projectRef"},"required":true,"description":"Project slug or project id (proj_*)","in":"path","name":"projectRef"},"versionType":{"schema":{"$ref":"#/components/schemas/versionType"},"required":true,"description":"Version type, can be either 'branch' or 'environment'","in":"path","name":"versionType"},"versionSlug":{"schema":{"$ref":"#/components/schemas/versionSlug"},"required":true,"description":"Version slug","in":"path","name":"versionSlug"}},"schemas":{"projectRef":{"anyOf":[{"type":"string","minLength":31,"maxLength":31,"description":"Object ID with prefix \"proj_\""},{"type":"string","minLength":1}],"description":"Project slug or project id (proj_*)"},"versionType":{"type":"string","enum":["branch","environment"],"description":"Version type, can be either 'branch' or 'environment'"},"versionSlug":{"type":"string","minLength":1,"description":"Version slug"},"Server":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6ss7d6dtqk4","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}},"required":["url","versionId"],"description":"Server is an URL endpoint template attached to a service, path, or operation, including variables when needed."},"ServerVariable":{"type":"object","properties":{"enum":{"type":"array","items":{"type":"string"},"minItems":1},"default":{"type":"string"},"description":{"type":"string"}},"required":["default"],"description":"Variable in the server URL, with a default value and optional allowed values."}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ConflictError":{"description":"Conflict","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/servers":{"post":{"summary":"Create Server","description":"Create a new Server item.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"create-server1","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"}],"requestBody":{"description":"Payload to create a new Server item","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"responses":{"201":{"description":"Server created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"409":{"$ref":"#/components/responses/ConflictError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Get Server

> Get a Server item by its id.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"projectRef":{"schema":{"$ref":"#/components/schemas/projectRef"},"required":true,"description":"Project slug or project id (proj_*)","in":"path","name":"projectRef"},"versionType":{"schema":{"$ref":"#/components/schemas/versionType"},"required":true,"description":"Version type, can be either 'branch' or 'environment'","in":"path","name":"versionType"},"versionSlug":{"schema":{"$ref":"#/components/schemas/versionSlug"},"required":true,"description":"Version slug","in":"path","name":"versionSlug"}},"schemas":{"projectRef":{"anyOf":[{"type":"string","minLength":31,"maxLength":31,"description":"Object ID with prefix \"proj_\""},{"type":"string","minLength":1}],"description":"Project slug or project id (proj_*)"},"versionType":{"type":"string","enum":["branch","environment"],"description":"Version type, can be either 'branch' or 'environment'"},"versionSlug":{"type":"string","minLength":1,"description":"Version slug"},"Server":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6ss7d6dtqk4","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}},"required":["url","versionId"],"description":"Server is an URL endpoint template attached to a service, path, or operation, including variables when needed."},"ServerVariable":{"type":"object","properties":{"enum":{"type":"array","items":{"type":"string"},"minItems":1},"default":{"type":"string"},"description":{"type":"string"}},"required":["default"],"description":"Variable in the server URL, with a default value and optional allowed values."}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"NotFoundErrorServer":{"description":"Server not found","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/servers/{id}":{"get":{"summary":"Get Server","description":"Get a Server item by its id.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"get-server-by-id1","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Server identifier"},"required":true,"description":"Server identifier","name":"id","in":"path"}],"responses":{"200":{"description":"Server details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorServer"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Replace Server

> Completely replaces a Server item by its id.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"projectRef":{"schema":{"$ref":"#/components/schemas/projectRef"},"required":true,"description":"Project slug or project id (proj_*)","in":"path","name":"projectRef"},"versionType":{"schema":{"$ref":"#/components/schemas/versionType"},"required":true,"description":"Version type, can be either 'branch' or 'environment'","in":"path","name":"versionType"},"versionSlug":{"schema":{"$ref":"#/components/schemas/versionSlug"},"required":true,"description":"Version slug","in":"path","name":"versionSlug"}},"schemas":{"projectRef":{"anyOf":[{"type":"string","minLength":31,"maxLength":31,"description":"Object ID with prefix \"proj_\""},{"type":"string","minLength":1}],"description":"Project slug or project id (proj_*)"},"versionType":{"type":"string","enum":["branch","environment"],"description":"Version type, can be either 'branch' or 'environment'"},"versionSlug":{"type":"string","minLength":1,"description":"Version slug"},"Server":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6ss7d6dtqk4","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}},"required":["url","versionId"],"description":"Server is an URL endpoint template attached to a service, path, or operation, including variables when needed."},"ServerVariable":{"type":"object","properties":{"enum":{"type":"array","items":{"type":"string"},"minItems":1},"default":{"type":"string"},"description":{"type":"string"}},"required":["default"],"description":"Variable in the server URL, with a default value and optional allowed values."}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"NotFoundErrorServer":{"description":"Server not found","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/servers/{id}":{"post":{"summary":"Replace Server","description":"Completely replaces a Server item by its id.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"replace-server-by-id1","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Server identifier"},"required":true,"description":"Server identifier","name":"id","in":"path"}],"requestBody":{"description":"Payload to replace the Server item by its id","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"responses":{"200":{"description":"Server replaced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"201":{"description":"Server created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorServer"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Delete Server

> Delete a Server item by its id.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"projectRef":{"schema":{"$ref":"#/components/schemas/projectRef"},"required":true,"description":"Project slug or project id (proj_*)","in":"path","name":"projectRef"},"versionType":{"schema":{"$ref":"#/components/schemas/versionType"},"required":true,"description":"Version type, can be either 'branch' or 'environment'","in":"path","name":"versionType"},"versionSlug":{"schema":{"$ref":"#/components/schemas/versionSlug"},"required":true,"description":"Version slug","in":"path","name":"versionSlug"}},"schemas":{"projectRef":{"anyOf":[{"type":"string","minLength":31,"maxLength":31,"description":"Object ID with prefix \"proj_\""},{"type":"string","minLength":1}],"description":"Project slug or project id (proj_*)"},"versionType":{"type":"string","enum":["branch","environment"],"description":"Version type, can be either 'branch' or 'environment'"},"versionSlug":{"type":"string","minLength":1,"description":"Version slug"}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"NotFoundErrorServer":{"description":"Server not found","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/servers/{id}":{"delete":{"summary":"Delete Server","description":"Delete a Server item by its id.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"delete-server-by-id1","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Server identifier"},"required":true,"description":"Server identifier","name":"id","in":"path"}],"responses":{"204":{"description":"Server deleted"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorServer"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Update Server

> Partially updates a Server item by its id.\
> \
> Server is an URL endpoint template attached to a service, path, or operation, including variables when needed.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Servers"}],"servers":[{"url":"https://api.appear.sh","description":"Primary public endpoint"}],"security":[{"projectApiKey":[]},{"personalAccessToken":[]}],"components":{"securitySchemes":{"projectApiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Project API key authentication. Use your project API key as a Bearer token in the Authorization header."},"personalAccessToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Personal access token authentication. Use your personal access token as a Bearer token in the Authorization header. Suitable for MCP integrations, CLI tools, and other OAuth flows."}},"parameters":{"projectRef":{"schema":{"$ref":"#/components/schemas/projectRef"},"required":true,"description":"Project slug or project id (proj_*)","in":"path","name":"projectRef"},"versionType":{"schema":{"$ref":"#/components/schemas/versionType"},"required":true,"description":"Version type, can be either 'branch' or 'environment'","in":"path","name":"versionType"},"versionSlug":{"schema":{"$ref":"#/components/schemas/versionSlug"},"required":true,"description":"Version slug","in":"path","name":"versionSlug"}},"schemas":{"projectRef":{"anyOf":[{"type":"string","minLength":31,"maxLength":31,"description":"Object ID with prefix \"proj_\""},{"type":"string","minLength":1}],"description":"Project slug or project id (proj_*)"},"versionType":{"type":"string","enum":["branch","environment"],"description":"Version type, can be either 'branch' or 'environment'"},"versionSlug":{"type":"string","minLength":1,"description":"Version slug"},"ServerVariable":{"type":"object","properties":{"enum":{"type":"array","items":{"type":"string"},"minItems":1},"default":{"type":"string"},"description":{"type":"string"}},"required":["default"],"description":"Variable in the server URL, with a default value and optional allowed values."},"Server":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6ss7d6dtqk4","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}},"required":["url","versionId"],"description":"Server is an URL endpoint template attached to a service, path, or operation, including variables when needed."}},"responses":{"BadRequestError":{"description":"Invalid request","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"NotFoundErrorServer":{"description":"Server not found","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"},"details":{}},"required":["error"],"additionalProperties":false}}}}}},"paths":{"/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/servers/{id}":{"patch":{"summary":"Update Server","description":"Partially updates a Server item by its id.\n\nServer is an URL endpoint template attached to a service, path, or operation, including variables when needed.","operationId":"update-server-by-id1","tags":["Servers"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Server identifier"},"required":true,"description":"Server identifier","name":"id","in":"path"}],"requestBody":{"description":"Partial payload to update the Server item by its id","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"srv_agpzwhz73fyz3hi6u2emsxzxay","description":"Object ID with prefix \"srv_\""},"serviceId":{"type":"string","minLength":30,"maxLength":30,"description":"Server scoped to a service; cannot be combined with pathId or operationId."},"pathId":{"type":"string","minLength":31,"maxLength":31,"description":"Server scoped to a specific path; cannot be combined with serviceId or operationId."},"operationId":{"type":"string","minLength":29,"maxLength":29,"description":"Server scoped to a single operation; cannot be combined with serviceId or pathId."},"url":{"type":"string","description":"Base URL template for calling the API (may include `{variable}` placeholders)."},"description":{"type":"string","description":"Markdown description of the server."},"variables":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ServerVariable"},"default":{},"description":"Map of variables that the server URL template expects."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata preserved with the server definition."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"}}}}}},"responses":{"200":{"description":"Server updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Server"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorServer"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```