API Documentation

Table of Contents

• Authentication
• Endpoints
  • Accounts Endpoint
  • Conversations Endpoint
    • List Conversations
    • Create a New Conversation
    • Show Conversation
  • Conversation Messages Endpoint
• Error Handling
• Examples
• Data Primitives

Authentication

To access protected endpoints, include your API key in the request header as follows:

Authorization: Bearer YOUR_API_KEY

There are two types of API keys:

1. Master API Key - Provided by the development team, used to create new accounts
2. Account API Key - Returned when creating an account, used for all subsequent API operations for that specific user/account

When creating a new account, use the master API key. After account creation, use the account-specific API key returned in the response for all other API calls.

Endpoints

Accounts Endpoint

Create Account from IMX Code

Creates a new user account using an IMX code. This endpoint will fetch the DISC profile associated with the IMX code and create a new user with their personal account.

Note: This endpoint only creates new users. If a user already exists with the provided email, an error will be returned.

• HTTP Method: POST

• URL: /api/v1/accounts

• Headers:

  • Content-Type: application/json
  • Authorization: Bearer YOUR_API_KEY

Request Body

Parameter	Type	Required	Description
imx_code	String	Yes	The IMX code used for fetching DISC profile.
name	String	Yes	The full name for the new user.
email	String	Yes	The email address for the new user (must be unique).

Successful Response

• Status Code: 201 Created
• Response Body:

{
  "token": "acct_1234567890",
  "name": "Example Name",
  "state": "active",
  "api_key": "token_abcdef1234567890"
}

Important: Save the api_key returned in this response. This is the API key for the newly created user and should be used for all subsequent API requests on behalf of this user.

Error Responses

• Status Code: 422 Unprocessable Entity
• Response Body (validation errors):

{
  "errors": {
    "imx_code": ["can't be blank"],
    "email": ["is not a valid email address"]
  }
}

• Response Body (user already exists):

{
  "errors": {
    "email": ["User already exists with this email"]
  }
}

---

Conversations Endpoint

List Conversations

This endpoint returns a list of the current account's conversations. It supports filtering by active state using a query parameter, and returns both active and finished conversations together in one array.

• Method: GET
• URL: /api/v1/conversations
• Content-Type: application/json
• Authentication: Required

Query Parameters

Parameter	Type	Required	Description
active	Boolean	No	Filter conversations by active state. Set to true for active conversations, false for finished ones.
page	Number	No	The page number for paginated results (when not filtering by active).
per_page	Number	No	Number of conversations per page (when not filtering by active).

Successful Response

{
  "conversations": [
    {
      "token": "con_1",
      "state": "active",
      "last_message_at": "2023-10-10T13:00:00Z",
      "assistant": {
        "token": "ast_3",
        "name": "Assistant Name",
        "description": "Assistant description"
      }
    },
    {
      "token": "con_5",
      "state": "finished",
      "last_message_at": "2023-09-20T11:00:00Z",
      "assistant": {
        "token": "ast_2",
        "name": "Another Assistant",
        "description": "Another description"
      }
    }
    // ...
  ]
}

Error Response

• Status Code: 401 Unauthorized (if authentication fails)
• Response body:

{
  "error": "Unauthorized access"
}

Create a New Conversation

This endpoint is used to create a new conversation between the current user and an assistant. It accepts optional parameters such as a goal, initial question, and text messages.

• Method: POST
• URL: /api/v1/conversations
• Content-Type: application/json
• Authentication: Required

Request Body

Parameter	Type	Required	Description
goal	String	No	A signed global ID or identifier of the goal associated with the conversation.
question	String	No	An initial question to kick start the conversation.
reopen_conversation	Boolean	No	Reopen the conversation if it is finished.
conversation	Object	No	Optional nested object: Use this when sending additional text details. prefer to the question parameter.
└─ text	String	Conditionally required	The additional text to send for the conversation.
└─ user	String	Conditionally required	The sender of the message. Accepted values: "user", "assistant"

Note: If the request includes the reopen_conversation parameter, the conversation is reopened (with its state set back to active) and any summary details are removed.

Successful Response

• Status Code: 201 Created
• Response Body:

{
  "token": "con_1234567890",
  "state": "active",
  "assistant": {
    "token": "ast_123456789",
    "name": "Assistant Name",
    "description": "Assistant description"
  }
}

Error Response

• Status Code: 422 Unprocessable Entity
• Response Body:

{
  "errors": {
    "base": ["Unable to create conversation. Please check your input."]
  }
}

Show Conversation

This endpoint retrieves a single conversation by its token and includes all associated messages.

• Method: GET
• URL: /api/v1/conversations/:token
• Content-Type: application/json
• Authentication: Required

