Integration Endpoints Tutorial

This tutorial demonstrates how third-party systems can integrate with Knowledge Discovery using dedicated integration endpoints. These endpoints are designed specifically for external systems like Alfresco or other content management platforms that need to provide Knowledge Discovery capabilities to their users.

What Are Integration Endpoints?

Integration endpoints provide a specialized API surface for external systems to interact with Knowledge Discovery on behalf of their users. Unlike standard endpoints that assume direct user authentication, integration endpoints support a service-to-service authentication model where:

A service user (the integration system) authenticates with Knowledge Discovery
The service submits requests on behalf of external users from its system
Each request includes context about which external user is making the request
Access control and data isolation ensure users can only see their own data

Key Differences from Standard Endpoints

Aspect	Standard Endpoints	Integration Endpoints
Authentication	JWT Token	JWT Token
User Context	Implicit from token	Explicit `userId` parameter required to pass the service user for the integration. Actual user is passed through `externalUserId` field [Only relevant for prompt processing]
Agent Filtering	Optional `sourceId`	Required `sourceId` parameter
Use Case	Direct user access via UI/app	System-to-system integration

When to Use Integration Endpoints

Use integration endpoints when:

Building integrations for third-party systems (Alfresco, etc.)

Use standard endpoints when:

Building direct user-facing applications
Users authenticate directly with Knowledge Discovery
No intermediary service layer is needed

Prerequisites

Before starting this tutorial, ensure you have:

Authentication: Valid JWT access token with hxp.integrations scope
Roles:: hxai-insight-discovery.manager or hxai-insight-discovery.user roles are required
Agent Configuration: At least one agent configured with appropriate access rights for your service account
Source ID: A valid source ID that your agents are associated with
Environment Setup: Access to a Knowledge Discovery environment (dev, staging, or prod)

Tutorial Overview

In this tutorial, you'll learn to:

Retrieve agents accessible to your integration using the sourceId filter
Get detailed agent configuration for question submission
Submit questions on behalf of external users
Poll and retrieve answers with proper user context

By the end of this tutorial, you'll be able to implement a production-ready integration between your system and Knowledge Discovery.

Authentication Context

Service User vs. External User

The integration endpoints use a dual-user model:

Service User:

Your integration system's service account
Authenticates via JWT token
Has permissions to access integration endpoints
Acts as a proxy for external users

External User:

A user in your system (e.g., user in Alfresco)
Identified by a UUID (userId parameter)
Does not directly authenticate with Knowledge Discovery
Data is isolated per external user

How It Works

Your service authenticates and receives a JWT token
When submitting requests, you include the external userId
Knowledge Discovery associates data with that external user
The external user can only access their own questions and answers
Your service account must have rights to the agents being accessed

Part 1: Retrieve Agents for Integration

The first step in any integration workflow is discovering which agents are available for your source.

List Agents by Source ID

HTTP
curl

GET {{baseUrl}}/agent/integrations/agents?sourceId={{sourceId}}
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

SOURCE_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X GET "${DISCOVERY_API_BASE_URL}/agent/integrations/agents?sourceId=${SOURCE_ID}" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: ${APP_KEY}"

Understanding the sourceId Parameter

The sourceId parameter is required for integration endpoints, unlike the standard agent endpoint where it's optional. This ensures that:

Your integration only sees agents associated with your data sources
Multi-tenant isolation is maintained
Agent discovery is scoped appropriately

Required Parameter

Omitting the sourceId parameter will result in a 400 Bad Request error. This is a key difference from the standard /agents endpoint.

Response Structure

