Loading ...

REST API: Axero Copilot Create Conversation | Axero Documentation

Home » axero documentation » Wiki » Documentation » REST API Overview » REST API: Axero Copilot » REST API: Axero Copilot Create Conversation
Axero Documentation  Wiki
Public Space
Activity Stream Content
Version 32

REST API: Axero Copilot Create Conversation

0 
 /5
0 (0votes)
Open API Guide
POST/api/chatbot/chat

Start a new Axero Copilot conversation or continue an existing one. Axero sends your message to the configured Axero Copilot service, with a token that identifies the signed-in user, and returns its answer. You can name a profile to change how Axero Copilot answers.

Request

Request Header

HeaderRequiredValueDescription
AuthorizationYESBearer YOUR_TOKENBearer token for the authenticated user. Learn how to create Bearer tokens.
Content-TypeNOapplication/jsonSend application/json. This endpoint reads the body as JSON whatever this header says.

Required Parameters

ParameterTypeRequiredLocationDescription
messageStringYESBodyThe question or instruction to send to Axero Copilot, for example { "message": "What's the company's policy on remote work?" }. A value that is not text, such as a list, is refused by the Axero Copilot service. The call then answers 200 with IsError true (Error while calling to Chat Bot engine.).

Optional Parameters

ParameterTypeRequiredLocationDescription
conversation_idStringNOBodyThe ID of an existing conversation, to continue it, for example { "conversation_id": "50b828ea-d84e-446f-b05e-1b2e8b12208b" }. Leave it out to start a new conversation. An ID the service does not know, or a value that is not text, answers 200 with IsError true (Error while calling to Chat Bot engine.).
bot_profileStringNOBodyThe ProfileId of the Axero Copilot profile to use, sent as a string, for example { "bot_profile": "2" }. A valid profile replaces the site's Axero Copilot settings with its own configuration, system prompt, and scope settings. A missing or unknown one falls back to the default profile. This applies only when Axero Copilot profiles are turned on for the site. Otherwise the site-wide settings are used, and bot_profile has no effect. Use the GET /api/chatbot/profile endpoint to list the ProfileId values.

Example

Request Header

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Request URL

https://your-site.com/api/chatbot/chat

Request Body

{
  "message": "What’s the company’s policy on remote work?"
}

Success Response

{
  "IsError": false,
  "ResponseData": {
    "conversation_id": "debd095e-12ef-4ae8-a6d9-959f73f3233d",
    "footer": "\n- [Work From Home Policy](https://your-site.com/spaces/252/human-resources/wiki/view/8497/work-from-home-policy?language=en-US) _(r:100)_\n...",
    "logs": [
      "Searching at Axero...\n    Question: What is the company's official policy on remote work? Please include any eligibility rules, expectations, approvals, and references to official policy documents or wiki pages.\n    Keywords: remote work policy"
    ],
    "message": "# Remote Work Policy\n\nThe company\u2019s official guidance is in **_Work From Home Policy_**.\n\n## Summary\n- Employees may work from home **only if their job duties permit it**.\n- Roles requiring **direct physical contact with customers** are **not eligible** to telecommute.\n- Employees whose work is ...",
    "response_id": "2d015967-7a7e-4ad2-83c5-c3388faf03ba",
    "sources": [
      {
        "content_id": 8497,
        "entity_type": 9,
        "is_private": false,
        "relevance": 100,
        "space_id": 252,
        "title": "Work From Home Policy",
        "url": "https://your-site.com/spaces/252/human-resources/wiki/view/8497/work-from-home-policy?language=en-US"
      }
    ]
  }
}

Error Response

Invalid Json Object format.

Error Handling

Status CodeLikely CauseNext Action
200 with IsErrorThe Axero Copilot service refused the request, for example because message is missing or is not text, or conversation_id is unknown. ResponseMessage carries a fixed text (Error while calling to Chat Bot engine.), and the service's own status and message are in ResponseData, under StatusCode and ErrorMessage. A site where Axero Copilot is not set up answers the same way with a different text (Copilot engine is not configured.).Read IsError on every response, not the status code. Then read ResponseData for the service's own message.
400 Bad RequestThe body is missing or is not a JSON object (Invalid Json Object format.).Send a JSON object carrying message.
401 UnauthorizedMissing or invalid Bearer token.Check token validity. Learn how to create Bearer tokens →
403 ForbiddenThe profile named in bot_profile, or the default profile when bot_profile is left out, is limited to roles the caller does not hold. The body names the profile, for example The user does not have access to profileID 2.Send a bot_profile the caller can use; Get Profiles lists them.
500 Server ErrorInternal failure, or Axero Copilot profiles are turned on and the site has no default profile (Invalid default Chat Bot profile.).Retry later.

Rate Limits

While Axero does not enforce hard rate limits by default, we recommend the following best practices to ensure optimal performance:

  • Sustained Request Rate: Do not exceed 5 API calls per second
  • Sequential Processing: Wait for each request to complete before sending the next in automated workflows
  • Concurrent Connections: If parallel processing is required, limit to 3 or fewer simultaneous requests
  • Response Timeout: Ensure API responses complete within 15 seconds during testing

Axero may implement temporary rate restrictions if excessive API usage affects overall site performance. For high-volume integrations, contact Axero to discuss your requirements.

Wiki Index

Pages