Skip to main content

Getting Started

This guide will help you set up your environment and make your first API calls to Knowledge Discovery.

Prerequisites​

Before you begin, ensure you have:

Required Access​

  • Admin Portal Access - Administrative access to the Hyland Experience Admin Portal to create Service Users and configure External Applications
  • Active Subscription - Knowledge Discovery App Subscription in your Environment

Required Knowledge​

  • Basic understanding of RESTful APIs
  • Familiarity with JSON format
  • Understanding of OAuth 2.0 authentication

Required Tools​

  • HTTP Client - curl, Postman, or any HTTP client library

Account Setup Process​

Step 1: Create Service User​

To use the Knowledge Discovery API, you need a Service User - a user account with access to the environment and the Knowledge Discovery app. This user has a mapped External Application (Client) that is used to obtain authentication tokens.

Service User Creation Process​

Follow these steps to create a Service User and configure the required External Application:

  1. Log in to the Admin Portal:

  2. Navigate to Service Users:

    • In the top navigation menu, select Identity
    • From the left-hand panel, expand the Users section
    • Click on Service Users

  3. Create Service User:

    • On the right side, click Create Service User
    • Complete the Create Service User form with the following details:
      • User Name: <service-name> (e.g., discovery-api-user)
      • User Group: Select the appropriate Discovery group for your environment
        note

        Choose the group that corresponds to the Discovery Manager or User role for your specific environment. For example, this might be "Discovery - Managers" or similar, depending on your environment configuration.

  4. Register New Client:

    • Application Name: <client-id> (e.g., discovery-api-client)
      note

      This creates a new External Application (Client) and generates both a Client ID and Client Secret. Important: Securely record the Client Secret immediately after creation, as it will not be displayed again.

  5. Configure Client Scopes:

    • Click on the External Systems tab
    • Find and open the newly created External Application
    • Ensure the following scopes are selected:
      • hxp
      • hxp.integrations
      • iam.jti-capture
      • openid
      • profile
    • Click Save to apply the configuration

After completing these steps, you will have the credentials needed for API authentication.

  • Base IAM URL - e.g. https://auth.iam.experience.hyland.com/
  • Base API URL - e.g. https://discovery.experience.hyland.com/
  • Environment Key - Your unique environment key identifier
  • Client ID - Your client identifier
  • Client Secret - Your client secret

Step 2: Configure Environment Variables​

Set up your environment variables for secure credential storage:

# In your shell or .env file
export IAM_BASE_URL="https://auth.iam.experience.hyland.com/"
export DISCOVERY_API_BASE_URL="https://discovery.experience.hyland.com/"
export ENVIRONMENT_KEY="your-environment-key"
export APP_KEY="hxai-discovery"
export SCOPE="hxp hxp.integrations hxai-insight-discovery iam.jti-capture"
export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"

Step 3: Retrieve Access Token​

Before making API calls, you need to authenticate and obtain an access token.

Authentication Details

For more information about authentication methods, token refresh, and security best practices, see the Authentication documentation.

### Get Access Token
POST {{iam_base_url}}/idp/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials &
scope={{scope}} &
client_id={{client_id}} &
client_secret={{client_secret}}

Step 4: Verify API Access​

Test your connection to the API by retrieving the list of agents:

### Get Agents - Verify API Access
GET {{baseUrl}}/agent/agents
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

Response (200 OK):

[
  {
    "id": "agent-guid-1",
    "name": "HR Knowledge Agent",
    "version": 1,
    "modelName": "bedrock-amazon-nova-micro",
    "description": "Agent specialized in HR policies"
  }
]

For Postman/Bruno: Create environment variables:

  • baseUrl: Your DISCOVERY_API_BASE_URL
  • accessToken: Your access token from Step 3
  • environmentKey: Your environment key
  • appKey: hxai-discovery
First Time Setup

If you haven't created any agents yet, this will return an empty array []. This is normal - you'll create your first agent in the Quick Start Guide below.

Quick Start Guide​

Follow this simple end-to-end example to create an agent and ask a question.

tip

For more detailed tutorials and advanced scenarios, see the Tutorials section.

Prerequisites​

  • Valid authentication token (from Step 3)
  • User with Discovery Manager role

Step 1: Create an Agent​

### Create Agent
POST {{baseUrl}}/agent/agents
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "name": "HR Knowledge Agent",
  "description": "Agent specialized in HR policies and procedures",
  "modelName": "bedrock-amazon-nova-micro",
  "instructions": "You are an HR assistant. Provide helpful and accurate information based on company policies.",
  "sourceIds": ["your-source-id-guid"],
  "accessRights": [
    { "type": "Group", "id": "hr-team-guid" }
  ]
}

Step 2: Submit a Question​

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

{
  "question": "What is the company's vacation policy for new employees?"
}

Response: 202 Accepted - The question is submitted for asynchronous processing.

Asynchronous Processing

The POST endpoint returns 202 Accepted immediately. The answer is generated asynchronously in the background. You must poll the GET endpoint in Step 3 to retrieve the completed answer.

Step 3: Retrieve the Answer​

### Get Answer
GET {{baseUrl}}/qna/questions/{{questionId}}/answer
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

Note: Wait a few seconds after submitting the question before retrieving the answer, or use polling logic.

Example Response:

{
  "answer": "The company's vacation policy provides new employees with 15 days of paid vacation per year. This increases to 20 days after 5 years of service and 25 days after 10 years. Vacation days must be requested in advance and approved by your manager.",
  "agentId": "agent-id-from-step-1",
  "agentVersion": 1,
  "responseCompleteness": "Complete",
  "objectReferences": [
    {
      "objectId": "hr-policy-doc-123",
      "references": [
        {
          "referenceId": "section-4.2",
          "rankScore": 0.95,
          "content": "Vacation Policy: New employees receive 15 days..."
        }
      ]
    }
  ],
  "question": "What is the company's vacation policy?",
  "feedback": null,
  "staticFilter": null,
  "dynamicFilter": null
}

Response Fields:

  • answer - The generated answer text
  • responseCompleteness - Status: Submitted, Complete, or Error
  • objectReferences - Source documents that support the answer
  • feedback - User feedback (null until submitted)

Next Steps​

Congratulations! You've successfully created an agent and asked your first question. Here's what to explore next:

🔐 Authentication

Learn about authentication methods, OAuth 2.0 flows, and service users.

Learn More

📚 Tutorials

Follow comprehensive tutorials for agent management, filtering, and Q&A workflows.

View Tutorials

Common Issues​

Connection Refused or Timeout

Ensure your network allows HTTPS connections to the API endpoint. Check firewall rules and proxy settings.

401 Unauthorized

Your access token may be expired or invalid. Refresh your token or verify your credentials are correct.

404 Not Found

Verify the base URL and endpoint paths are correct. Ensure you're using the correct environment (dev, staging, production).

Need Help?

If you encounter issues not covered here, consult the Error Reference or contact Hyland Support.