NajmHoda AI Assistant — Chat & Conversations API

NajmHoda is EarthCoop’s AI assistant, accessible through both the web interface and this REST API. The API lets you send messages, retrieve conversation histories, manage conversation state, submit feedback, and escalate issues into support tickets. Most endpoints require authentication; the welcome and escalate endpoints are public.

GET /api/najm-hoda/welcome

Returns a welcome message and system statistics for the NajmHoda service. This endpoint is public — no token is required. Authentication: None Request: No parameters.

Example Request

curl -X GET https://your-domain.com/api/najm-hoda/welcome \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "message": "Welcome to NajmHoda. How can I assist you today?",
  "stats": {
    "total_conversations": 1420,
    "active_agents": 4
  }
}

boolean

Always true for a successful response.

string

The welcome message text configured for the NajmHoda service.

object

Aggregate system statistics such as total conversation count and available agents.

POST /api/najm-hoda/chat

Sends a message to NajmHoda and receives an AI-generated response. A conversation is created automatically if you do not supply a conversation_id. Non-admin users are always routed through the steward agent regardless of the agent field value. Authentication: Required — Authorization: Bearer {token}

Request Body

string

required

The user message to send to NajmHoda. Maximum 2,000 characters.

string

The agent to route the request to. One of: auto, engineer, pilot, steward, guide. Defaults to steward for non-admin users. Admin users may use any value including auto for automatic routing.

integer

ID of an existing conversation to continue. If omitted, a new conversation is created automatically.

object

Optional key-value pairs providing additional context to the agent.

Response Fields

boolean

true if the AI responded successfully; false on error.

string

The AI-generated answer text.

string

The agent identifier that handled the request (e.g. steward).

string

The human-readable display name of the agent.

string

An emoji or icon string representing the agent.

integer

The ID of the conversation this message belongs to. Use this in subsequent requests to continue the same conversation.

array

An array of suggested follow-up question strings the user might want to ask next.

integer

Time in milliseconds the AI took to generate the response.

string

A unique identifier for this specific chat request, useful for debugging and support.

Example Request

curl -X POST https://your-domain.com/api/najm-hoda/chat \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What documents do I need to submit a cooperative project?",
    "agent": "steward"
  }'

Example Response

{
  "success": true,
  "message": "To submit a cooperative project you will need to provide a project title, description, required capital amount, and at least one supporting document. You can upload PDFs or images up to 10 MB each.",
  "agent": "steward",
  "agent_name": "Steward",
  "agent_icon": "🧑‍✈️",
  "conversation_id": 847,
  "suggestions": [
    "How do I set the required capital amount?",
    "What file formats are accepted for attachments?"
  ],
  "response_time_ms": 1243,
  "request_id": "req_a1b2c3d4"
}

Error Responses

Validation failure — 422:

{
  "success": false,
  "errors": {
    "message": ["The message field is required."]
  }
}

Server error — 500:

{
  "success": false,
  "message": "An error occurred. Please try again.",
  "error": null
}

GET /api/najm-hoda/conversations

Returns a paginated list of all conversations belonging to the authenticated user, ordered newest first. Authentication: Required — Authorization: Bearer {token}

Query Parameters

string

Filter conversations by status. Accepted values: active, archived, deleted.

string

Filter conversations by agent type. One of: engineer, pilot, steward, guide, auto.

integer

Number of conversations to return per page. Defaults to 20.

Response Fields

boolean

true on success.

array

Paginated array of conversation summary objects.

integer

Unique conversation ID.

string

Auto-generated title derived from the first message (up to 50 characters).

string

The agent type used for this conversation.

string

Current status: active, archived, or deleted.

string

Text of the most recent message in the conversation, or null.

string

ISO 8601 timestamp of the last activity.

string

ISO 8601 timestamp of when the conversation was created.

object

Pagination metadata: current_page, total, per_page, last_page.

Example Request

curl -X GET "https://your-domain.com/api/najm-hoda/conversations?per_page=10&status=active" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "conversations": [
    {
      "id": 847,
      "title": "What documents do I need to submit...",
      "agent_type": "steward",
      "status": "active",
      "last_message": "You can upload PDFs or images up to 10 MB each.",
      "updated_at": "2024-11-15T09:42:00Z",
      "created_at": "2024-11-15T09:41:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total": 14,
    "per_page": 10,
    "last_page": 2
  }
}

GET /api/najm-hoda/conversations/

Returns the full message history for a single conversation. You may only retrieve conversations that belong to your account. Authentication: Required — Authorization: Bearer {token}

Path Parameters

integer

required

The ID of the conversation to retrieve.

Response Fields

boolean

true on success.

object

The full conversation object including message history.

integer

Conversation ID.

string

Auto-generated conversation title.

string

Agent type used in this conversation.

string

ISO 8601 creation timestamp.

array

Chronologically ordered array of message objects.

string

Either user or assistant.

string

The text content of the message.

string

ISO 8601 timestamp of when the message was created.

Example Request

curl -X GET https://your-domain.com/api/najm-hoda/conversations/847 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "conversation": {
    "id": 847,
    "title": "What documents do I need to submit...",
    "agent_type": "steward",
    "created_at": "2024-11-15T09:41:00Z",
    "messages": [
      {
        "role": "user",
        "content": "What documents do I need to submit a cooperative project?",
        "created_at": "2024-11-15T09:41:05Z"
      },
      {
        "role": "assistant",
        "content": "To submit a cooperative project you will need to provide...",
        "created_at": "2024-11-15T09:41:06Z"
      }
    ]
  }
}

