# Examples

## List Examples

> List all Examples items.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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"},"Example":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyb6olnrujoe","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}},"required":["versionId"],"description":"Example is a reusable example that holds either an inline payload or an external reference for request or response bodies."},"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}/examples":{"get":{"summary":"List Examples","description":"List all Examples items.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"list-examples","tags":["Examples"],"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 Examples","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Example"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["items","pagination"],"description":"Examples collection"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Create Example

> Create a new Example item.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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"},"Example":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyb6olnrujoe","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}},"required":["versionId"],"description":"Example is a reusable example that holds either an inline payload or an external reference for request or response bodies."},"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}/examples":{"post":{"summary":"Create Example","description":"Create a new Example item.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"create-example","tags":["Examples"],"parameters":[{"$ref":"#/components/parameters/versionId"}],"requestBody":{"description":"Payload to create a new Example item","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"responses":{"201":{"description":"Example created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"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 Example

> Get a Example item by its id.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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"},"Example":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyb6olnrujoe","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}},"required":["versionId"],"description":"Example is a reusable example that holds either an inline payload or an external reference for request or response bodies."},"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}}}},"NotFoundErrorExample":{"description":"Example 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}/examples/{id}":{"get":{"summary":"Get Example","description":"Get a Example item by its id.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"get-example-by-id","tags":["Examples"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":31,"maxLength":31,"description":"Example identifier"},"required":true,"description":"Example identifier","name":"id","in":"path"}],"responses":{"200":{"description":"Example details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorExample"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Replace Example

> Completely replaces a Example item by its id.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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"},"Example":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyb6olnrujoe","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}},"required":["versionId"],"description":"Example is a reusable example that holds either an inline payload or an external reference for request or response bodies."},"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}}}},"NotFoundErrorExample":{"description":"Example 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}/examples/{id}":{"post":{"summary":"Replace Example","description":"Completely replaces a Example item by its id.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"replace-example-by-id","tags":["Examples"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":31,"maxLength":31,"description":"Example identifier"},"required":true,"description":"Example identifier","name":"id","in":"path"}],"requestBody":{"description":"Payload to replace the Example item by its id","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"responses":{"200":{"description":"Example replaced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"201":{"description":"Example created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorExample"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Delete Example

> Delete a Example item by its id.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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}}}},"NotFoundErrorExample":{"description":"Example 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}/examples/{id}":{"delete":{"summary":"Delete Example","description":"Delete a Example item by its id.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"delete-example-by-id","tags":["Examples"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":31,"maxLength":31,"description":"Example identifier"},"required":true,"description":"Example identifier","name":"id","in":"path"}],"responses":{"204":{"description":"Example deleted"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorExample"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Update Example

> Partially updates a Example item by its id.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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`."},"Example":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyb6olnrujoe","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}},"required":["versionId"],"description":"Example is a reusable example that holds either an inline payload or an external reference for request or response bodies."}},"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}}}},"NotFoundErrorExample":{"description":"Example 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}/examples/{id}":{"patch":{"summary":"Update Example","description":"Partially updates a Example item by its id.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"update-example-by-id","tags":["Examples"],"parameters":[{"$ref":"#/components/parameters/versionId"},{"schema":{"type":"string","minLength":31,"maxLength":31,"description":"Example identifier"},"required":true,"description":"Example identifier","name":"id","in":"path"}],"requestBody":{"description":"Partial payload to update the Example item by its id","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyc5ixjvi7gu","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}}}}}},"responses":{"200":{"description":"Example updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorExample"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## List Examples

> List all Examples items.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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"},"Example":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyb6olnrujoe","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}},"required":["versionId"],"description":"Example is a reusable example that holds either an inline payload or an external reference for request or response bodies."},"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}/examples":{"get":{"summary":"List Examples","description":"List all Examples items.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"list-examples1","tags":["Examples"],"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 Examples","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Example"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["items","pagination"],"description":"Examples collection"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Create Example

> Create a new Example item.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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"},"Example":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyb6olnrujoe","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}},"required":["versionId"],"description":"Example is a reusable example that holds either an inline payload or an external reference for request or response bodies."},"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}/examples":{"post":{"summary":"Create Example","description":"Create a new Example item.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"create-example1","tags":["Examples"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"}],"requestBody":{"description":"Payload to create a new Example item","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"responses":{"201":{"description":"Example created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"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 Example

> Get a Example item by its id.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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"},"Example":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyb6olnrujoe","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}},"required":["versionId"],"description":"Example is a reusable example that holds either an inline payload or an external reference for request or response bodies."},"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}}}},"NotFoundErrorExample":{"description":"Example 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}/examples/{id}":{"get":{"summary":"Get Example","description":"Get a Example item by its id.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"get-example-by-id1","tags":["Examples"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":31,"maxLength":31,"description":"Example identifier"},"required":true,"description":"Example identifier","name":"id","in":"path"}],"responses":{"200":{"description":"Example details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorExample"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Replace Example

> Completely replaces a Example item by its id.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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"},"Example":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyb6olnrujoe","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}},"required":["versionId"],"description":"Example is a reusable example that holds either an inline payload or an external reference for request or response bodies."},"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}}}},"NotFoundErrorExample":{"description":"Example 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}/examples/{id}":{"post":{"summary":"Replace Example","description":"Completely replaces a Example item by its id.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"replace-example-by-id1","tags":["Examples"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":31,"maxLength":31,"description":"Example identifier"},"required":true,"description":"Example identifier","name":"id","in":"path"}],"requestBody":{"description":"Payload to replace the Example item by its id","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"responses":{"200":{"description":"Example replaced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"201":{"description":"Example created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorExample"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Delete Example

> Delete a Example item by its id.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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}}}},"NotFoundErrorExample":{"description":"Example 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}/examples/{id}":{"delete":{"summary":"Delete Example","description":"Delete a Example item by its id.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"delete-example-by-id1","tags":["Examples"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":31,"maxLength":31,"description":"Example identifier"},"required":true,"description":"Example identifier","name":"id","in":"path"}],"responses":{"204":{"description":"Example deleted"},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorExample"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Update Example

> Partially updates a Example item by its id.\
> \
> Example is a reusable example that holds either an inline payload or an external reference for request or response bodies.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Examples"}],"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`."},"Example":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwyb6olnrujoe","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}},"required":["versionId"],"description":"Example is a reusable example that holds either an inline payload or an external reference for request or response bodies."}},"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}}}},"NotFoundErrorExample":{"description":"Example 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}/examples/{id}":{"patch":{"summary":"Update Example","description":"Partially updates a Example item by its id.\n\nExample is a reusable example that holds either an inline payload or an external reference for request or response bodies.","operationId":"update-example-by-id1","tags":["Examples"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"},{"schema":{"type":"string","minLength":31,"maxLength":31,"description":"Example identifier"},"required":true,"description":"Example identifier","name":"id","in":"path"}],"requestBody":{"description":"Partial payload to update the Example item by its id","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":31,"maxLength":31,"default":"expl_agpf42ylcfymdjwydwtjrzbiau","description":"Object ID with prefix \"expl_\""},"name":{"type":"string","description":"Non-unique name of a reusable example; matches how it is referenced in API definitions."},"value":{"description":"Inline example payload for the referenced content type."},"externalValue":{"type":"string","description":"URL pointing to an external example payload."},"summary":{"type":"string"},"description":{"type":"string","description":"Example description in markdown."},"descriptionBlocks":{"anyOf":[{"$ref":"#/components/schemas/ProseMirrorContentSchema"},{"type":"array","items":{"$ref":"#/components/schemas/ProseMirrorContentSchema"}}],"description":"Example description in ProseMirror JSON blocks."},"kvStorage":{"type":"object","additionalProperties":{},"default":{},"description":"Custom metadata carried with the example (e.g., vendor-specific extensions)."},"versionId":{"type":"string","minLength":30,"maxLength":30,"description":"Object ID with prefix \"ver_\""},"updatedAt":{"type":["string","null"],"format":"date-time","default":"2026-05-25T09:15:34.033Z"}}}}}},"responses":{"200":{"description":"Example updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Example"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundErrorExample"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

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

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

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

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

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