Agents

Get agent users by agent ID and Organization API key

get

Fetches agent users by agent ID and Organization API key. The response includes the agent users details.

Authorizations

Organization-Secret-Key

Organization-Secret-KeystringRequired

Custom authentication header

Path parameters

idstringRequired

Unique identifier of the agent.

Example: 5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b

Query parameters

pagenumberOptional

Page number

pageSizenumberOptional

Page size

orderBystring · enumOptional

Order by

Possible values:

orderDirectionstring · enumOptional

Order direction

Possible values:

Responses

200

Successfully retrieved agent users.

application/json

currentPagenumberRequired

Current page

pageSizenumberRequired

Page size

totalItemsnumberRequired

Total items

totalPagesnumberRequired

Total pages

hasNextPagebooleanRequired

Has next page

hasPreviousPagebooleanRequired

Has previous page

403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json

404

Agent not found.

application/json

500

Unexpected error occurred while processing the request. Please try again later.

application/json

get

/external/agents/{id}/users

HTTPcURLJavaScriptPython

GET /external/agents/{id}/users HTTP/1.1
Host: api.raia2.com
Organization-Secret-Key: YOUR_API_KEY
Accept: */*

{
  "currentPage": 1,
  "pageSize": 1,
  "totalItems": 1,
  "totalPages": 1,
  "hasNextPage": true,
  "hasPreviousPage": true,
  "data": [
    {
      "id": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
      "firstName": "John",
      "lastName": "Doe",
      "context": "Support",
      "source": "webchat",
      "fkId": "123456",
      "fkUserId": "123456",
      "email": "[email protected]",
      "phoneNumber": "[phone]",
      "metadata": {
        "customData": {
          "key1": "value1",
          "key2": "value2"
        }
      }
    }
  ]
}

Get agent users by Agent API key

get

Fetches agent users by Agent API key. The response includes the agent users details.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Query parameters

pagenumberOptional

Page number

pageSizenumberOptional

Page size

orderBystring · enumOptional

Order by

Possible values:

orderDirectionstring · enumOptional

Order direction

Possible values:

Responses

200

Successfully retrieved agent users.

application/json

organizationIdstring · uuidRequired

Unique identifier for the organization.

Example: 123e4567-e89b-12d3-a456-426614174000

organizationNamestringRequired

Name of the organization.

idstring · uuidRequired

Unique identifier for the agent.

Example: 123e4567-e89b-12d3-a456-426614174000

namestringRequired

Name of the agent.

publicNamestringRequired

Public name of the agent.

rolestringRequired

Role of the agent.

descriptionstringOptional

Description of the agent.

vectorStoreIdstringRequired

OpenAI vector store ID.

Example: vs_1234567890

avatarUrlstringOptional

Avatar URL of the agent.

Example: https://example.com/avatar.jpg

statusstring · enumRequired

Status of the agent.

Possible values:

tagsstring[] · nullableOptional

Agent tags.

403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json

404

Agent not found.

application/json

500

Unexpected error occurred while processing the request. Please try again later.

application/json

get

/external/agents/users

HTTPcURLJavaScriptPython

GET /external/agents/users HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Accept: */*

{
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationName": "text",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "publicName": "text",
  "role": "text",
  "description": "text",
  "vectorStoreId": "vs_1234567890",
  "aiConfig": {
    "id": "asst_1234567890",
    "model": "gpt-5.1",
    "temperature": 1,
    "topP": 1,
    "instructions": "text",
    "isCodeInterpreterEnabled": true,
    "isFileSearchEnabled": true,
    "fileSearchMaxNumResults": 10,
    "reasoningEffort": "medium",
    "isOutputJsonSchemaEnabled": true,
    "outputJsonSchema": "{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}"
  },
  "avatarUrl": "https://example.com/avatar.jpg",
  "status": "active",
  "tags": [
    "text"
  ],
  "skills": [
    {
      "systemName": "AGENT_SKILL_SYSTEM_NAME",
      "status": "active"
    }
  ]
}

Get agent by API key

get

Fetches an agent by API key. The response includes the agent details.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Responses

200

Successfully retrieved the agent.

application/json

organizationIdstring · uuidRequired

Unique identifier for the organization.

Example: 123e4567-e89b-12d3-a456-426614174000

organizationNamestringRequired

Name of the organization.

idstring · uuidRequired

Unique identifier for the agent.

Example: 123e4567-e89b-12d3-a456-426614174000

namestringRequired

Name of the agent.

publicNamestringRequired

Public name of the agent.

rolestringRequired

Role of the agent.

descriptionstringOptional

Description of the agent.

vectorStoreIdstringRequired

OpenAI vector store ID.