[
  {
    "id": "agent-uuid-here",
    "name": "HR Documents Agent",
    "description": "Answers questions about HR policies and procedures",
    "modelName": "bedrock-amazon-nova-micro",
    "version": 1,
    "isLatest": true,
    "avatarUrl": "https://example.com/avatar.png",
    "instructions": "You are an HR assistant...",
    "sourceIds": ["550e8400-e29b-41d4-a716-446655440000"],
    "accessRights": [
      {
        "id": "service-user-id",
        "type": "User"
      }
    ],
    "staticFilterExpression": null,
    "createdBy": "admin-user-id",
    "createdOn": "2025-01-10T10:00:00Z",
    "modifiedBy": "admin-user-id",
    "modifiedOn": "2025-01-10T10:00:00Z"
  }
]

Key Response Fields

Field	Type	Description
`id`	UUID	Unique agent identifier
`name`	string	Agent display name
`sourceIds`	array	Data source IDs this agent can access
`version`	integer	Agent version number
`isLatest`	boolean	Whether this is the latest version
`accessRights`	array	Users/groups with access to this agent

Access Rights Validation

Agents are filtered based on your service account's access rights. You'll only see agents where:

Your service user ID appears in the accessRights list, OR
A group you belong to appears in the accessRights list

If no agents are returned, verify that your service account has been granted access to agents for the specified sourceId.

Part 2: Retrieve Specific Agent Details

Once you've identified an agent, retrieve its full configuration before submitting questions.

Get Agent by ID

HTTP
curl

GET {{baseUrl}}/agent/integrations/agents/{{agentId}}
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

AGENT_ID="agent-uuid-here"

curl -X GET "${DISCOVERY_API_BASE_URL}/agent/integrations/agents/${AGENT_ID}" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: ${APP_KEY}"

Response

The response includes complete agent configuration identical to the list response, but for a single agent.

Verifying Agent Configuration

Before submitting questions, verify:

The agent's sourceIds include your integration's source
Your service account appears in accessRights
The agent is active (isLatest: true or use specific version)
The agent has appropriate instructions for your use case

Part 3: Submit Questions via Integration Endpoint

Submit questions on behalf of external users using the integration-specific endpoint.

Submit Question Request

HTTP
curl

POST {{baseUrl}}/agent/integrations/agents/{{agentId}}/questions
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "question": "What is the vacation policy for new employees?",
  "userId": "12345678-90ab-cdef-1234-567890abcdef",
  "contextObjectIds": [
    "doc-uuid-1",
    "doc-uuid-2"
  ]
}

AGENT_ID="agent-uuid-here"
EXTERNAL_USER_ID="12345678-90ab-cdef-1234-567890abcdef"

curl -X POST "${DISCOVERY_API_BASE_URL}/agent/integrations/agents/${AGENT_ID}/questions" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: ${APP_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the vacation policy for new employees?",
    "userId": "'"${EXTERNAL_USER_ID}"'",
    "contextObjectIds": [
      "doc-uuid-1",
      "doc-uuid-2"
    ]
  }'

Request Body Parameters

Parameter	Required	Type	Description
`question`	Yes	string	The natural language question text
`userId`	Yes	UUID	External user identifier from your system
`contextObjectIds`	Yes	array	Document IDs to use as context for the question

External User ID

The userId should be a stable, unique identifier for users in your system. This ID will be used to retrieve answers and ensure data isolation.

Response

{
  "questionId": "c9d6f822-e88c-48a7-bfb9-1f91e7214b40"
}

The endpoint returns 202 Accepted immediately with a questionId. The question is processed asynchronously.

Understanding Asynchronous Processing

Immediate Return: The POST request returns quickly with a question ID
Background Processing: Knowledge Discovery processes the question asynchronously
Polling Required: You must poll the answer endpoint to retrieve results
Typical Duration: Processing usually takes 2-15 seconds depending on complexity

Context Object IDs

The contextObjectIds parameter allows you to scope the question to specific documents.

Part 4: Retrieve Answers via Integration Endpoint

After submitting a question, poll for the answer using the integration-specific endpoint.

Get Answer with User Context

HTTP
curl

GET {{baseUrl}}/qna/integrations/questions/{{questionId}}/answer?userId={{userId}}
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