Error Responses

Conversation not found — 404:

{
  "success": false,
  "message": "Conversation not found."
}

Access denied — 403:

{
  "success": false,
  "message": "You do not have access to this conversation."
}

DELETE /api/najm-hoda/conversations/

Soft-deletes a conversation by setting its status to deleted. You may only delete conversations that belong to your account. Authentication: Required — Authorization: Bearer {token}

Path Parameters

integer

required

The ID of the conversation to delete.

Example Request

curl -X DELETE https://your-domain.com/api/najm-hoda/conversations/847 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "message": "Conversation deleted successfully."
}

Error Responses

Conversation not found — 404:

{
  "success": false,
  "message": "Conversation not found."
}

Access denied — 403:

{
  "success": false,
  "message": "You do not have access to this conversation."
}

PUT /api/najm-hoda/conversations//archive

Archives a conversation by setting its status to archived. Archived conversations remain accessible but are hidden from the default active listing. You may only archive conversations that belong to your account. Authentication: Required — Authorization: Bearer {token}

Path Parameters

integer

required

The ID of the conversation to archive.

Example Request

curl -X PUT https://your-domain.com/api/najm-hoda/conversations/847/archive \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "message": "Conversation archived."
}

POST /api/najm-hoda/feedback

Submits feedback about the NajmHoda service. Feedback is saved and visible to platform administrators. Authentication: Required — Authorization: Bearer {token}

Request Body

string

required

Category of feedback. One of: bug, feature_request, improvement, complaint, praise, other.

string

required

A brief summary of the feedback. Maximum 200 characters.

string

required

The full feedback text. Maximum 2,000 characters.

integer

Optional satisfaction rating from 1 (poor) to 5 (excellent).

Response Fields

boolean

true if feedback was saved successfully.

string

Confirmation message.

integer

The ID of the newly created feedback record.

Example Request

curl -X POST https://your-domain.com/api/najm-hoda/feedback \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "improvement",
    "subject": "Response speed on complex questions",
    "content": "When I ask detailed financial questions the response takes over 5 seconds.",
    "rating": 3
  }'

Example Response

{
  "success": true,
  "message": "Your feedback has been recorded. Thank you!",
  "feedback_id": 92
}

Error Responses

Validation failure — 422:

{
  "success": false,
  "errors": {
    "type": ["The selected type is invalid."],
    "subject": ["The subject field is required."]
  }
}

POST /api/najm-hoda/escalate

Creates a support ticket from an AI conversation that could not be fully resolved by NajmHoda. This endpoint is public and is intended for use when escalation is needed. It is rate-limited to 30 requests per minute to prevent abuse. Authentication: None (public endpoint)

This endpoint is throttled at 30 requests per minute per IP address. Clients that exceed this limit receive 429 Too Many Requests and should back off using the Retry-After response header.

Request Body

integer

The ID of the conversation being escalated.

string

A description of why the conversation requires escalation.

Response Fields

boolean

true if the escalation was created successfully.

string

Confirmation message.

integer

The ID of the support ticket created from this escalation.

Example Request

curl -X POST https://your-domain.com/api/najm-hoda/escalate \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 847,
    "reason": "User requires manual review of document verification issue."
  }'

Example Response

{
  "success": true,
  "message": "Your request has been escalated to the support team.",
  "ticket_id": 210
}

Error Responses

Rate limit exceeded — 429:

{
  "message": "Too Many Requests."
}

​GET /api/najm-hoda/welcome

​Example Request

​Example Response

​POST /api/najm-hoda/chat

​Request Body

​Response Fields

​Example Request

​Example Response

​Error Responses

​GET /api/najm-hoda/conversations

​Query Parameters

​Response Fields

​Example Request

​Example Response

​GET /api/najm-hoda/conversations/

​Path Parameters

​Response Fields

​Example Request

​Example Response

​Error Responses

​DELETE /api/najm-hoda/conversations/

​Path Parameters

​Example Request

​Example Response

​Error Responses

​PUT /api/najm-hoda/conversations//archive

​Path Parameters

​Example Request

​Example Response

​POST /api/najm-hoda/feedback

​Request Body

​Response Fields

​Example Request

​Example Response

​Error Responses

​POST /api/najm-hoda/escalate

​Request Body

​Response Fields

​Example Request

​Example Response

​Error Responses

GET /api/najm-hoda/welcome

Example Request

Example Response

POST /api/najm-hoda/chat

Request Body

Response Fields

Example Request

Example Response

Error Responses

GET /api/najm-hoda/conversations

Query Parameters

Response Fields

Example Request

Example Response

GET /api/najm-hoda/conversations/

Path Parameters

Response Fields

Example Request

Example Response

Error Responses

DELETE /api/najm-hoda/conversations/

Path Parameters

Example Request

Example Response

Error Responses

PUT /api/najm-hoda/conversations//archive

Path Parameters

Example Request

Example Response

POST /api/najm-hoda/feedback

Request Body

Response Fields

Example Request

Example Response

Error Responses

POST /api/najm-hoda/escalate

Request Body

Response Fields

Example Request

Example Response

Error Responses