URL Parameters

Parameter	Type	Required	Description
token	String	Yes	The conversation token to retrieve.

Successful Response

{
  "token": "con_1234567890",
  "state": "active",
  "last_message_at": "2023-10-10T13:00:00Z",
  "assistant": {
    "token": "ast_123456789",
    "name": "Assistant Name",
    "description": "Assistant description"
  },
  "messages": [
    {
      "token": "msg_1234567890",
      "conversation_token": "con_1234567890",
      "user": "user",
      "text": "Hello, assistant!",
      "created_at": "2023-10-10T12:55:00Z"
    },
    {
      "token": "msg_0987654321",
      "conversation_token": "con_1234567890",
      "user": "assistant",
      "text": "Hello! How can I help you today?",
      "created_at": "2023-10-10T13:00:00Z"
    }
  ]
}

Error Response

• Status Code: 404 Not Found
• Response Body:

{
  "error": "Conversation not found"
}

---

Conversation Messages Endpoint

Add a Message to a Conversation

This endpoint is used to add a new message to an existing conversation. It enables both user and assistant messages to be appended to the conversation thread.

• Method: POST
• URL: /api/v1/conversations/message
• Content-Type: application/json
• Authentication: Required

Request Body

Parameter	Type	Required	Description
conversation_token	String	Yes	The ID of the existing conversation that you want to add a message to.
text	String	Yes	The text content of the message.
async	Boolean	No	Set to true for asynchronous processing (default: false).

Note: By default, the API processes messages synchronously and returns the assistant's response immediately. Set async: true to process the message in the background and receive only the user message confirmation.

Successful Response

• Status Code: 200 OK
• Response Body:

{
  "user_message": {
    "token": "msg_1234567890",
    "conversation_token": "con_1234567890",
    "user": "user",
    "text": "Hello, assistant!",
    "created_at": "2023-10-10T13:00:00Z"
  },
  "assistant_message": {
    "token": "msg_0987654321",
    "conversation_token": "con_1234567890",
    "user": "assistant",
    "text": "Hello! How can I help you today?",
    "created_at": "2023-10-10T13:00:01Z"
  }
}

Note: The API returns both the user's message and the assistant's response by default. If async: true is specified, only the user message is returned and assistant_message will be null.

Error Response

• Status Code: 422 Unprocessable Entity
• Response Body:

{
  "errors": {
    "text": ["cannot be blank"]
  }
}

---

Error Handling

All endpoints return appropriate HTTP status codes along with a JSON body for error messages when issues occur. Some common error status codes include:

• 401 Unauthorized: For missing or invalid API tokens.
• 422 Unprocessable Entity: For validation errors in request parameters.
• 404 Not Found: If a requested resource does not exist.

Errors are returned with an "errors" key in the JSON response. Clients should handle these status codes accordingly.

---

Examples

Example: Create a New Account

curl -X POST https://decipherme.com/api/v1/accounts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "imx_code": "IMX123456",
    "name": "Example Account",
    "email": "[email protected]"
  }'

Example: List Conversations

curl -X GET "https://decipherme.com/api/v1/conversations?page=1&per_page=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example: Create a Conversation

curl -X POST https://decipherme.com/api/v1/conversations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the weather today?",
    "conversation": { "text": "Please share today\'s weather forecast." }
  }'

Example: Adding a Message to a Conversation

curl -X POST https://decipherme.com/api/v1/conversations/message \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_token": "con_1234567890",
    "text": "Hello, can you provide further details?"
  }'

Data Primitives

Below is a description of the key JSON primitives used in the API responses:

Account Object

Field	Type	Description
token	String	Unique identifier for the account (prefixed with "acc_")
name	String	Name of the account
state	String	Current state of the account (e.g., "active")

Conversation Object

Field	Type	Description
token	String	Unique conversation identifier (prefixed with "con_")
state	String	The state of the conversation (active, finished, etc.)
last_message_at	String	Last message timestamp in ISO8601 format
assistant	Object	The assistant object associated with this conversation
messages	Array	A list of Message objects (only on Show Conversation endpoint)

Message Object

Field	Type	Description
token	String	Unique message identifier (prefixed with "msg_")
conversation_token	String	References the associated conversation token
user	String	The sender of the message ("user", "assistant")
text	String	The textual content of the message
created_at	String	Creation timestamp in ISO8601 format

Assistant Object

Field	Type	Description
token	String	Unique assistant identifier (prefixed with "ast_")
name	String	Name of the assistant
description	String	Description of the assistant

These primitives define the shape of data exchanged between the API and its consumers. Use these definitions as a reference when parsing responses and constructing requests.