# 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_agpf42ylcfymdjwxy6nsjmtxky","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-05-25T09:15:34.033Z"}},"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_agpf42ylcfymdjwxy6nsjmtxky","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-05-25T09:15:34.033Z"}},"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_agpf42ylcfymdjwxy6nsjmtxky","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-05-25T09:15:34.033Z"}},"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_agpf42ylcfymdjwxy6nsjmtxky","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-05-25T09:15:34.033Z"}},"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_agpf42ylcfymdjwxy6nsjmtxky","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-05-25T09:15:34.033Z"}},"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_agpf42ylcfymdjwxz5xdhwquni","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-05-25T09:15:34.033Z"}}}}}},"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_agpf42ylcfymdjwxy6nsjmtxky","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-05-25T09:15:34.033Z"}},"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_agpf42ylcfymdjwxy6nsjmtxky","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-05-25T09:15:34.033Z"}},"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_agpf42ylcfymdjwxy6nsjmtxky","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-05-25T09:15:34.033Z"}},"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_agpf42ylcfymdjwxy6nsjmtxky","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-05-25T09:15:34.033Z"}},"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_agpf42ylcfymdjwxy6nsjmtxky","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-05-25T09:15:34.033Z"}},"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_agpf42ylcfymdjwx23ymfe63ca","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-05-25T09:15:34.033Z"}}}}}},"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"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.appear.sh/api/servers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.