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

# 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"}}}}}}
```