Services | Appear docs

List Services

get

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

versionIdstring · min: 30 · max: 30Required

Catalog version identifier

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

Query parameters

afterstringOptional

Cursor for pagination (item ID)

limitinteger · min: 1 · max: 1000Optional

Maximum number of items to return (default: 50, max: 1000)

Default: 50

sortany ofOptional

Sort order. Use 'prop' for ascending, '-prop' for descending. Multiple params supported (e.g. sort=name&sort=-createdAt)

stringOptional

or

string[]Optional

Responses

200

List of Services

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get

/v2/catalog/versions/{versionId}/services

GET /v2/catalog/versions/{versionId}/services HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [],
  "pagination": {
    "nextCursor": null,
    "hasMore": true,
    "limit": 1
  }
}

Create Service

post

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

versionIdstring · min: 30 · max: 30Required

Catalog version identifier

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

Body

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

idstring · min: 30 · max: 30Optional

Object ID with prefix "svc_"

Default: svc_agob4v2per3ujmlj2b2r2v3jquExample: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

namestringOptionalDefault: ""Example: User Service

slugstringRequiredExample: user-servicePattern: ^[a-z0-9-]+$

summarystringOptional

Short plain-text summary of the service.

Default: ""Example: User management services that allows adding, updating, and deleting users.

descriptionstringOptional

Service description written in markdown.

Default: ""Example: Service for managing users, authentication, and user profiles.

descriptionBlocksany ofOptional

Service description as ProseMirror JSON blocks.

Example: {"type":"paragraph","content":[{"type":"text","text":"Service description in rich text format."}]}

or

tagsstring[]OptionalDefault: []Example: ["authentication","users"]

previousSlugsstring[]OptionalDefault: []Example: ["user-api","users-api"]

versionIdstring · min: 30 · max: 30Required

Object ID with prefix "ver_"

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

organizationIdstringRequiredExample: org_sample_org

createdAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

updatedAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

lastReportAtstring · nullableOptional

Timestamp of the most recent report received from the service.

Example: 2024-01-15T10:30:00.000Z

lastMentionAtstring · nullableOptional

Timestamp when the service was last mentioned in a report, either directly or via connected services.

Example: 2024-01-15T10:30:00.000Z

lastConnectionAtstring · nullableOptional

Timestamp of the last successful connection observed from the service (ping or report).

Example: 2024-01-15T10:30:00.000Z

hasConnectionbooleanOptional

Indicates that the service maintains a direct connection from which reports are expected.

Default: false

Responses

201

Service created

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

409

Conflict

application/json

500

Internal Server Error

application/json

post

/v2/catalog/versions/{versionId}/services

POST /v2/catalog/versions/{versionId}/services HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 799

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

Get Service

get

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

versionIdstring · min: 30 · max: 30Required

Catalog version identifier

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

idstring · min: 30 · max: 30Required

Service identifier

Example: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

Responses

200

Service details

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

get

/v2/catalog/versions/{versionId}/services/{id}

GET /v2/catalog/versions/{versionId}/services/{id} HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

Replace Service

post

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

versionIdstring · min: 30 · max: 30Required

Catalog version identifier

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

idstring · min: 30 · max: 30Required

Service identifier

Example: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

Body

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

idstring · min: 30 · max: 30Optional

Object ID with prefix "svc_"

Default: svc_agob4v2per3ujmlj2b2r2v3jquExample: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

namestringOptionalDefault: ""Example: User Service

slugstringRequiredExample: user-servicePattern: ^[a-z0-9-]+$

summarystringOptional

Short plain-text summary of the service.

Default: ""Example: User management services that allows adding, updating, and deleting users.

descriptionstringOptional

Service description written in markdown.

Default: ""Example: Service for managing users, authentication, and user profiles.

descriptionBlocksany ofOptional

Service description as ProseMirror JSON blocks.

Example: {"type":"paragraph","content":[{"type":"text","text":"Service description in rich text format."}]}

or

tagsstring[]OptionalDefault: []Example: ["authentication","users"]

previousSlugsstring[]OptionalDefault: []Example: ["user-api","users-api"]

versionIdstring · min: 30 · max: 30Required

Object ID with prefix "ver_"

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

organizationIdstringRequiredExample: org_sample_org

createdAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

updatedAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

lastReportAtstring · nullableOptional

