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 Tools​

  • HTTP Client - curl, Postman, or any HTTP client library
  • Development Environment - .NET 6+, Python 3.8+, or Node.js 16+ (depending on your preferred language)
  • API Credentials - Access to Hyland Experience platform with appropriate permissions

Required Knowledge​

  • Basic understanding of RESTful APIs
  • Familiarity with JSON format
  • Understanding of OAuth 2.0 authentication (for production use)

System Requirements​

  • API Endpoint Access - Your base URL will be provided during onboarding
  • Network Access - Ability to make HTTPS requests to the API endpoints
  • TLS 1.2+ - Support for modern TLS encryption

Account Setup Process​

Step 1: Obtain API Credentials​

Account Provisioning

Contact your Hyland representative to provision your Knowledge Discovery account and obtain your API credentials.

You'll need:

  • Base IAM URL - Example: https://auth.iam.experience.hyland.com/
  • Base API URL - Example: https://discovery.experience.hyland.com/
  • Environment Key - Your unique environment key identifier
  • Client ID - Your application's client identifier
  • Client Secret - Your application's client secret
  • Username/Password - (for standard user authentication)

Step 2: Install Required SDKs (Optional)​

curl is typically pre-installed on most systems. Verify with:

curl --version

Step 3: 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="openid profile hxp iam.permissions.bulk hxai-insight-discovery"
export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"
export USERNAME="your-username"  # For standard user authentication
export PASSWORD="your-password"  # For standard user authentication

Step 4: 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.

Standard Users (with username/password):

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

grant_type=password&username={{username}}&password={{password}}&scope={{scope}}&client_id={{client_id}}&client_secret={{client_secret}}

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile hxp iam.permissions.bulk hxai-insight-discovery"
}

For Service Users (machine-to-machine):

### Get Access Token (Service User)
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 5: 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 4
  • 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 4)
  • Discovery App subscription with environment access
  • 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.