1Kosmos · Conversational

Chat API

Embed identity-aware conversational and chatbot experiences.

The Chatbot API service powers identity-aware conversational experiences — integrate 1Kosmos identity into chat and messaging surfaces.

10 endpoints

across 9 resource groups.

ECDSA-signed

every request is signed with your key pair.

JSON over HTTPS

predictable REST, conventional status codes.

OpenAPI 3.0

Download the spec →

Reference

Base URL

All Chat endpoints are relative to your environment host. Examples on this page use the 1Kosmos pilot environment — swap in your production root when you go live.

Pilot https://pilot-root.1kosmos.net/chatapi

Content type

Requests and responses use application/json.

GEThttps://pilot-root.1kosmos.net/chatapi/healthz

curl -X GET 'https://pilot-root.1kosmos.net/chatapi/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Security

Authentication

Chat uses ECDSA key-pair authentication. Each request carries your credentials as HTTP headers; verification-grade calls additionally sign the request body. Retrieve the system signing key from /publickeys.

Credentials

keyIdECDSA Public Keyheader

keySecretECDSA Private Keyheader

licenseLicense key from License Microserviceheader

GEThttps://pilot-root.1kosmos.net/chatapi/healthz

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/chatapi/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/healthz", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Authorization": "Bearer YOUR_TOKEN"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/chatapi/healthz",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY",
        "Authorization": "Bearer YOUR_TOKEN"
    }
)
print(res.json())

Reference

Errors

Chat uses conventional HTTP status codes: 2xx success, 4xx a problem with the request, 5xx a service-side error.

Status	Meaning	Description
200 / 204	OK	The request succeeded.
400	Bad Request	Validation failed.
401	Unauthorized	Missing or invalid credentials.
403	Forbidden	Authenticated, but not permitted.
404	Not Found	The resource does not exist.
500	Server Error	Something went wrong on our side.

4XXerror response

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error"
}

Chat

Service Key

Service Key endpoints.

GET/servicekeys

Get service keys

This endpoint returns available service keys. The license you are using must be of authLevel 'system'

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns array with service keys

Headers

Name	Type	Description
requestidrequired	string	JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒

GEThttps://pilot-root.1kosmos.net/chatapi/servicekeys

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/chatapi/servicekeys' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/servicekeys", {
  method: "GET",
  headers: {
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "licensekey": "YOUR_LICENSE_KEY",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/chatapi/servicekeys",
    headers={
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "licensekey": "YOUR_LICENSE_KEY",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

400

401

403

500

Success

[
  {
    "tag": "xxxxx",
    "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "type": "xxxxx"
  }
]

// no response body

// no response body

// no response body

// no response body

DELETE/servicekey/{keyId}

Reset Service Key

This endpoint resets service key for given keyId. Deletes current one and recreates a new one. The license you are using must be of authLevel 'system'

Parameters

keyId (required)

The keyId of service key to reset

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Returns

Returns re-created service key

Path parameters

Name	Type	Description
keyIdrequired	string	keyId of service key to reset

Headers

Name	Type	Description
requestidrequired	string	JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒

DELETEhttps://pilot-root.1kosmos.net/chatapi/servicekey/{keyId}

cURL

Node.js

Python

curl -X DELETE 'https://pilot-root.1kosmos.net/chatapi/servicekey/<keyId>' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/servicekey/<keyId>", {
  method: "DELETE",
  headers: {
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "licensekey": "YOUR_LICENSE_KEY",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.delete(
    "https://pilot-root.1kosmos.net/chatapi/servicekey/<keyId>",
    headers={
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "licensekey": "YOUR_LICENSE_KEY",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

400

401

500

Success

[
  {
    "tag": "xxxxx",
    "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "type": "xxxxx"
  }
]

// no response body

// no response body

// no response body

Chat

Chat API

Conversational endpoints.

POST/query/agent/{agentId}

Chat API endpoint to query specific agent

Sends user input to specific agent and returns response

Path parameters

Name	Type	Description
agentIdrequired	string	Agent ID to query

Query parameters

Name	Type	Description
sessionId	string	Optional session ID. If not provided, generated by API.

Request body

Field	Type	Description
data	object	—

POSThttps://pilot-root.1kosmos.net/chatapi/query/agent/{agentId}

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/chatapi/query/agent/<agentId>?sessionId=<sessionId>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"sessionId": "string", "userInput": "string", "tenantId": "string", "communityId": "string", "username": "string"}}'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/query/agent/<agentId>?sessionId=<sessionId>", {
  method: "POST",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "data": {
      "sessionId": "string",
      "userInput": "string",
      "tenantId": "string",
      "communityId": "string",
      "username": "string"
    }
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/chatapi/query/agent/<agentId>?sessionId=<sessionId>",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY",
        "Authorization": "Bearer YOUR_TOKEN"
    },
    json={
      "data": {
        "sessionId": "string",
        "userInput": "string",
        "tenantId": "string",
        "communityId": "string",
        "username": "string"
      }
    },
)
print(res.json())

RESPONSE

200

Agent response

{
  "response": "string",
  "sessionId": "string"
}

Chat

ECDSA Helper

ECDSA Helper endpoints.

POST/ecdsa_helper/{method}

Encrypt and decrypt the data string by public key and private key.

Parameters

method (optional)

The method parameter is type of enum. Default value is encrypt.

This parameter only accepts following values

encrypt, decrypt

Request Body

data (optional)

The data key is type of String.

publicKey (required)

The publicKey is type of string.

privateKey (required)

The privateKey is type of string.

Returns

Returns the encrypted/decrypted string.

This API throw an error if something goes wrong. A common source of error is public or private key is not valid.

Path parameters

Name	Type	Description
method	string	—

Request body

Field	Type	Description
data	string	—
publicKey	string	—
privateKey	string	—

POSThttps://pilot-root.1kosmos.net/chatapi/ecdsa_helper/{method}

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/chatapi/ecdsa_helper/<method>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"data": "Hey, This is example data string.", "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=", "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="}'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/ecdsa_helper/<method>", {
  method: "POST",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "data": "Hey, This is example data string.",
    "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=",
    "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/chatapi/ecdsa_helper/<method>",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY",
        "Authorization": "Bearer YOUR_TOKEN"
    },
    json={
      "data": "Hey, This is example data string.",
      "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=",
      "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="
    },
)
print(res.json())

RESPONSE

200

successful operation

{
  "data": "xxxxxxxxxxxxxxxxxxxx",
  "publicKey": "xxxxxxxxxxxxxxxxxxxx"
}

Chat

Environment

Environment endpoints.

GET/environment

/environment

Provide details regarding the environments.

Returns

Returns an environment object

GEThttps://pilot-root.1kosmos.net/chatapi/environment

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/chatapi/environment' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/environment", {
  method: "GET",
  headers: {
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/chatapi/environment",
    headers={
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

Success

// no response body

Chat

Healthz

Healthz endpoints.

GET/healthz

Get healthz.

Get healthz

Returns

Returns a healthz object

``version = <git-tag>.<commit-id>.<dob>``

``git-tag``: When code is compiled from a git-tag, this must carry the tag name. This should match one of the git tags.
``commit-id``: This is the git-commit-id. eg: When code is built from this, the hex code, in the end, is the commit it.
``dob``: Date Of Build. This is epoc-time-in-se conds that tell the time when the build was created.
if the code is not built from a git-tag, then the ``version =<commit-id>.<dob>``

GEThttps://pilot-root.1kosmos.net/chatapi/healthz

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/chatapi/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/healthz", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Authorization": "Bearer YOUR_TOKEN"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/chatapi/healthz",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY",
        "Authorization": "Bearer YOUR_TOKEN"
    }
)
print(res.json())

RESPONSE

200

Success ``` { "status": "all services operational", "publicKey": "string" //same as <service>/publickeys endpoint, "code": "200", "version": "<version>" //as defined above } ```