Timestamp of the most recent report received from the service.

Example: 2024-01-15T10:30:00.000Z

lastMentionAtstring · nullableOptional

Timestamp when the service was last mentioned in a report, either directly or via connected services.

Example: 2024-01-15T10:30:00.000Z

lastConnectionAtstring · nullableOptional

Timestamp of the last successful connection observed from the service (ping or report).

Example: 2024-01-15T10:30:00.000Z

hasConnectionbooleanOptional

Indicates that the service maintains a direct connection from which reports are expected.

Default: false

Responses

200

Service replaced

application/json

201

Service created

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

post

/v2/catalog/versions/{versionId}/services/{id}

POST /v2/catalog/versions/{versionId}/services/{id} HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 799

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

Delete Service

delete

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

versionIdstring · min: 30 · max: 30Required

Catalog version identifier

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

idstring · min: 30 · max: 30Required

Service identifier

Example: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

Responses

204

Service deleted

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

delete

/v2/catalog/versions/{versionId}/services/{id}

DELETE /v2/catalog/versions/{versionId}/services/{id} HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update Service

patch

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

versionIdstring · min: 30 · max: 30Required

Catalog version identifier

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

idstring · min: 30 · max: 30Required

Service identifier

Example: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

Body

idstring · min: 30 · max: 30Optional

Object ID with prefix "svc_"

Default: svc_agob4v2per3ujmlj3fywzofzoiExample: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

namestringOptionalDefault: ""Example: User Service

slugstringOptionalExample: user-servicePattern: ^[a-z0-9-]+$

summarystringOptional

Short plain-text summary of the service.

Default: ""Example: User management services that allows adding, updating, and deleting users.

descriptionstringOptional

Service description written in markdown.

Default: ""Example: Service for managing users, authentication, and user profiles.

descriptionBlocksany ofOptional

Service description as ProseMirror JSON blocks.

Example: {"type":"paragraph","content":[{"type":"text","text":"Service description in rich text format."}]}

or

tagsstring[]OptionalDefault: []Example: ["authentication","users"]

previousSlugsstring[]OptionalDefault: []Example: ["user-api","users-api"]

versionIdstring · min: 30 · max: 30Optional

Object ID with prefix "ver_"

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

organizationIdstringOptionalExample: org_sample_org

createdAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

updatedAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

lastReportAtstring · nullableOptional

Timestamp of the most recent report received from the service.

Example: 2024-01-15T10:30:00.000Z

lastMentionAtstring · nullableOptional

Timestamp when the service was last mentioned in a report, either directly or via connected services.

Example: 2024-01-15T10:30:00.000Z

lastConnectionAtstring · nullableOptional

Timestamp of the last successful connection observed from the service (ping or report).

Example: 2024-01-15T10:30:00.000Z

hasConnectionbooleanOptional

Indicates that the service maintains a direct connection from which reports are expected.

Default: false

Responses

200

Service updated

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

patch

/v2/catalog/versions/{versionId}/services/{id}

PATCH /v2/catalog/versions/{versionId}/services/{id} HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 799

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

List Services

get

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

projectRefany ofRequired

Project slug or project id (proj_*)

string · min: 31 · max: 31Optional

Object ID with prefix "proj_"

Example: proj_c4x6k3w8j7n9b1z5s2t4m8q0ve

or

string · min: 1Optional

versionTypestring · enumRequired

Version type, can be either 'branch' or 'environment'

Example: branchPossible values:

versionSlugstring · min: 1Required

Version slug

Example: main

Query parameters

afterstringOptional

Cursor for pagination (item ID)

limitinteger · min: 1 · max: 1000Optional

Maximum number of items to return (default: 50, max: 1000)

Default: 50

sortany ofOptional

Sort order. Use 'prop' for ascending, '-prop' for descending. Multiple params supported (e.g. sort=name&sort=-createdAt)

stringOptional

or

string[]Optional

Responses

200

List of Services

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get

/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services

GET /v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [],
  "pagination": {
    "nextCursor": null,
    "hasMore": true,
    "limit": 1
  }
}

Create Service

post

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

projectRefany ofRequired

Project slug or project id (proj_*)

string · min: 31 · max: 31Optional

Object ID with prefix "proj_"

Example: proj_c4x6k3w8j7n9b1z5s2t4m8q0ve

or

string · min: 1Optional

versionTypestring · enumRequired

