Lorikeet's "tools" primitive - typed actions with defined inputs and outputs and optional JavaScript output transforms, built no-code in the UI - lets the agent call into your systems (via synchronous scoped-credential API, inbound webhook, or outbound async callback) and chain multiple typed actions across systems. This surface is configured primarily in the Lorikeet UI; any programmatic management is not publicly documented.
openapi: 3.0.3
info:
title: Lorikeet API
description: >-
Programmatic surface for Lorikeet (Lorikeet CX), an AI customer support agent
for complex and regulated businesses. The API centers on conversations
(support tickets handled by the AI agent), messages within those
conversations, webhook subscriptions and events, and knowledge ingestion.
IMPORTANT (honesty note): Lorikeet's authoritative API reference at
docs.lorikeetcx.ai is gated behind a customer access code. The paths, schemas,
and the base URL below are MODELED from Lorikeet's public integration and
security materials (synchronous scoped-credential API, inbound HMAC-signed
webhooks, outbound async request/response, typed no-code "tools", and a
per-step audit trail) and from common conventions for this class of AI support
agent. They should be treated as a best-effort, plausible model - not
field-verified contract - and reconciled against the official reference once
access is available. Authentication is a Bearer API key.
version: 0.1.0-modeled
contact:
name: Lorikeet
url: https://lorikeet.ai
termsOfService: https://lorikeet.ai
servers:
- url: https://api.lorikeetcx.ai/v1
description: >-
Modeled base URL. The public site is lorikeet.ai and docs live at
docs.lorikeetcx.ai; the exact API host is not published outside the gated
reference.
security:
- bearerAuth: []
tags:
- name: Conversations
description: Create, continue, and inspect AI-agent-handled support conversations.
- name: Messages
description: Post and list messages within a conversation.
- name: Webhooks
description: Manage webhook subscriptions and receive Lorikeet events.
- name: Knowledge
description: Ingest and manage knowledge sources the agent reasons over.
paths:
/conversations:
post:
operationId: createConversation
tags:
- Conversations
summary: Create a conversation
description: >-
Start a new conversation (support ticket) for the Lorikeet AI agent to
work. An optional first end-user message and end-user / context metadata
can be supplied so the workflow orchestration layer can begin resolving
immediately.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConversationRequest'
responses:
'201':
description: Conversation created.
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
get:
operationId: listConversations
tags:
- Conversations
summary: List conversations
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
- name: status
in: query
required: false
schema:
$ref: '#/components/schemas/ConversationStatus'
responses:
'200':
description: A page of conversations.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationList'
'401':
$ref: '#/components/responses/Unauthorized'
/conversations/{conversation_id}:
parameters:
- $ref: '#/components/parameters/ConversationId'
get:
operationId: getConversation
tags:
- Conversations
summary: Retrieve a conversation
description: >-
Retrieve the current state of a conversation, including status, resolution,
and whether it has been escalated to a human agent.
responses:
'200':
description: The conversation.
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: continueConversation
tags:
- Conversations
summary: Continue a conversation
description: >-
Continue an existing conversation by supplying a new end-user message.
The agent advances its workflow and returns the updated conversation
(including any new agent messages).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContinueConversationRequest'
responses:
'200':
description: Updated conversation.
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
'404':
$ref: '#/components/responses/NotFound'
/conversations/{conversation_id}/messages:
parameters:
- $ref: '#/components/parameters/ConversationId'
get:
operationId: listMessages
tags:
- Messages
summary: List messages
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: A page of messages for the conversation.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageList'
'404':
$ref: '#/components/responses/NotFound'
post:
operationId: createMessage
tags:
- Messages
summary: Post a message
description: Append a message to a conversation.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageRequest'
responses:
'201':
description: Message created.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'404':
$ref: '#/components/responses/NotFound'
/webhooks:
get:
operationId: listWebhooks
tags:
- Webhooks
summary: List webhook subscriptions
responses:
'200':
description: Registered webhook subscriptions.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WebhookSubscription'
post:
operationId: createWebhook
tags:
- Webhooks
summary: Create a webhook subscription
description: >-
Register an endpoint to receive Lorikeet events. Deliveries are signed so
the receiver can cryptographically verify them (HMAC) before acting.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookRequest'
responses:
'201':
description: Webhook subscription created.
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
/webhooks/{webhook_id}:
parameters:
- name: webhook_id
in: path
required: true
schema:
type: string
delete:
operationId: deleteWebhook
tags:
- Webhooks
summary: Delete a webhook subscription
responses:
'204':
description: Webhook subscription deleted.
'404':
$ref: '#/components/responses/NotFound'
/knowledge/sources:
get:
operationId: listKnowledgeSources
tags:
- Knowledge
summary: List knowledge sources
responses:
'200':
description: Configured knowledge sources.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/KnowledgeSource'
post:
operationId: ingestKnowledgeSource
tags:
- Knowledge
summary: Ingest a knowledge source
description: >-
Submit a document, URL, or help-center article for ingestion into the
knowledge base the agent reasons over. Ingestion is asynchronous; poll the
returned source for status.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IngestKnowledgeRequest'
responses:
'202':
description: Ingestion accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/KnowledgeSource'
/knowledge/sources/{source_id}:
parameters:
- name: source_id
in: path
required: true
schema:
type: string
get:
operationId: getKnowledgeSource
tags:
- Knowledge
summary: Retrieve a knowledge source
responses:
'200':
description: The knowledge source and its ingestion status.
content:
application/json:
schema:
$ref: '#/components/schemas/KnowledgeSource'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteKnowledgeSource
tags:
- Knowledge
summary: Delete a knowledge source
responses:
'204':
description: Knowledge source deleted.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer API key issued to your Lorikeet account. Send as
`Authorization: Bearer <API_KEY>`. Lorikeet also supports OAuth2, JWT
bearer, Basic, HMAC, and M2M flows for tool/action integrations into your
systems; those secure Lorikeet's outbound calls rather than this inbound
management API.
parameters:
ConversationId:
name: conversation_id
in: path
required: true
schema:
type: string
Limit:
name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
Cursor:
name: cursor
in: query
required: false
schema:
type: string
description: Opaque pagination cursor from a prior response.
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
ConversationStatus:
type: string
enum:
- open
- resolved
- escalated
- closed
description: >-
Lifecycle of a conversation. `escalated` indicates the agent handed off to
a human per the workflow's escalation rules.
CreateConversationRequest:
type: object
properties:
end_user:
$ref: '#/components/schemas/EndUser'
message:
type: string
description: Optional first end-user message.
channel:
type: string
description: Origin channel (e.g. chat, email, voice).
enum:
- chat
- email
- voice
metadata:
type: object
additionalProperties: true
description: Arbitrary context passed to the agent's workflows.
ContinueConversationRequest:
type: object
required:
- message
properties:
message:
type: string
description: New end-user message to advance the conversation.
metadata:
type: object
additionalProperties: true
Conversation:
type: object
properties:
id:
type: string
status:
$ref: '#/components/schemas/ConversationStatus'
channel:
type: string
end_user:
$ref: '#/components/schemas/EndUser'
resolution:
type: string
nullable: true
description: Summary of how the agent resolved the conversation, if resolved.
escalated:
type: boolean
messages:
type: array
items:
$ref: '#/components/schemas/Message'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
ConversationList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Conversation'
next_cursor:
type: string
nullable: true
EndUser:
type: object
properties:
id:
type: string
description: Your stable identifier for the end user.
email:
type: string
format: email
name:
type: string
attributes:
type: object
additionalProperties: true
description: Traits used by workflows (e.g. plan, region, account state).
CreateMessageRequest:
type: object
required:
- role
- content
properties:
role:
type: string
enum:
- end_user
- agent
description: Author of the message.
content:
type: string
Message:
type: object
properties:
id:
type: string
conversation_id:
type: string
role:
type: string
enum:
- end_user
- agent
- system
content:
type: string
created_at:
type: string
format: date-time
MessageList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Message'
next_cursor:
type: string
nullable: true
CreateWebhookRequest:
type: object
required:
- url
- events
properties:
url:
type: string
format: uri
description: HTTPS endpoint that will receive signed event deliveries.
events:
type: array
items:
$ref: '#/components/schemas/EventType'
secret:
type: string
description: >-
Shared secret used to compute the HMAC signature on deliveries so you
can verify authenticity before acting.
WebhookSubscription:
type: object
properties:
id:
type: string
url:
type: string
format: uri
events:
type: array
items:
$ref: '#/components/schemas/EventType'
created_at:
type: string
format: date-time
EventType:
type: string
enum:
- conversation.created
- conversation.updated
- conversation.resolved
- conversation.escalated
- message.created
description: Lorikeet event types delivered to webhook subscribers.
IngestKnowledgeRequest:
type: object
properties:
type:
type: string
enum:
- url
- document
- article
url:
type: string
format: uri
description: Source URL when `type` is `url` or `article`.
title:
type: string
content:
type: string
description: Inline content when `type` is `document`.
KnowledgeSource:
type: object
properties:
id:
type: string
type:
type: string
enum:
- url
- document
- article
title:
type: string
status:
type: string
enum:
- pending
- processing
- ready
- failed
description: Asynchronous ingestion status.
created_at:
type: string
format: date-time
Error:
type: object
properties:
error:
type: object
properties:
type:
type: string
message:
type: string