{
  "status": "all services operational",
  "publicKey": "//same as <service>/publickeys endpoint",
  "code": "200",
  "version": "xxxx.xxxx.xxxx"
}

Chat

JWT

Endpoints for JWT operations

POST/jwt/verifyToken

/jwt/verifyToken

Verify JWT token and check active session

This endpoint verifies a JWT token and checks if the user has an active login session. It also validates user permissions for AI chatbot access and ensures the user is active and not disabled. If validation fails, all user login sessions are destroyed.

Headers

requestid (required)

JSON string encrypted with ECDSA containing "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds

publickey (required)

ECDSA Public key for encryption/decryption

Request Body

data (required)

Encrypted object containing:

token: JWT token string to verify

Returns

Returns verification result with decoded token data and user permissions.

Headers

Name	Type	Description
requestidrequired	string	JSON string encrypted with ECDSA containing request metadata
publickeyrequired	string	Public Key / Try Authorize 🔒

Request body

Request body contains encrypted 'data' field with the token to verify.

For Swagger preview, you can send unencrypted data:

{
    "data": {
        "token": "your-jwt-token-here"
    }
}

Field	Type	Description
data	object	Encrypted data containing token (or unencrypted for Swagger preview)

POSThttps://pilot-root.1kosmos.net/chatapi/jwt/verifyToken

cURL

Node.js

Python

curl -X POST 'https://pilot-root.1kosmos.net/chatapi/jwt/verifyToken' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}}'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/jwt/verifyToken", {
  method: "POST",
  headers: {
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "data": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://pilot-root.1kosmos.net/chatapi/jwt/verifyToken",
    headers={
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET"
    },
    json={
      "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    },
)
print(res.json())

RESPONSE

200

401

Token verified successfully

{
  "data": {
    "status": 200,
    "data": "{\"user\":{\"id\":\"123\",\"email\":\"user@example.com\"},\"tenant\":{\"id\":\"tenant123\"},\"community\":{\"id\":\"community123\"}}"
  },
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."
}

{
  "message": "Invalid token"
}

Chat

Public Key

Public Key endpoints.

GET/publickeys

Get system's public key.

Returns

Returns a public key object

GEThttps://pilot-root.1kosmos.net/chatapi/publickeys

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/chatapi/publickeys' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/publickeys", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Authorization": "Bearer YOUR_TOKEN"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/chatapi/publickeys",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY",
        "Authorization": "Bearer YOUR_TOKEN"
    }
)
print(res.json())

RESPONSE

200

401

{
  "publicKey": ""
}

// no response body

Chat

Service Directory

Service Directory endpoints.

GET/sd

Get all service directories.

Returns

Returns all service directories.

GEThttps://pilot-root.1kosmos.net/chatapi/sd

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/chatapi/sd' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/sd", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Authorization": "Bearer YOUR_TOKEN"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/chatapi/sd",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY",
        "Authorization": "Bearer YOUR_TOKEN"
    }
)
print(res.json())

RESPONSE

200

{
  "name1": "https://xxx.xxxxxx.xxx/xxxxx",
  "name2": "https://xxx.xxxxxx.xxx/xxxxx",
  "name3": "https://xxx.xxxxxx.xxx/xxxxx"
}

Chat

Well Known config

Well Known config endpoints.

GET/.well-known

Get well known config.

Get well known config

Returns

Returns an object

GEThttps://pilot-root.1kosmos.net/chatapi/.well-known

cURL

Node.js

Python

curl -X GET 'https://pilot-root.1kosmos.net/chatapi/.well-known' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const res = await fetch("https://pilot-root.1kosmos.net/chatapi/.well-known", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Authorization": "Bearer YOUR_TOKEN"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "https://pilot-root.1kosmos.net/chatapi/.well-known",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY",
        "Authorization": "Bearer YOUR_TOKEN"
    }
)
print(res.json())

RESPONSE

200

Success ``` { "public_key": "string" //same as <service>/publickeys endpoint, } ```

{
  "public_key": "//same as <service>/publickeys endpoint"
}