Version type, can be either 'branch' or 'environment'

Example: branchPossible values:

versionSlugstring · min: 1Required

Version slug

Example: main

Body

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

idstring · min: 30 · max: 30Optional

Object ID with prefix "svc_"

Default: svc_agob4v2per3ujmlj2b2r2v3jquExample: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

namestringOptionalDefault: ""Example: User Service

slugstringRequiredExample: user-servicePattern: ^[a-z0-9-]+$

summarystringOptional

Short plain-text summary of the service.

Default: ""Example: User management services that allows adding, updating, and deleting users.

descriptionstringOptional

Service description written in markdown.

Default: ""Example: Service for managing users, authentication, and user profiles.

descriptionBlocksany ofOptional

Service description as ProseMirror JSON blocks.

Example: {"type":"paragraph","content":[{"type":"text","text":"Service description in rich text format."}]}

or

tagsstring[]OptionalDefault: []Example: ["authentication","users"]

previousSlugsstring[]OptionalDefault: []Example: ["user-api","users-api"]

versionIdstring · min: 30 · max: 30Required

Object ID with prefix "ver_"

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

organizationIdstringRequiredExample: org_sample_org

createdAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

updatedAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

lastReportAtstring · nullableOptional

Timestamp of the most recent report received from the service.

Example: 2024-01-15T10:30:00.000Z

lastMentionAtstring · nullableOptional

Timestamp when the service was last mentioned in a report, either directly or via connected services.

Example: 2024-01-15T10:30:00.000Z

lastConnectionAtstring · nullableOptional

Timestamp of the last successful connection observed from the service (ping or report).

Example: 2024-01-15T10:30:00.000Z

hasConnectionbooleanOptional

Indicates that the service maintains a direct connection from which reports are expected.

Default: false

Responses

201

Service created

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

409

Conflict

application/json

500

Internal Server Error

application/json

post

/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services

POST /v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 799

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

Get Service

get

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

projectRefany ofRequired

Project slug or project id (proj_*)

string · min: 31 · max: 31Optional

Object ID with prefix "proj_"

Example: proj_c4x6k3w8j7n9b1z5s2t4m8q0ve

or

string · min: 1Optional

versionTypestring · enumRequired

Version type, can be either 'branch' or 'environment'

Example: branchPossible values:

versionSlugstring · min: 1Required

Version slug

Example: main

idstring · min: 30 · max: 30Required

Service identifier

Example: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

Responses

200

Service details

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

get

/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{id}

GET /v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{id} HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

Replace Service

post

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

projectRefany ofRequired

Project slug or project id (proj_*)

string · min: 31 · max: 31Optional

Object ID with prefix "proj_"

Example: proj_c4x6k3w8j7n9b1z5s2t4m8q0ve

or

string · min: 1Optional

versionTypestring · enumRequired

Version type, can be either 'branch' or 'environment'

Example: branchPossible values:

versionSlugstring · min: 1Required

Version slug

Example: main

idstring · min: 30 · max: 30Required

Service identifier

Example: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

Body

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

idstring · min: 30 · max: 30Optional

Object ID with prefix "svc_"

Default: svc_agob4v2per3ujmlj2b2r2v3jquExample: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

namestringOptionalDefault: ""Example: User Service

slugstringRequiredExample: user-servicePattern: ^[a-z0-9-]+$

summarystringOptional

Short plain-text summary of the service.

Default: ""Example: User management services that allows adding, updating, and deleting users.

descriptionstringOptional

Service description written in markdown.

Default: ""Example: Service for managing users, authentication, and user profiles.

descriptionBlocksany ofOptional

Service description as ProseMirror JSON blocks.

Example: {"type":"paragraph","content":[{"type":"text","text":"Service description in rich text format."}]}

or

tagsstring[]OptionalDefault: []Example: ["authentication","users"]

previousSlugsstring[]OptionalDefault: []Example: ["user-api","users-api"]

versionIdstring · min: 30 · max: 30Required

Object ID with prefix "ver_"

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

organizationIdstringRequiredExample: org_sample_org

createdAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

updatedAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

lastReportAtstring · nullableOptional

Timestamp of the most recent report received from the service.

Example: 2024-01-15T10:30:00.000Z

lastMentionAtstring · nullableOptional

Timestamp when the service was last mentioned in a report, either directly or via connected services.