QUESTION_ID="c9d6f822-e88c-48a7-bfb9-1f91e7214b40"
EXTERNAL_USER_ID="12345678-90ab-cdef-1234-567890abcdef"

curl -X GET "${DISCOVERY_API_BASE_URL}/qna/integrations/questions/${QUESTION_ID}/answer?userId=${EXTERNAL_USER_ID}" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: ${APP_KEY}"

Required userId Parameter

The userId query parameter is required and must match the userId used when submitting the question. This ensures:

Data isolation between external users
Users can only access their own questions and answers
Security boundary enforcement

Security Boundary

If the userId doesn't match the question's author, you'll receive a 404 Not Found error (not 403 Forbidden) to prevent information leakage about which questions exist.

Response Structure

{
  "answer": "New employees are eligible for 15 days of paid vacation per year. This includes holidays and personal days. Vacation accrual begins immediately upon hire, but vacation time cannot be used during the first 90 days of employment.",
  "agentId": "agent-uuid-here",
  "agentVersion": 1,
  "responseCompleteness": "Complete",
  "objectReferences": [
    {
      "objectId": "doc-uuid-1",
      "references": [
        {
          "referenceId": "chunk-456",
          "rankScore": 0.95,
          "rank": 1
        }
      ]
    }
  ],
  "question": "What is the vacation policy for new employees?",
  "feedback": null,
  "staticFilter": null,
  "dynamicFilter": null
}

Response Completeness States

State	Meaning	Action
`Submitted`	Question is still being processed	Continue polling
`Complete`	Answer has been generated	Display to user
`Error`	An error occurred during processing	Check logs, retry if appropriate

Object References

The objectReferences array contains source attribution:

{
  "objectId": "doc-uuid-1",
  "references": [
    {
      "referenceId": "chunk-456",
      "rankScore": 0.95,
      "rank": 1
    }
  ]
}

objectId: Document that contained relevant information
referenceId: Specific chunk/section within the document
rankScore: Relevance score (0.0 to 1.0)
rank: Ranking position (1 = most relevant)

Use these references to:

Show source documents in your UI
Create deep links to relevant sections
Validate answer accuracy
Improve user trust through transparency

Complete Workflow Diagram

Part 6: Access Control and Security

Understanding the security model is critical for proper integration implementation.

Access Rights Model

Knowledge Discovery uses a multi-layered access control system:

Layer 1: Service Account Rights

Your service account must have the hxp.integrations scope assigned

Layer 2: Agent Access Rights

Each agent has an accessRights list
Your service account must appear in this list (directly or via group membership)
Only agents you have rights to will be returned by the API

Layer 3: External User Isolation

Each question is associated with an external userId
Users can only retrieve their own questions and answers
The system enforces this through the required userId query parameter

Why userId Must Be Provided

The userId parameter serves multiple critical purposes:

Data Isolation: Ensures users only see their own data
Audit Trail: Tracks which external user asked which question
Analytics: Enables per-user usage tracking and reporting
Security Boundary: Prevents cross-user data access
Compliance: Supports data privacy requirements (GDPR, etc.)

Service User vs. External User

Security Boundaries

What Your Service Can Do:

List agents for your sourceId
Submit questions for any external user
Retrieve answers for any external user (with their userId)

What Your Service Cannot Do:

Access agents without proper access rights
Retrieve answers without providing the correct userId
Access questions/answers for external users in other integrations
Bypass the sourceId filter requirement

What External Users Cannot Do:

Directly authenticate with Knowledge Discovery
Access other external users' questions/answers
Submit questions without going through the service

Source ID Filtering

The required sourceId parameter provides:

Tenant Isolation:

When Source A queries, it only sees Agents 1 and 2. When Source B queries, it only sees Agents 3 and 4.

Data Scoping:

Agents are associated with specific data sources
Questions are answered using documents from those sources
This prevents cross-contamination between different systems

Access Control:

Your service account has access to specific sourceIds
This is configured at the tenant/subscription level
Attempting to use an unauthorized sourceId will fail

Best Practices

Never Share Service Credentials:
- Protect your service JWT token
- Rotate credentials regularly
- Use secure storage (Azure Key Vault, AWS Secrets Manager)
Validate External User IDs:
- Ensure userId is a valid user in your system
- Don't allow arbitrary userId values from client input
- Use server-side validation
Implement Rate Limiting:
- Protect against abuse by limiting requests per user
- Implement per-user quotas if needed
- Monitor usage patterns
Log Security Events:
- Log all question submissions with userId
- Track access denied errors (403, 404)
- Monitor for suspicious patterns
Handle Errors Gracefully:
- Don't expose internal error details to end users
- Log full error details server-side
- Provide user-friendly error messages

Key Takeaways

Service-to-Service Model: Integration endpoints use a proxy pattern where your service authenticates and acts on behalf of external users
Required Parameters: Always include sourceId when listing agents and userId when retrieving answers
Data Isolation: External users can only access their own questions and answers through the userId mechanism
Asynchronous Processing: Question answering is asynchronous; implement polling with appropriate intervals and timeouts
Access Control: Your service account must have proper permissions and agent access rights
Security First: Protect service credentials, validate user IDs, and implement proper error handling

Next Steps

Explore Agent Management: Learn how to create and configure agents for your integration
Review Authentication Guide: Understand advanced authentication patterns and token management
Check API Reference: Review complete endpoint documentation and schemas
Monitor Performance: Set up monitoring and alerting for your integration
Production Deployment: Follow deployment best practices and scaling guidelines

Get Help

If you encounter issues or need assistance with your integration:

Review error messages and status codes carefully

Consult the API reference documentation

Contact Hyland Support with specific error details and request/response examples

What Are Integration Endpoints?​

Key Differences from Standard Endpoints​

When to Use Integration Endpoints​

Prerequisites​

Tutorial Overview​

Authentication Context​

Service User vs. External User​

How It Works​

Part 1: Retrieve Agents for Integration​

List Agents by Source ID​

Understanding the sourceId Parameter​

Response Structure​

Key Response Fields​

Access Rights Validation​

Part 2: Retrieve Specific Agent Details​

Get Agent by ID​

Response​

Verifying Agent Configuration​

Part 3: Submit Questions via Integration Endpoint​

Submit Question Request​

Request Body Parameters​

Response​

Understanding Asynchronous Processing​

Context Object IDs​

Part 4: Retrieve Answers via Integration Endpoint​

Get Answer with User Context​

Required userId Parameter​

Response Structure​

Response Completeness States​

Object References​

Complete Workflow Diagram​

Part 6: Access Control and Security​

Access Rights Model​

Why userId Must Be Provided​

Service User vs. External User​

Security Boundaries​

Source ID Filtering​

Best Practices​

Key Takeaways​

Next Steps​

What Are Integration Endpoints?

Key Differences from Standard Endpoints

When to Use Integration Endpoints

Prerequisites

Tutorial Overview

Authentication Context

Service User vs. External User

How It Works

Part 1: Retrieve Agents for Integration

List Agents by Source ID

Understanding the sourceId Parameter

Response Structure

Key Response Fields

Access Rights Validation

Part 2: Retrieve Specific Agent Details

Get Agent by ID

Response

Verifying Agent Configuration

Part 3: Submit Questions via Integration Endpoint

Submit Question Request

Request Body Parameters

Response

Understanding Asynchronous Processing

Context Object IDs

Part 4: Retrieve Answers via Integration Endpoint

Get Answer with User Context

Required userId Parameter

Response Structure

Response Completeness States

Object References

Complete Workflow Diagram

Part 6: Access Control and Security

Access Rights Model

Why userId Must Be Provided

Service User vs. External User

Security Boundaries

Source ID Filtering

Best Practices

Key Takeaways

Next Steps