ConverZen - High-Performance AI, Simplified

REST API

Openapi Docs

. The most up-to-date Swagger documentation can always be viewed from https://chat.converzen.de/docs , the openapi definition can be downloaded from https://chat.converzen.de/docs/openapi.json

Authentication

All API requests require authentication using either an api-key or a JWT token. Please see the specific endpoint documentation for details.

curl -X POST https://chat.converzen.de/api/chat/completion/stream \
    -H "Authorization: Bearer YOUR_TOKEN" \
    ...

curl -X POST https://chat.converzen.de/api/chat/completion/stream \
  -H "X-API-Key: YOUR_API_KEY" \
  ...

Endpoints

POST: Get Token Requests

This endpoint only accepts api keys and returns a token that can be used with all other chat endpoints.

curl -v -X POST https://chat.converzen.de/api/chat/get_token \
-H "X-API-Key: sk_test_YOUR_TEST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "user_id" : "unique id, UUID preferably", 
  "persona": { "persona_id": 1, "version_type": "next" }
}'

Result: {"token":"YOUR_NEW_TOKEN","expires_at":1770571652} The expires_at field holds the expiration time of the token in UNIX_EPOCH seconds.

The Request body must contain a valid persona selector. Valid persona selectors depend on the type of api-key used:

prod api-keys: (sk_prod_XXX) are only for personas submitted to production, selectable by their alias, if a persona selector is not supplied, the default persona for the key will be used.

{"persona" : { "alias" : "my-alias" } }

test api-keys: (sk_test_XXX) api keys can select personas by persona_id and version_type, by alias or use the default persona for the api-key.

{"persona" : { "persona_id" : 47, "version_type": "next" } }

Using persona_id and "version_type": "next" allows you to select a work in progress persona that is not submitted to production. This allows you to test your work before submitting it.

POST: Streaming Chat Completion Requests

This request starts a new session. It can be called using an api-key and a persona-selector or using a token (requested from the get_token endpoint), that already contains all information required to select a persona.

curl -X POST https://chat.converzen.de/api/chat/completion/stream \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "persona": { "persona_id": 1, "version_type": "next" }
       "message" : "Talk to me"     
      }'

curl -X POST https://chat.converzen.de/api/chat/completion/stream \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "message" : "Talk to me"     
      }'

This endpoint will stream Server-Sent Events.

Each event is a JSON object with a type field:

session_created: {"type": "session_created", "session_id": "uuid"}
token: {"type": "token", "content": "text chunk"}
done: {"type": "done", "usage": {...}, "finish_reason": "stop"}
error: {"type": "error", "message": "error description"}

POST: Streaming Chat Continuation Requests

This request continues a chat session started by a call to the /chat/completion/stream endpoint. It can be called using an api-key and a persona-selector or using a token, that already contains all information required to select a persona. The session is an id returned by the session_created/session_continued streaming events.

curl -X POST https://chat.converzen.de/api/chat/continuation/stream \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "message" : "Talk to me"     
      }'

curl -X POST https://chat.converzen.de/api/chat/completion/stream \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "message" : "Talk to me"     
      }'