Example: 2024-01-15T10:30:00.000Z

lastConnectionAtstring · nullableOptional

Timestamp of the last successful connection observed from the service (ping or report).

Example: 2024-01-15T10:30:00.000Z

hasConnectionbooleanOptional

Indicates that the service maintains a direct connection from which reports are expected.

Default: false

Responses

200

Service replaced

application/json

201

Service created

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

post

/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{id}

POST /v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{id} HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 799

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

Delete Service

delete

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

projectRefany ofRequired

Project slug or project id (proj_*)

string · min: 31 · max: 31Optional

Object ID with prefix "proj_"

Example: proj_c4x6k3w8j7n9b1z5s2t4m8q0ve

or

string · min: 1Optional

versionTypestring · enumRequired

Version type, can be either 'branch' or 'environment'

Example: branchPossible values:

versionSlugstring · min: 1Required

Version slug

Example: main

idstring · min: 30 · max: 30Required

Service identifier

Example: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

Responses

204

Service deleted

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

delete

/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{id}

DELETE /v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{id} HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update Service

patch

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

projectRefany ofRequired

Project slug or project id (proj_*)

string · min: 31 · max: 31Optional

Object ID with prefix "proj_"

Example: proj_c4x6k3w8j7n9b1z5s2t4m8q0ve

or

string · min: 1Optional

versionTypestring · enumRequired

Version type, can be either 'branch' or 'environment'

Example: branchPossible values:

versionSlugstring · min: 1Required

Version slug

Example: main

idstring · min: 30 · max: 30Required

Service identifier

Example: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

Body

idstring · min: 30 · max: 30Optional

Object ID with prefix "svc_"

Default: svc_agob4v2per3ujmlj4bnquxbdteExample: svc_c4x6k3w8j7n9b1z5s2t4m8q0ve

namestringOptionalDefault: ""Example: User Service

slugstringOptionalExample: user-servicePattern: ^[a-z0-9-]+$

summarystringOptional

Short plain-text summary of the service.

Default: ""Example: User management services that allows adding, updating, and deleting users.

descriptionstringOptional

Service description written in markdown.

Default: ""Example: Service for managing users, authentication, and user profiles.

descriptionBlocksany ofOptional

Service description as ProseMirror JSON blocks.

Example: {"type":"paragraph","content":[{"type":"text","text":"Service description in rich text format."}]}

or

tagsstring[]OptionalDefault: []Example: ["authentication","users"]

previousSlugsstring[]OptionalDefault: []Example: ["user-api","users-api"]

versionIdstring · min: 30 · max: 30Optional

Object ID with prefix "ver_"

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

organizationIdstringOptionalExample: org_sample_org

createdAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

updatedAtstring · nullableOptionalDefault: 2026-02-02T12:32:44.324ZExample: 2024-01-15T10:30:00.000Z

lastReportAtstring · nullableOptional

Timestamp of the most recent report received from the service.

Example: 2024-01-15T10:30:00.000Z

lastMentionAtstring · nullableOptional

Timestamp when the service was last mentioned in a report, either directly or via connected services.

Example: 2024-01-15T10:30:00.000Z

lastConnectionAtstring · nullableOptional

Timestamp of the last successful connection observed from the service (ping or report).

Example: 2024-01-15T10:30:00.000Z

hasConnectionbooleanOptional

Indicates that the service maintains a direct connection from which reports are expected.

Default: false

Responses

200

Service updated

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

patch

/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{id}

PATCH /v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{id} HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 799

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

