Testing the API

You can test the Agent Builder API using Bruno or any API client that supports OpenAPI imports (Postman, Swagger UI, etc.).

Prerequisites

• An API client installed (Bruno, Postman, etc.)
• OAuth client credentials configured in NCP IAM (see Authentication)

Import the OpenAPI Spec

Download the OpenAPI Spec

Download openapi.yaml — the full Agent Builder API specification for use with any OpenAPI-compatible client.

1. Download the OpenAPI spec using the link above
2. Import it into your API client:
   • Bruno: Open Collection > Import > OpenAPI, select the YAML file
   • Postman: Import > Upload Files, select the YAML file

This gives you all endpoints with their request schemas, parameters, and response types.

Environment Setup

After importing, configure these variables in your client's environment:

Variable	Value
BASE_URL	https://agent-builder.ai.experience.hyland.com/latest (adjust per environment)
AUTH_URL	https://auth.iam.<ENV>.experience.hyland.com
CLIENT_ID	Your OAuth client ID
CLIENT_SECRET	Your OAuth client secret

Get an Access Token

curl -X POST https://auth.iam.<ENV>.experience.hyland.com/idp/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>" \
  -d "scope=hxp environment_authorization" \
  -d "grant_type=client_credentials"

Use the access_token from the response as a Bearer token in the Authorization header for all subsequent requests.

Walkthrough

This walkthrough demonstrates the complete lifecycle using cURL: authenticate, create a Tool agent, invoke it, stream a response, and clean up.

Step 1: Get an Access Token

curl -s -X POST "https://auth.iam.<ENV>.experience.hyland.com/idp/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>" \
  -d "scope=hxp environment_authorization" \
  -d "grant_type=client_credentials"

Response:

{
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "hxp environment_authorization"
}

Save the token for subsequent requests:

export TOKEN="eyJhbGciOiJSUzI1NiIs..."
export BASE_URL="https://agent-builder.ai.experience.hyland.com/latest"

Step 2: Create a Tool Agent

curl -s -X POST "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TestCalculator",
    "description": "A test calculator agent",
    "agentType": "tool",
    "config": {
        "llmModelId": "anthropic.claude-3-haiku-20240307-v1:0",
        "systemPrompt": "You are a helpful assistant with access to a multiply tool.",
        "tools": [
            {
                "toolType": "function",
                "name": "multiply",
                "description": "Multiplies two numbers",
                "funcName": "multiply"
            }
        ],
        "inferenceConfig": {
            "maxTokens": 1000,
            "temperature": 0.0
        }
    }
}'

Response:

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "TestCalculator",
    "description": "A test calculator agent",
    "agentType": "tool",
    "version": 1,
    "config": { ... }
}

Save the agent ID:

export AGENT_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Step 3: Invoke the Agent

curl -s -X POST "$BASE_URL/v1/agents/$AGENT_ID/versions/latest/invoke" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
        {
            "role": "user",
            "content": "What is 7 times 8?"
        }
    ]
}'

Response:

{
    "object": "response",
    "createdAt": 1741705500,
    "model": "anthropic.claude-3-haiku-20240307-v1:0",
    "output": [
        {
            "type": "message",
            "status": "completed",
            "role": "assistant",
            "content": [
                {
                    "type": "output_text",
                    "text": "The result of 7 times 8 is 56."
                }
            ]
        }
    ]
}

Step 4: Stream a Response

curl -N -X POST "$BASE_URL/v1/agents/$AGENT_ID/versions/latest/invoke-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
        {
            "role": "user",
            "content": "Explain how multiplication works."
        }
    ]
}'

Response (streamed line-by-line):

{"type": "response.created", "response": {"id": "resp-id", "model": "anthropic.claude-3-haiku-20240307-v1:0", "object": "response", "createdAt": 1760632921}}
{"type": "response.output_text.delta", "role": "assistant", "delta": "Multiplication is ", "id": "resp-id"}
{"type": "response.output_text.delta", "role": "assistant", "delta": "repeated addition...", "id": "resp-id"}
{"type": "response.completed", "response": {"id": "resp-id", "model": "anthropic.claude-3-haiku-20240307-v1:0", "object": "response", "createdAt": 1760632921}}

Each line is a self-contained JSON object. Concatenate the delta fields to form the full response text.

Step 5: Delete the Agent

curl -s -X DELETE "$BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns 200 OK on success.

Importing the OpenAPI Spec

No pre-built collection is provided, but you can import the OpenAPI spec directly into your preferred API client:

• Bruno: Open Collection > Import > OpenAPI, select the downloaded YAML file
• Postman: Import > Upload Files, select the YAML file

This gives you all endpoints pre-configured with their request schemas, parameters, and response types.

Common Errors

Status	Error	Cause	Fix
400	Bad Request	Invalid configuration, missing required fields, or invalid parameter values	Check request body against the API spec. Ensure all required fields are present and correctly typed.
401	Unauthorized	Missing or expired access token	Re-request a token using the authentication endpoint. Tokens expire after the expires_in period.
403	Forbidden	Insufficient IAM permissions for the requested operation	Verify your IAM user group has the required permissions (READ, CREATE, EDIT, INVOKE, DELETE).
404	Not Found	Agent ID or version does not exist	Verify the agent ID is correct. Use GET /v1/agents to list available agents.
N/A	Token request fails	Incorrect client credentials, wrong AUTH_URL, or missing scopes	Double-check CLIENT_ID, CLIENT_SECRET, AUTH_URL, and ensure you request both hxp and environment_authorization scopes.