API Reference

API Reference - PsycoAI API

Introduction

Welcome to the PsycoAI Enterprise API documentation! This API is all about AI Agents of all types. Whether you need emotional support agents or efficiency-boosting enterprise agents, our API has you covered. This guide will help you integrate our advanced features into your platform, including real-time chat, user management, and smart data collection via webhooks. Let's get started!

Key Features

  • Real-time Chat: Engage with users through text, audio, or image messages in real-time.
  • User Management: Efficiently manage users with our API endpoints.
  • Smart Data Collection: Utilize our webhook feature to collect and analyze data in real-time, enabling smarter interactions and decisions.

Use Cases

  • Employee Wellness Programs: Integrate our emotional support agents into corporate wellness programs to enhance employee well-being.
  • Customer Support Automation: Provide automated yet personalized customer support using our AI agents.
  • Healthcare Applications: Enhance mental health apps with our state-of-the-art emotional support features.
  • Automate Any Flow: With personalized agents, automate any enterprise workflow, such as medical form applications, customer support, sales, and more.

📘

For more details on the endpoints, see the https://psycoai.readme.io/reference/post_users


Authentication

To access the PsycoAI Enterprise API endpoints, you need to authenticate using an API key provided by us. Include this key in the header of all your requests.

Example

curl --location '<http://backend.psyco.ai/enterprise/v1/users>' \\
--header 'api-key: {{your_key}}'

Authentication Errors

  • 401 Unauthorized: The API key is missing or invalid.
  • 403 Forbidden: The API key does not have the required permissions to access the endpoint.

Agents

At PsycoAI, an agent is a system that uses a language model (LLM) to determine and execute a sequence of actions, either to provide personalized emotional support or automate operational workflows in companies. These agents, based on the Nebula Engine, integrate tools and chat models to perform specific tasks and continuously adjust their actions based on user needs. Agent autonomy can range from simple input routing to complex and continuous workflows.

📘

To check which Agents your company can use, see https://psycoai.readme.io/reference/get_agents


Chat

The chat allows users to interact with Agents through Text, Audio, or even Image messages. PsycoAI Chats, managed by the Nebula Engine, use the main strategies of Short and Long Term Memory, providing the best conversational experience.

Creating a Chat

To create a Chat, you only need a registered User and an available Agent. You can include your own identifier if you want.

curl --request POST \
     --url https://backend.psyco.ai/enterprise/v1/chats \
     --header 'accept: application/json' \
     --header 'api-key: {{your_key}}' \
     --header 'content-type: application/json' \
     --data '
{
  "userId": "{{user_id}}",
  "agentId": "{{agent_id}}",
  "externalIdentifier": "{{your_identifier}}"
}
'

Sending a Message and Receiving a Response

To send a message in a chat, just execute the POST below. You have the option to send a fileId in the body with the id of files that you have previously uploaded to https://psycoai.readme.io/reference/post_uploads.

curl --request POST \
     --url 'https://backend.psyco.ai/enterprise/v1/chats/{{chat_id}}/messages' \
     --header 'accept: application/json' \
     --header 'api-key: {{your_key}}' \
     --header 'content-type: application/json' \
     --data '{"message":"hello!"}'

Streaming Response (Synchronous)

To receive the response as it is created using streaming, just insert the header accept: text/event-stream. As you can imagine, the response in this case will be a text stream.

📘

Use this mode if you can wait for the entire response to be generated.

Event Stream Structure

The response will be divided into sequential events as follows:

1. Delta Event

Contains small parts of the message being generated.

event: delta
data: {"v":"<part of the message>"}

2. Completed Event

Contains the full summary of the generated message.

event: completed
data: {
    "userId": "<user_id>",
    "content": {
        "text": "<full_message>"
    },
    "messageId": "<message_id>",
    "chatId": "<chat_id>",
    "platform": "<platform>",
    "from": "<source>",
    "tenantId": "<tenant_id>",
    "method": "<method>",
    "createdAt": "<timestamp>"
}

Expected Event Stream Flow

  • Start: delta events with message fragments.
  • Completion: A completed event with the full JSON message.
  • Closing: A message event with [DONE].
event: delta
data: {"v":"Hi"}

event: delta
data: {"v":", how are you?"}

