API Documentation

Build custom integrations with AgenticPortals' powerful API.

Contents

Introduction

The AgenticPortals API allows you to integrate our AI-powered conversational capabilities into your own applications, products, or services. Use our API to:

  • Programmatically manage your portal's FAQ content
  • Create custom chat interfaces beyond our standard widget
  • Access and analyze conversation data and metrics
  • Integrate portal functionality with your mobile app or other platforms
  • Connect AgenticPortals with your CRM, ticketing system, or booking software

Base URL

https://api.agenticportals.com/v1

API Versioning

The current version is v1. When we make backwards-incompatible changes to the API, we will release a new version. We'll provide ample notice before deprecating any existing API versions.

Authentication

The AgenticPortals API uses API keys for authentication. To obtain an API key, login to your account dashboard and navigate to the API Settings section.

Security Notice: Keep your API key secure. Do not share it publicly or include it in client-side code.

Authentication Header

All API requests must include your API key in the HTTP header:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET "https://api.agenticportals.com/v1/faqs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Rate Limits

To ensure service stability, the API enforces rate limits based on your subscription plan:

Plan Rate Limit Burst Limit
Starter 60 requests/minute 100 requests/minute
Professional 300 requests/minute 500 requests/minute
Enterprise 1,000 requests/minute 2,000 requests/minute

The API includes rate limit information in the response headers:

  • X-RateLimit-Limit: Total number of requests allowed per minute
  • X-RateLimit-Remaining: Number of requests remaining in the current window
  • X-RateLimit-Reset: Time in seconds until the rate limit resets

If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

API Endpoints

The AgenticPortals API is organized around REST principles. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Chat API

Send Message

POST /chat/messages

Send a message to the portal and receive a response.

Request Parameters
Parameter Type Required Description
message string Yes The user's message to the portal
session_id string Yes A unique identifier for the conversation session
language string No Language code (default: 'en')
Example Request
curl -X POST "https://api.agenticportals.com/v1/chat/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your opening hours?",
    "session_id": "abc123",
    "language": "en"
  }'
Example Response
{
  "id": "msg_123456",
  "response": "We're open Monday to Friday from 9 AM to 5 PM, and weekends from 10 AM to 4 PM. We're closed on public holidays.",
  "session_id": "abc123",
  "timestamp": "2025-05-02T11:24:15Z",
  "source": "faq",
  "confidence": 0.95,
  "suggested_actions": [
    {
      "type": "link",
      "text": "View Map & Directions",
      "url": "https://example.com/directions"
    }
  ]
}

Get Conversation History

GET /chat/conversations/{session_id}

Retrieve the message history for a specific conversation.

Example Request
curl -X GET "https://api.agenticportals.com/v1/chat/conversations/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

FAQ Management

List FAQs

GET /faqs

Retrieve a list of all FAQ items.

Create FAQ

POST /faqs

Create a new FAQ item.

Update FAQ

PUT /faqs/{faq_id}

Update an existing FAQ item.

Delete FAQ

DELETE /faqs/{faq_id}

Delete an FAQ item.

Analytics

Conversation Metrics

GET /analytics/conversations

Get conversation metrics over a specified time period.

Popular Questions

GET /analytics/popular-questions

Get a list of the most frequently asked questions.

Booking Integration

Get Available Products

GET /booking/products

Retrieve a list of bookable products/experiences.

Check Availability

GET /booking/availability

Check availability for a specific product on a given date.

Webhooks

AgenticPortals supports webhooks to notify your application when specific events occur, such as:

  • New conversation started
  • Message received (from visitor)
  • Message sent (from portal)
  • Booking inquiry initiated
  • FAQ not found

To configure webhooks, visit the API Settings section in your AgenticPortals dashboard.

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests:

  • 2xx: Success
  • 4xx: Client error (invalid request, authentication issues)
  • 5xx: Server error

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The request was malformed or missing required parameters",
    "status": 400,
    "details": {
      "missing_fields": ["session_id"]
    }
  }
}

Common Error Codes

Code Description
authentication_failed Invalid or missing API key
invalid_request Malformed request or missing required parameters
resource_not_found The requested resource does not exist
rate_limit_exceeded API rate limit has been exceeded
internal_error An unexpected error occurred on the server

Client SDKs

To make integration easier, we provide official client libraries for several programming languages:

JavaScript/TypeScript

For web and Node.js applications

View on npm
Python

For Python applications and data science

View on PyPI
PHP

For PHP applications and CMS plugins

View on Packagist

All our SDKs are open source and available on GitHub. We welcome contributions from the community.

Additional Resources

API Tutorials

Step-by-step guides for common integrations

Sample Code

Example implementations on GitHub

Support

Get help from our API team