Call the API
This guide walks you through obtaining a token using Client Credentials authentication and conversing with an agent via SSE.
Introduction
Here are the quickest steps to use the Marketplace API. You can start conversing with an agent in just three steps.
- Setup of the AGENTIC STAR environment purchased from Marketplace is complete
- A service account has been created in the admin console
- You have Base URL, Client ID, Client Secret, and Agent ID
Step 1: Verify Authentication Information
Gather the information you need to call the Chat API from your administrator and the admin console. Note that these values are checked in different places.
From your administrator
- Base URL — The domain of the external API (
https://<your-domain>), decided by the administrator when building the environment - Authentication service domain — Where to get tokens (
https://<auth-domain>), decided by the administrator when building the environment
From the Service Account detail screen
- Client ID — Client ID issued for the service account
- Client Secret — Secret issued for the service account
From the admin console
- Agent ID — Identifier to pass as the
agentIdparameter in Chat API calls. Available on the detail page of the target agent under AI Agents → Marketplace AI Agents in the admin console (see Settings Guide — Marketplace AI Agents). You can also get the list withGET /v1/marketplace-agents.
Authentication Information Example
Base URL: https://<your-domain>
Auth URL: https://<auth-domain>
Client ID: mp-service-001
Client Secret: (hidden)
Agent ID: agent-ai-bot
Step 2: Obtain Token
Use the Client Credentials flow to obtain an access token. Execute the following request from your server.
Request Example
1curl -X POST https://<auth-domain>/api/v1/oauth/token \2-u "<your-client-id>:<your-client-secret>" \3-H "Content-Type: application/x-www-form-urlencoded" \4-d "grant_type=client_credentials"curl -X POST https://<auth-domain>/api/v1/oauth/token \ -u "<your-client-id>:<your-client-secret>" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials"
import requests
response = requests.post(
"https://<auth-domain>/api/v1/oauth/token",
auth=("<your-client-id>", "<your-client-secret>"),
data={"grant_type": "client_credentials"},
)
token = response.json()["access_token"]
print(token)const credentials = btoa("<your-client-id>:<your-client-secret>");
const response = await fetch("https://<auth-domain>/api/v1/oauth/token", {
method: "POST",
headers: {
Authorization: `Basic ${credentials}`,
"Content-Type": "application/x-www-form-urlencoded",
},
body: new URLSearchParams({ grant_type: "client_credentials" }),
});
const { access_token } = await response.json();
console.log(access_token);package main
import (
"encoding/json"
"fmt"
"net/http"
"net/url"
"strings"
)
func main() {
form := url.Values{"grant_type": {"client_credentials"}}
req, _ := http.NewRequest(
"POST",
"https://<auth-domain>/api/v1/oauth/token",
strings.NewReader(form.Encode()),
)
req.SetBasicAuth("<your-client-id>", "<your-client-secret>")
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["access_token"])
}Parameters
<auth-domain>: Authentication service domain verified in Step 1 (example: auth.example.com)<your-client-id>: Client ID verified in Step 1<your-client-secret>: Secret verified in Step 1
Response Example
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"scope": "openid profile email"
}
The previous POST https://<auth-domain>/api/v1/auth/external-service-token (JSON body with client_id and client_secret) also continues to work. For details, see the Authentication Guide.
The token is valid for the number of seconds specified in expires_in. Obtain a new token before expiration. The Client Credentials flow does not issue refresh tokens, so after expiration, execute the same request again.
Step 3: Call Chat API
Use the obtained access token to call the Chat API via SSE (Server-Sent Events). You will receive real-time responses from the agent in stream format.
Request Example
1curl -X POST https://<your-domain>/api/v1/chat/completions \2-H "Authorization: Bearer <access_token>" \3-H "Content-Type: application/json" \4-d '{5 "model": "AGENTIC STAR",6 "stream": true,7 "agentId": "<your-agent-id>",8 "messages": [9 {10 "role": "user",11 "content": "Hello"12 }13 ]14}'curl -X POST https://<your-domain>/api/v1/chat/completions \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"model": "AGENTIC STAR",
"stream": true,
"agentId": "<your-agent-id>",
"messages": [
{
"role": "user",
"content": "Hello"
}
]
}'import requests
import json
response = requests.post(
"https://<your-domain>/api/v1/chat/completions",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
},
json={
"model": "AGENTIC STAR",
"stream": True,
"agentId": "<your-agent-id>",
"messages": [{"role": "user", "content": "Hello"}],
},
stream=True,
)
for line in response.iter_lines():
if line:
data = line.decode("utf-8")
if data == "data: [DONE]":
break
if data.startswith("data: "):
chunk = json.loads(data[6:])
content = chunk["choices"][0]["delta"].get("content", "")
print(content, end="", flush=True)const response = await fetch(
"https://<your-domain>/api/v1/chat/completions",
{
method: "POST",
headers: {
"Authorization": `Bearer ${accessToken}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "AGENTIC STAR",
stream: true,
agentId: "<your-agent-id>",
messages: [{ role: "user", content: "Hello" }],
}),
}
);
const reader = response.body?.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader?.read() || { done: true };
if (done) break;
for (const line of decoder.decode(value).split("\n")) {
if (line.startsWith("data: ") && line !== "data: [DONE]") {
const chunk = JSON.parse(line.slice(6));
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
}
}package main
import (
"bufio"
"bytes"
"encoding/json"
"fmt"
"net/http"
"strings"
)
func main() {
token := "<access_token>" // Access token obtained in Step 2
body, _ := json.Marshal(map[string]interface{}{
"model": "AGENTIC STAR",
"stream": true,
"agentId": "<your-agent-id>",
"messages": []map[string]string{
{"role": "user", "content": "Hello"},
},
})
req, _ := http.NewRequest("POST",
"https://<your-domain>/api/v1/chat/completions",
bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
line := scanner.Text()
if strings.HasPrefix(line, "data: ") {
data := line[6:]
if data == "[DONE]" { break }
var chunk map[string]interface{}
json.Unmarshal([]byte(data), &chunk)
choices, _ := chunk["choices"].([]interface{})
if len(choices) > 0 {
delta, _ := choices[0].(map[string]interface{})["delta"].(map[string]interface{})
if content, ok := delta["content"].(string); ok {
fmt.Print(content)
}
}
}
}
}Parameters
<access_token>: Access token obtained in Step 2<your-agent-id>: Agent ID verified in Step 1stream: true: Enable SSE streamingmessages: Message from user. Multiple messages can be sent in array format
Response Example (SSE Stream)
data: {"choices":[{"delta":{"content":"Hello"}}]}
data: {"choices":[{"delta":{"content":", how can I"}}]}
data: {"choices":[{"delta":{"content":"help you?"}}]}
data: [DONE]
For readability, the snippet above only shows delta.content. Actual chunks include additional fields such as createdAt / model / choices[].index / finishReason. See the API Reference for the complete format.
The response is in Server-Sent Events (SSE) format, sent in real-time in chunks. Each chunk is in the format data: JSON. The conversation completes with data: [DONE]. See Streaming Guide for details.
Next Steps
For more detailed information and implementation patterns, see the following documentation.