Agent Ai Chat Bot API Documentation

Table of Contents

API Base URL

https://api.theineedagent.ai/v2

Overview

This documentation covers all endpoints available in the API v1.0. The API follows RESTful principles and uses standard HTTP methods (GET, POST, PUT, DELETE).

Authentication

Most endpoints require authentication. The API uses API keys that can be managed through the /account/apiKey endpoints.

Endpoints

Account

Endpoints for managing your account and API keys.

POST /account/apiKey
Create a new API key
GET /account/apiKey
List all API keys
DELETE /account/apiKey/{keyId}
Delete a specific API key

Agency

Endpoints for managing agencies and their sources.

POST /agency/source
Create a new source for the agency
GET /agency/source
List all sources for the agency
DELETE /agency/source/{id}
Delete a specific source
GET /agency/source/{id}
Get details of a specific source
GET /agency/current
Get information about the current agency
POST /agency/invite
Send an invitation to join the agency
GET /agency
Get agency details
PUT /agency/source/{sourceId}
Update a specific source

AiProvider

Endpoints for managing AI providers.

POST /aiProvider
Create a new AI provider
GET /aiProvider
List all AI providers
DELETE /aiProvider/{id}
Delete a specific AI provider
GET /aiProvider/{id}
Get details of a specific AI provider
PUT /aiProvider/{id}
Update a specific AI provider

Bot

Endpoints for managing bots, their sources, and steps.

POST /bot/ai
Create a bot using AI
POST /bot/{id}/source/{sourceId}
Attach a source to a bot
DELETE /bot/{id}/source/{sourceId}
Remove a source from a bot
POST /bot
Create a new bot
GET /bot
List all bots
DELETE /bot/{id}
Delete a specific bot
GET /bot/{id}
Get details of a specific bot
PUT /bot/{id}
Update a specific bot
GET /bot/{id}/steps
Get steps for a specific bot
GET /bot/nodeDescriptors
Get node descriptors for bots
POST /bot/{id}/publish
Publish a bot
POST /bot/{id}/save
Save a bot's configuration
POST /bot/{id}/softverify
Perform soft verification on a bot

BotMetric

Endpoints for retrieving metrics about bots.

GET /botMetric/actions
Get bot actions metrics
GET /botMetric/logs
Get bot logs
GET /botMetric/messages
Get bot message metrics

BotSourceVariable

Endpoints for managing variables associated with bot sources.

GET /botVariables/{botId}/{sourceId}
Get variables for a specific bot source
POST /botVariables/{botId}/{sourceId}
Create or update variables for a bot source

BotTemplate

Endpoints for managing bot templates.

GET /botTemplates
List all bot templates

BotTesting

Endpoints for testing bots.

POST /bot/{botId}/testSession
Create a test session for a bot
GET /bot/{botId}/testSession
Get test sessions for a bot
DELETE /bot/{botId}/testSession/{leadId}
Delete a specific test session
GET /bot/{botId}/testSession/messages/{leadId}
Get messages from a test session
POST /bot/{botId}/testSession/message
Send a message in a test session

Changelog

Endpoints for retrieving changelog information.

GET /changelog
Get the changelog

Clerk

Endpoints for Clerk integration.

POST /_clerk/hook
Webhook for Clerk events

GHL

Endpoints for Go High Level integration.

POST /ghl/webhook
Webhook for Go High Level events

Hierarchy

Endpoints for managing hierarchies.

POST /hierarchy
Create a new hierarchy
GET /hierarchy
List all hierarchies
DELETE /hierarchy/{id}
Delete a specific hierarchy
GET /hierarchy/{id}
Get details of a specific hierarchy
PUT /hierarchy/{id}
Update a specific hierarchy

HubSpot

Endpoints for HubSpot integration.

POST /hubspot/webhook
Webhook for HubSpot events

Lead

Endpoints for managing leads.

DELETE /lead/{leadId}
Delete a specific lead
GET /lead/{leadId}
Get details of a specific lead
GET /lead
List all leads
GET /lead/search
Search for leads

Library

Endpoints for managing the content library, including files and web scraping.

GET /library/aisearch
Search the library using AI
POST /library/files/{fileId}/source/{sourceId}
Attach a file to a source
DELETE /library/files/{fileId}/source/{sourceId}
Remove a file from a source
DELETE /library/files/{fileId}
Delete a specific file
GET /library/files/{fileId}
Get details of a specific file
PUT /library/files/{fileId}
Update a specific file
GET /library/files
List all files
POST /library/files
Upload a new file
GET /library/webscrape/prescrape
Analyze a URL before scraping
POST /library/webscrape
Scrape content from a website
GET /library/files/{fileId}/view
View a specific file

Persona

Endpoints for managing personas.

POST /persona
Create a new persona
GET /persona
List all personas
DELETE /persona/{id}
Delete a specific persona
GET /persona/{id}
Get details of a specific persona
PUT /persona/{id}
Update a specific persona

Webhook

Endpoints for managing webhooks.

POST /webhook/message/{sourceId}
Send a message to a webhook for a specific source

Data Models / Schemas

The API uses the following data models:

  • AddHierarchyInput: Schema for creating a hierarchy
  • AddSourceInput: Schema for adding a source
  • AddSourceOutput: Response schema when adding a source
  • AgencyMemberResult: Schema for agency member data
  • AgencyResult: Schema for agency data
  • AiCreateBotInput: Schema for creating a bot using AI
  • AttachSourceInput: Schema for attaching a source
  • BotMetricAction: Schema for bot action metrics
  • BotMetricLog: Schema for bot logs
  • BotMetricMessage: Schema for bot message metrics
  • BotMetricPrompt: Schema for bot prompts
  • BotNodeGroup: Schema for bot node groups
  • BotVariableUpdateInput: Schema for updating bot variables

Note: Full schema definitions are not provided in the source documentation.

Usage Examples

Creating a Bot

POST /bot
Content-Type: application/json
Authorization: Bearer {YOUR_API_KEY}

{
  "name": "Customer Support Bot",
  "description": "Bot to handle customer support inquiries"
}

Testing a Bot

POST /bot/{botId}/testSession
Content-Type: application/json
Authorization: Bearer {YOUR_API_KEY}

{
  "initialMessage": "Hello, I need help with my order"
}

Sending a Message to a Bot Test Session

POST /bot/{botId}/testSession/message
Content-Type: application/json
Authorization: Bearer {YOUR_API_KEY}

{
  "leadId": "lead_12345",
  "message": "My order number is #12345"
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests:

  • 200 OK: The request was successful
  • 201 Created: A resource was successfully created
  • 400 Bad Request: The request was invalid
  • 401 Unauthorized: Authentication failed or was not provided
  • 403 Forbidden: The authenticated user doesn't have permission
  • 404 Not Found: The requested resource was not found
  • 500 Internal Server Error: An error occurred on the server

Error responses typically include a JSON body with more details about the error.

For additional information, refer to the Swagger UI at:

Or download the complete API specification in JSON format:

https://api.theineedagent.ai/v2