event: completed
data: {"userId":"9383a73d-ad5a-4a67-b4cc-5a6b383e82fb","content":{"text":"Hi, how are you?"},"messageId":"892e18c9-c665-4f6a-b82d-082488acd0a8","chatId":"763aa313-3041-4d3d-bd4c-6c3a07e96044","platform":"enterprise-panel","from":"ai-model","tenantId":"3bed2360-8e32-38985317034a","method":"text","createdAt":"2024-11-29T14:04:15.105Z"}

event: message
data: [DONE]

File Upload

File upload allows you to send files to our system. Currently, we only accept files in the following formats:

  • MP3 (speech)
  • JPEG (photo)

These files can be used for various purposes, such as attachments in conversations, support documents, or any other type of content relevant to user interaction.

Get File Link

To retrieve a direct link to access a previously uploaded file, use the GET endpoint below. The file must have been uploaded using the File Upload route.

curl --request GET \
     --url 'https://backend.psyco.ai/enterprise/v1/files/{{user_id}}/{{file_id}}/link' \
     --header 'accept: application/json' \
     --header 'api-key: {{your_key}}'

Webhook

Webhooks are HTTP callbacks that allow your application to receive real-time notifications about events occurring in our API. Whenever a configured event occurs, the API sends an HTTP POST request to the URL specified in the webhook.

List of Events

user.registered
user.profile.updated
user.deleted
user.context-data.updated

chat.created
chat.deleted
chat.user-traits.updated
chat.user-insights.updated
chat.stage.updated

chat.message.sent
chat.message.received

file.uploaded

Event Schema

Configuration

To configure webhooks for specific events, use the endpoint https://psycoai.readme.io/reference/post_webhooks


Web Chat (Webview)

Get the Link

To create the link for accessing the Web Chat, you need to have a created chat. The HTTP request below will return a URL that should be used directly by the end customer to access our platform. Each generated URL is valid for 1 hour, and once accessed, the session is valid for 24 hours.

curl --request GET \
     --url 'https://backend.psyco.ai/enterprise/v1/auth/whitelabel/{{chat_id}}?partnerUrl={{your_url}}' \
     --header 'accept: application/json' \
     --header 'api-key: {{your_key}}'

📘

You can send a URL in the "partnerUrl" query param so that the customer can return directly to your platform by clicking the "back" button.


Standardization

API Response Format

Our API adheres to REST standards and uses JSON for content. On some endpoints, such as the Post Chats route and routes that involve file output, you'll have the option for a stream response. A successful request will return a 200 status code, while successful POST requests will return a 201 status code.


Pagination, Filtering and Sorting

For endpoints returning large datasets, you can use pagination and filtering to manage the data.

Pagination

Include the following parameters in your request:

  • page: The page number to retrieve.
  • limit: The number of items per page.

Example:

curl --location 'https://backend.psyco.ai/enterprise/v1/users?page=2&limit=50' \
--header 'api-key: {{your_key}}'

Filtering

In some endpoints, you can filter results using query parameters. For instance, to filter chats by agentId:

Example:

curl --location 'https://backend.psyco.ai/enterprise/v1/chats?agentId={{agent_id}}' \
--header 'api-key: {{your_key}}'

Sorting

On some endpoints, you can sort the response by createdAt date in either ascending (ASC) or descending (DESC) order.
Example: 

curl --location 'https://backend.psyco.ai/enterprise/v1/chats?sort=ASC' \
--header 'api-key: {{your_key}}'

Rate Limiting

Our API has rate limiting to ensure fair usage. The limits are as follows:

  • 1000 requests per hour per API key.
  • If the limit is exceeded, the API will return a 429 Too Many Requests status.

Change Log

We are creating a Change Log. Stay tuned!


Versioning

Our API is versioned to ensure compatibility. The current version is v1. Future versions will be introduced as /v2, /v3, etc.


Error Handling and Troubleshooting

Common Errors

  • 400 Bad Request: Check if the request payload for correctness.
  • 401 Unauthorized and 403 Forbidden: Check if the API key is correct and included in the request header.
  • 404 Not Found: Verify the endpoint URL and resource identifiers.
  • 429 Too Many Requests: Wait and retry after some time if you have exceeded the rate limit.
  • 500 Internal Server Error: Contact support if the issue persists.

Troubleshooting Tips

  • Make sure the API key is correct and included in the "api-key" header.
  • Check the endpoint URL and request payload for correctness.
  • Review the rate limits to avoid throttling.

To view the complete API Reference, visit https://psycoai.readme.io/.