# Services

## List Services

> List all Services items.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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"},"Service":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxdxp7pamfmq","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}},"required":["slug","versionId","organizationId"],"description":"Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata."},"ProseMirrorContentSchema":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}},"content":{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}},"marks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}}},"required":["type"],"additionalProperties":{}}},"text":{"type":"string"}},"additionalProperties":{},"description":"A recursive schema modeling ProseMirror document/node structure. It mirrors the ProseMirror JSON format as described at https://prosemirror.net/docs/guide/#schema.serialization. Each node may contain a `type`, optional `attrs`, children in `content`, formatting `marks`, and inline `text`."},"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}/services":{"get":{"summary":"List Services","description":"List all Services items.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"list-services","tags":["Services"],"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 Services","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["items","pagination"],"description":"Services collection"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Create Service

> Create a new Service item.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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"},"Service":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxdxp7pamfmq","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}},"required":["slug","versionId","organizationId"],"description":"Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata."},"ProseMirrorContentSchema":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}},"content":{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}},"marks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}}},"required":["type"],"additionalProperties":{}}},"text":{"type":"string"}},"additionalProperties":{},"description":"A recursive schema modeling ProseMirror document/node structure. It mirrors the ProseMirror JSON format as described at https://prosemirror.net/docs/guide/#schema.serialization. Each node may contain a `type`, optional `attrs`, children in `content`, formatting `marks`, and inline `text`."}},"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}/services":{"post":{"summary":"Create Service","description":"Create a new Service item.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"create-service","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/versionId"}],"requestBody":{"description":"Payload to create a new Service item","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"responses":{"201":{"description":"Service created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"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 Service

> Get a Service item by its id.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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"},"Service":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxdxp7pamfmq","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}},"required":["slug","versionId","organizationId"],"description":"Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata."},"ProseMirrorContentSchema":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}},"content":{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}},"marks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}}},"required":["type"],"additionalProperties":{}}},"text":{"type":"string"}},"additionalProperties":{},"description":"A recursive schema modeling ProseMirror document/node structure. It mirrors the ProseMirror JSON format as described at https://prosemirror.net/docs/guide/#schema.serialization. Each node may contain a `type`, optional `attrs`, children in `content`, formatting `marks`, and inline `text`."}},"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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{id}":{"get":{"summary":"Get Service","description":"Get a Service item by its id.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"get-service-by-id","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Service identifier"},"required":true,"description":"Service identifier","name":"id","in":"path"}],"responses":{"200":{"description":"Service details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Replace Service

> Completely replaces a Service item by its id.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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"},"Service":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxdxp7pamfmq","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}},"required":["slug","versionId","organizationId"],"description":"Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata."},"ProseMirrorContentSchema":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}},"content":{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}},"marks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}}},"required":["type"],"additionalProperties":{}}},"text":{"type":"string"}},"additionalProperties":{},"description":"A recursive schema modeling ProseMirror document/node structure. It mirrors the ProseMirror JSON format as described at https://prosemirror.net/docs/guide/#schema.serialization. Each node may contain a `type`, optional `attrs`, children in `content`, formatting `marks`, and inline `text`."}},"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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{id}":{"post":{"summary":"Replace Service","description":"Completely replaces a Service item by its id.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"replace-service-by-id","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Service identifier"},"required":true,"description":"Service identifier","name":"id","in":"path"}],"requestBody":{"description":"Payload to replace the Service item by its id","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"responses":{"200":{"description":"Service replaced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"201":{"description":"Service created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Delete Service

> Delete a Service item by its id.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{id}":{"delete":{"summary":"Delete Service","description":"Delete a Service item by its id.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"delete-service-by-id","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Service identifier"},"required":true,"description":"Service identifier","name":"id","in":"path"}],"responses":{"204":{"description":"Service deleted"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Update Service

> Partially updates a Service item by its id.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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"},"ProseMirrorContentSchema":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}},"content":{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}},"marks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}}},"required":["type"],"additionalProperties":{}}},"text":{"type":"string"}},"additionalProperties":{},"description":"A recursive schema modeling ProseMirror document/node structure. It mirrors the ProseMirror JSON format as described at https://prosemirror.net/docs/guide/#schema.serialization. Each node may contain a `type`, optional `attrs`, children in `content`, formatting `marks`, and inline `text`."},"Service":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxdxp7pamfmq","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}},"required":["slug","versionId","organizationId"],"description":"Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and 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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{id}":{"patch":{"summary":"Update Service","description":"Partially updates a Service item by its id.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"update-service-by-id","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Service identifier"},"required":true,"description":"Service identifier","name":"id","in":"path"}],"requestBody":{"description":"Partial payload to update the Service item by its id","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxe4bmvgj4da","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}}}}}},"responses":{"200":{"description":"Service updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## List Services

> List all Services items.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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"},"Service":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxdxp7pamfmq","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}},"required":["slug","versionId","organizationId"],"description":"Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata."},"ProseMirrorContentSchema":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}},"content":{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}},"marks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}}},"required":["type"],"additionalProperties":{}}},"text":{"type":"string"}},"additionalProperties":{},"description":"A recursive schema modeling ProseMirror document/node structure. It mirrors the ProseMirror JSON format as described at https://prosemirror.net/docs/guide/#schema.serialization. Each node may contain a `type`, optional `attrs`, children in `content`, formatting `marks`, and inline `text`."},"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}/services":{"get":{"summary":"List Services","description":"List all Services items.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"list-services1","tags":["Services"],"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 Services","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["items","pagination"],"description":"Services collection"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Create Service

> Create a new Service item.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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"},"Service":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxdxp7pamfmq","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}},"required":["slug","versionId","organizationId"],"description":"Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata."},"ProseMirrorContentSchema":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}},"content":{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}},"marks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}}},"required":["type"],"additionalProperties":{}}},"text":{"type":"string"}},"additionalProperties":{},"description":"A recursive schema modeling ProseMirror document/node structure. It mirrors the ProseMirror JSON format as described at https://prosemirror.net/docs/guide/#schema.serialization. Each node may contain a `type`, optional `attrs`, children in `content`, formatting `marks`, and inline `text`."}},"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}/services":{"post":{"summary":"Create Service","description":"Create a new Service item.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"create-service1","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"}],"requestBody":{"description":"Payload to create a new Service item","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"responses":{"201":{"description":"Service created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"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 Service

> Get a Service item by its id.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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"},"Service":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxdxp7pamfmq","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}},"required":["slug","versionId","organizationId"],"description":"Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata."},"ProseMirrorContentSchema":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}},"content":{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}},"marks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}}},"required":["type"],"additionalProperties":{}}},"text":{"type":"string"}},"additionalProperties":{},"description":"A recursive schema modeling ProseMirror document/node structure. It mirrors the ProseMirror JSON format as described at https://prosemirror.net/docs/guide/#schema.serialization. Each node may contain a `type`, optional `attrs`, children in `content`, formatting `marks`, and inline `text`."}},"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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{id}":{"get":{"summary":"Get Service","description":"Get a Service item by its id.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"get-service-by-id1","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Service identifier"},"required":true,"description":"Service identifier","name":"id","in":"path"}],"responses":{"200":{"description":"Service details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Replace Service

> Completely replaces a Service item by its id.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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"},"Service":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxdxp7pamfmq","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}},"required":["slug","versionId","organizationId"],"description":"Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata."},"ProseMirrorContentSchema":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}},"content":{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}},"marks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}}},"required":["type"],"additionalProperties":{}}},"text":{"type":"string"}},"additionalProperties":{},"description":"A recursive schema modeling ProseMirror document/node structure. It mirrors the ProseMirror JSON format as described at https://prosemirror.net/docs/guide/#schema.serialization. Each node may contain a `type`, optional `attrs`, children in `content`, formatting `marks`, and inline `text`."}},"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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{id}":{"post":{"summary":"Replace Service","description":"Completely replaces a Service item by its id.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"replace-service-by-id1","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Service identifier"},"required":true,"description":"Service identifier","name":"id","in":"path"}],"requestBody":{"description":"Payload to replace the Service item by its id","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"responses":{"200":{"description":"Service replaced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"201":{"description":"Service created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Delete Service

> Delete a Service item by its id.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{id}":{"delete":{"summary":"Delete Service","description":"Delete a Service item by its id.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"delete-service-by-id1","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Service identifier"},"required":true,"description":"Service identifier","name":"id","in":"path"}],"responses":{"204":{"description":"Service deleted"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Update Service

> Partially updates a Service item by its id.\
> \
> Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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"},"ProseMirrorContentSchema":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}},"content":{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}},"marks":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"attrs":{"type":"object","additionalProperties":{}}},"required":["type"],"additionalProperties":{}}},"text":{"type":"string"}},"additionalProperties":{},"description":"A recursive schema modeling ProseMirror document/node structure. It mirrors the ProseMirror JSON format as described at https://prosemirror.net/docs/guide/#schema.serialization. Each node may contain a `type`, optional `attrs`, children in `content`, formatting `marks`, and inline `text`."},"Service":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxdxp7pamfmq","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}},"required":["slug","versionId","organizationId"],"description":"Service is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and 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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{id}":{"patch":{"summary":"Update Service","description":"Partially updates a Service item by its id.\n\nService is a top-level record representing a product or microservice; owns the collection of endpoints plus shared authentication and metadata.","operationId":"update-service-by-id1","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":30,"maxLength":30,"description":"Service identifier"},"required":true,"description":"Service identifier","name":"id","in":"path"}],"requestBody":{"description":"Partial payload to update the Service item by its id","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":30,"maxLength":30,"default":"svc_agpf42ylcfymdjwxf32ugogasa","description":"Object ID with prefix \"svc_\""},"name":{"type":"string","default":""},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"summary":{"type":"string","default":"","description":"Short plain-text summary of the service."},"description":{"type":"string","default":"","description":"Service description written in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Service description as ProseMirror JSON blocks."},"tags":{"type":"array","items":{"type":"string"},"default":[]},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"description":"Authentication requirements shared by every endpoint in the service. Each item maps a security scheme id to the scopes/permissions it needs.","url":"https://swagger.io/specification/#security-requirement-object"},"previousSlugs":{"type":"array","items":{"type":"string"},"default":[]},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"organizationId":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the service; kept intact when exporting or importing API docs."},"lastReportAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the most recent report received from the service."},"lastMentionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp when the service was last mentioned in a report, either directly or via connected services."},"lastConnectionAt":{"type":["string","null"],"format":"date-time","description":"Timestamp of the last successful connection observed from the service (ping or report)."},"hasConnection":{"type":"boolean","default":false,"description":"Indicates that the service maintains a direct connection from which reports are expected."}}}}}},"responses":{"200":{"description":"Service updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Get service OpenAPI spec

> Returns the machine-readable OpenAPI specification for a service. Supported versions: v3\_1 (JSON only).

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{idOrSlug}/openapi/{filename}":{"get":{"summary":"Get service OpenAPI spec","description":"Returns the machine-readable OpenAPI specification for a service. Supported versions: v3_1 (JSON only).","operationId":"get-service-openapi","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":1,"description":"Service ID or slug"},"required":true,"description":"Service ID or slug","in":"path","name":"idOrSlug"},{"schema":{"type":"string","enum":["v3_1.json"],"description":"OpenAPI spec filename (e.g. v3_1.json)"},"required":true,"description":"OpenAPI spec filename (e.g. v3_1.json)","in":"path","name":"filename"}],"responses":{"200":{"description":"OpenAPI specification (JSON)","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Replace or create service from OpenAPI spec

> Accepts an OpenAPI specification in the request body. If the service exists (by id or slug), replaces its definition (paths, operations, servers, etc.) with the spec. If not found, creates a new service using idOrSlug as the slug.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{idOrSlug}/openapi":{"post":{"summary":"Replace or create service from OpenAPI spec","description":"Accepts an OpenAPI specification in the request body. If the service exists (by id or slug), replaces its definition (paths, operations, servers, etc.) with the spec. If not found, creates a new service using idOrSlug as the slug.","operationId":"post-service-openapi","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":1,"description":"Service ID or slug"},"required":true,"description":"Service ID or slug","in":"path","name":"idOrSlug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"openapi":{"type":"string"},"info":{"type":"object","additionalProperties":{}}},"required":["openapi","info"],"additionalProperties":{}}}}},"responses":{"200":{"description":"Service updated from OpenAPI spec","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Get service OpenAPI spec

> Returns the machine-readable OpenAPI specification for a service. Supported versions: v3\_1 (JSON only).

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{idOrSlug}/openapi/{filename}":{"get":{"summary":"Get service OpenAPI spec","description":"Returns the machine-readable OpenAPI specification for a service. Supported versions: v3_1 (JSON only).","operationId":"get-service-openapi","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":1,"description":"Service ID or slug"},"required":true,"description":"Service ID or slug","in":"path","name":"idOrSlug"},{"schema":{"type":"string","enum":["v3_1.json"],"description":"OpenAPI spec filename (e.g. v3_1.json)"},"required":true,"description":"OpenAPI spec filename (e.g. v3_1.json)","in":"path","name":"filename"}],"responses":{"200":{"description":"OpenAPI specification (JSON)","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Replace or create service from OpenAPI spec

> Accepts an OpenAPI specification in the request body. If the service exists (by id or slug), replaces its definition (paths, operations, servers, etc.) with the spec. If not found, creates a new service using idOrSlug as the slug.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Services"}],"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}}}},"NotFoundErrorService":{"description":"Service 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}/services/{idOrSlug}/openapi":{"post":{"summary":"Replace or create service from OpenAPI spec","description":"Accepts an OpenAPI specification in the request body. If the service exists (by id or slug), replaces its definition (paths, operations, servers, etc.) with the spec. If not found, creates a new service using idOrSlug as the slug.","operationId":"post-service-openapi","tags":["Services"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":1,"description":"Service ID or slug"},"required":true,"description":"Service ID or slug","in":"path","name":"idOrSlug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"openapi":{"type":"string"},"info":{"type":"object","additionalProperties":{}}},"required":["openapi","info"],"additionalProperties":{}}}}},"responses":{"200":{"description":"Service updated from OpenAPI spec","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"404":{"$ref":"#/components/responses/NotFoundErrorService"},"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/services.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.