Example: vs_1234567890

avatarUrlstringOptional

Avatar URL of the agent.

Example: https://example.com/avatar.jpg

statusstring · enumRequired

Status of the agent.

Possible values:

tagsstring[] · nullableOptional

Agent tags.

403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json

404

Agent not found.

application/json

500

Unexpected error occurred while processing the request. Please try again later.

application/json

get

/external/agents/by-api-key

HTTPcURLJavaScriptPython

GET /external/agents/by-api-key HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Accept: */*

{
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationName": "text",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "publicName": "text",
  "role": "text",
  "description": "text",
  "vectorStoreId": "vs_1234567890",
  "aiConfig": {
    "id": "asst_1234567890",
    "model": "gpt-5.1",
    "temperature": 1,
    "topP": 1,
    "instructions": "text",
    "isCodeInterpreterEnabled": true,
    "isFileSearchEnabled": true,
    "fileSearchMaxNumResults": 10,
    "reasoningEffort": "medium",
    "isOutputJsonSchemaEnabled": true,
    "outputJsonSchema": "{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}"
  },
  "avatarUrl": "https://example.com/avatar.jpg",
  "status": "active",
  "tags": [
    "text"
  ],
  "skills": [
    {
      "systemName": "AGENT_SKILL_SYSTEM_NAME",
      "status": "active"
    }
  ]
}

Get agent statistic by API key

get

Fetches an agent statistic by API key. The response includes the agent statistic.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Query parameters

startDatestring · date-timeOptional

Start date of statistics calculation.

Example: 2024-03-20T12:00:00Z

endDatestring · date-timeOptional

End date of statistics calculation.

Example: 2024-03-20T12:00:00Z

Responses

200

Successfully retrieved the agent statistic.

application/json

tokensUsednumberRequired

Total number of tokens used by the agent in the given period.

tokensPerConversationnumberRequired

Number of tokens per conversations by the agent in the given period.

vapiSecondsUsednumberRequired

Total number of vapi seconds used by the agent in the given period.

averageCallDurationnumberRequired

Number of vapi seconds per conversations by the agent in the given period.

smsUsednumberRequired

Total number of sms used by the agent in the given period.

smsPerConversationnumberRequired

Number of sms per conversations by the agent in the given period.

emailsUsednumberRequired

Total number of emails used by the agent in the given period.

emailsPerConversationnumberRequired

Number of emails per conversations by the agent in the given period.

403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json

404

Agent not found.

application/json

500

Unexpected error occurred while processing the request. Please try again later.

application/json

get

/external/agents/statistic

HTTPcURLJavaScriptPython

GET /external/agents/statistic HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Accept: */*

{
  "tokensUsed": 1,
  "tokensPerConversation": 1,
  "vapiSecondsUsed": 1,
  "averageCallDuration": 1,
  "smsUsed": 1,
  "smsPerConversation": 1,
  "emailsUsed": 1,
  "emailsPerConversation": 1
}

Create agent webhook

post

Creates a new webhook for the agent identified by the API key.

Authorizations

Agent-Secret-Key

Agent-Secret-KeystringRequired

Custom authentication header

Body

application/json

titlestringRequired

Title of the webhook

Example: My Webhook

descriptionstringRequired

Description of the webhook

Example: This webhook is triggered when a message is received

urlstringRequired

URL where the webhook will be sent

Example: https://api.example.com/webhook

triggerConditionstring · enumRequired

Condition that triggers the webhook

Example: each_messagePossible values:

headersobjectOptional

Optional headers to be sent with the webhook

Example: {"Authorization":"Bearer token"}

Responses

201

Successfully created the webhook.

application/json

403

Invalid API key or secret key. Ensure that you are using a valid authentication key.

application/json

404

Agent not found.

application/json

500

Unexpected error occurred while processing the request. Please try again later.

application/json

post

/external/agents/webhooks

HTTPcURLJavaScriptPython

POST /external/agents/webhooks HTTP/1.1
Host: api.raia2.com
Agent-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 208

{
  "title": "My Webhook",
  "description": "This webhook is triggered when a message is received",
  "url": "https://api.example.com/webhook",
  "triggerCondition": "each_message",
  "headers": {
    "Authorization": "Bearer token"
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "agentId": "123e4567-e89b-12d3-a456-426614174000",
  "title": "My Webhook",
  "description": "This webhook is triggered when a message is received",
  "url": "https://api.example.com/webhook",
  "triggerCondition": "each_message",
  "headers": {
    "Authorization": "Bearer token"
  },
  "status": "active",
  "createdAt": "2024-03-20T12:00:00Z",
  "updatedAt": "2024-03-20T12:00:00Z"
}