{
  "id": "svc_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "name": "User Service",
  "slug": "user-service",
  "summary": "User management services that allows adding, updating, and deleting users.",
  "description": "Service for managing users, authentication, and user profiles.",
  "descriptionBlocks": {
    "type": "paragraph",
    "content": [
      {
        "type": "text",
        "text": "Service description in rich text format."
      }
    ]
  },
  "tags": [
    "authentication",
    "users"
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "previousSlugs": [
    "user-api",
    "users-api"
  ],
  "versionId": "ver_c4x6k3w8j7n9b1z5s2t4m8q0ve",
  "organizationId": "org_sample_org",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "kvStorage": {},
  "lastReportAt": "2024-01-15T10:30:00.000Z",
  "lastMentionAt": "2024-01-15T10:30:00.000Z",
  "lastConnectionAt": "2024-01-15T10:30:00.000Z",
  "hasConnection": false
}

Get service OpenAPI spec

get

Returns the machine-readable OpenAPI specification for a service. Supported versions: v3_1 (JSON only).

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

versionIdstring · min: 30 · max: 30Required

Catalog version identifier

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

idOrSlugstring · min: 1Required

Service ID or slug

filenamestring · enumRequired

OpenAPI spec filename (e.g. v3_1.json)

Example: v3_1.jsonPossible values:

Responses

200

OpenAPI specification (JSON)

application/json

400

Invalid request

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

get

/v2/catalog/versions/{versionId}/services/{idOrSlug}/openapi/{filename}

GET /v2/catalog/versions/{versionId}/services/{idOrSlug}/openapi/{filename} HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Replace or create service from OpenAPI spec

post

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

versionIdstring · min: 30 · max: 30Required

Catalog version identifier

Example: ver_c4x6k3w8j7n9b1z5s2t4m8q0ve

idOrSlugstring · min: 1Required

Service ID or slug

Body

openapistringRequired

Other propertiesanyOptional

Responses

200

Service updated from OpenAPI spec

application/json

400

Invalid request

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

post

/v2/catalog/versions/{versionId}/services/{idOrSlug}/openapi

POST /v2/catalog/versions/{versionId}/services/{idOrSlug}/openapi HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 101

{
  "openapi": "text",
  "info": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

{
  "ok": true
}

Get service OpenAPI spec

get

Returns the machine-readable OpenAPI specification for a service. Supported versions: v3_1 (JSON only).

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

projectRefany ofRequired

Project slug or project id (proj_*)

string · min: 31 · max: 31Optional

Object ID with prefix "proj_"

Example: proj_c4x6k3w8j7n9b1z5s2t4m8q0ve

or

string · min: 1Optional

versionTypestring · enumRequired

Version type, can be either 'branch' or 'environment'

Example: branchPossible values:

versionSlugstring · min: 1Required

Version slug

Example: main

idOrSlugstring · min: 1Required

Service ID or slug

filenamestring · enumRequired

OpenAPI spec filename (e.g. v3_1.json)

Example: v3_1.jsonPossible values:

Responses

200

OpenAPI specification (JSON)

application/json

400

Invalid request

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

get

/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{idOrSlug}/openapi/{filename}

GET /v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{idOrSlug}/openapi/{filename} HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Replace or create service from OpenAPI spec

post

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.

Authorizations

AuthorizationstringRequired

Project API key authentication. Use your project API key as a Bearer token in the Authorization header.

Path parameters

projectRefany ofRequired

Project slug or project id (proj_*)

string · min: 31 · max: 31Optional

Object ID with prefix "proj_"

Example: proj_c4x6k3w8j7n9b1z5s2t4m8q0ve

or

string · min: 1Optional

versionTypestring · enumRequired

Version type, can be either 'branch' or 'environment'

Example: branchPossible values:

versionSlugstring · min: 1Required

Version slug

Example: main

idOrSlugstring · min: 1Required

Service ID or slug

Body

openapistringRequired

Other propertiesanyOptional

Responses

200

Service updated from OpenAPI spec

application/json

400

Invalid request

application/json

404

Service not found

application/json

500

Internal Server Error

application/json

post

/v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{idOrSlug}/openapi

POST /v2/catalog/projects/{projectRef}/{versionType}/{versionSlug}/services/{idOrSlug}/openapi HTTP/1.1
Host: api.appear.sh
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 101

{
  "openapi": "text",
  "info": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

{
  "ok": true
}

hashtagList Services

hashtagCreate Service

hashtagGet Service

hashtagReplace Service

hashtagDelete Service

hashtagUpdate Service

hashtagList Services

hashtagCreate Service

hashtagGet Service

hashtagReplace Service

hashtagDelete Service

hashtagUpdate Service

hashtagGet service OpenAPI spec

hashtagReplace or create service from OpenAPI spec

hashtagGet service OpenAPI spec

hashtagReplace or create service from OpenAPI spec

List Services

Create Service

Get Service

Replace Service

Delete Service

Update Service

List Services

Create Service

Get Service

Replace Service

Delete Service

Update Service

Get service OpenAPI spec

Replace or create service from OpenAPI spec

Get service OpenAPI spec

Replace or create service from OpenAPI spec