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

# 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_agpzwhz73fyz3hi552xz5ymwty","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi552xz5ymwty","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi552xz5ymwty","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi552xz5ymwty","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi552xz5ymwty","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi562gcijpsea","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi552xz5ymwty","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi552xz5ymwty","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi552xz5ymwty","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi552xz5ymwty","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi552xz5ymwty","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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_agpzwhz73fyz3hi575xfqegjym","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-07-25T21:12:24.281Z"},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-07-25T21:12:24.281Z"},"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"}}}}}}
```