# Assistant

## Chat with catalog assistant

> Streaming AI assistant that answers questions about the API catalog using tools to query services and their details.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Assistant"}],"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"},"AssistantMessagesSchema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["system","user","assistant"]},"parts":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"},"state":{"type":"string","enum":["streaming","done"]},"providerMetadata":{"type":"object","additionalProperties":{}}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["reasoning"]},"text":{"type":"string"},"state":{"type":"string","enum":["streaming","done"]},"providerMetadata":{"type":"object","additionalProperties":{}}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["file"]},"mediaType":{"type":"string"},"url":{"type":"string"},"filename":{"type":"string"},"providerMetadata":{"type":"object","additionalProperties":{}}},"required":["type","mediaType","url"]},{"type":"object","properties":{"type":{"type":"string","minLength":1}},"required":["type"],"additionalProperties":{}}]}},"metadata":{"type":"object","additionalProperties":{}}},"required":["role","parts"]},"description":"Conversation messages for the AI assistant"}},"required":["messages"],"description":"AI-sdk structured conversation payload for the AI assistant"}},"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}}}},"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}/assistant":{"post":{"summary":"Chat with catalog assistant","description":"Streaming AI assistant that answers questions about the API catalog using tools to query services and their details.","operationId":"post-assistant","tags":["Assistant"],"parameters":[{"$ref":"#/components/parameters/versionId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantMessagesSchema"}}}},"responses":{"200":{"description":"Server-sent events stream of AI assistant response","content":{"text/event-stream":{"schema":{"description":"AI-sdk protocol streaming response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Chat with catalog assistant

> Streaming AI assistant that answers questions about the API catalog using tools to query services and their details.

```json
{"openapi":"3.1.0","info":{"title":"Appear API","version":"2.0.0"},"tags":[{"name":"Assistant"}],"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"},"AssistantMessagesSchema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["system","user","assistant"]},"parts":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"},"state":{"type":"string","enum":["streaming","done"]},"providerMetadata":{"type":"object","additionalProperties":{}}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["reasoning"]},"text":{"type":"string"},"state":{"type":"string","enum":["streaming","done"]},"providerMetadata":{"type":"object","additionalProperties":{}}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","enum":["file"]},"mediaType":{"type":"string"},"url":{"type":"string"},"filename":{"type":"string"},"providerMetadata":{"type":"object","additionalProperties":{}}},"required":["type","mediaType","url"]},{"type":"object","properties":{"type":{"type":"string","minLength":1}},"required":["type"],"additionalProperties":{}}]}},"metadata":{"type":"object","additionalProperties":{}}},"required":["role","parts"]},"description":"Conversation messages for the AI assistant"}},"required":["messages"],"description":"AI-sdk structured conversation payload for the AI assistant"}},"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}}}},"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}/assistant":{"post":{"summary":"Chat with catalog assistant","description":"Streaming AI assistant that answers questions about the API catalog using tools to query services and their details.","operationId":"post-assistant","tags":["Assistant"],"parameters":[{"$ref":"#/components/parameters/projectRef"},{"$ref":"#/components/parameters/versionType"},{"$ref":"#/components/parameters/versionSlug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantMessagesSchema"}}}},"responses":{"200":{"description":"Server-sent events stream of AI assistant response","content":{"text/event-stream":{"schema":{"description":"AI-sdk protocol streaming response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"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/assistant.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.