APIs
AI-Portal exposes REST APIs for chat, agents, and applications. The backend runs on port 3001 by default.
Agent API contract (for developers)
To register an Agent in Admin → Agents, your service must implement these endpoints at {base_url} (e.g. http://your-server.com:8020 — use no trailing slash).
- GET {base_url}/metadata — GET {base_url}/metadata — Name, description, capabilities, supported_models, sample_prompts, status.
- POST {base_url}/ask — POST {base_url}/ask — Accept prompt and context; return JSON with status: "success" and reply content (see below).
- GET {base_url}/data?type=... (optional) — GET {base_url}/data?type=... (optional) — Documents, experts, or other data.
POST /ask — Request body (Portal sends)
The Portal sends a JSON body with these fields. Your agent must accept them; the most critical for compatibility are listed.
| Field | Required | Description |
|---|---|---|
session_id | Yes | Session identifier. |
model_id | Yes | Model ID from your supported_models in metadata. |
user | Yes | User identifier or API URL. |
prompt | Yes | User message. |
output_type | Sent by Portal | Portal always sends "markdown". If your API validates output type, you must accept "markdown" (e.g. do not treat only "text" as valid, or you will get errors like "Invalid output type: text"). |
context | Optional | language, project, extra_data.document (file URLs), history (chat history). |
POST /ask — Response (your agent must return)
Your agent must respond with JSON that the Portal can display. Required:
status="success"- At least one of: content_markdown, answer, or content (string with the reply). Prefer content_markdown for rich formatting.
Example success response:
{
"status": "success",
"content_markdown": "## Answer\nYour reply here..."
}If your agent returns a non-success status or missing content, the Portal will show "Agent error" to the user. Ensure your base URL has no trailing slash (e.g. http://host:8020 not http://host:8020/) to avoid 404 on /ask.
Application API
Applications follow a similar metadata contract (GET /metadata). Register the base URL in Admin → Applications so users can open the app from the portal.
Backend APIs
The AI-Portal backend provides REST endpoints for authentication, chat, agents, projects, and admin operations. These are used by the frontend; for custom integrations you can call them with the same authentication (session or API token as configured).