Overview
The REST API Gateway provides HTTP/HTTPS access to Solace Agent Mesh agents with support for:
- Synchronous and asynchronous task execution
- Server-Sent Events (SSE) for real-time streaming
- File upload and download
- Session management
- Agent discovery
Base URL
http://localhost:8080/api/v1
/api/v1.
Authentication
Development Mode
When enforce_authentication: false:
curl http://localhost:8080/api/v1/agent-cards
Production Mode
When enforce_authentication: true, include bearer token:
curl -H "Authorization: Bearer YOUR_TOKEN" \
http://localhost:8080/api/v1/agent-cards
Core Endpoints
Execute Task
Execute a task on an agent asynchronously.
Create and execute a new task.
{
"agentName": "FileSystemAgent",
"sessionId": "user123_session",
"message": {
"text": "List all files in the current directory"
},
"metadata": {
"priority": "high",
"tags": ["filesystem", "query"]
}
}
Name of the agent to execute the task.
Session identifier for conversation history.
Message to send to the agent.Subfields:
text (string): Text message contentfiles (array): Attached file artifacts
Optional metadata for the task.
Unique identifier for the created task.
Initial task status (“queued” or “running”).
URL to connect for streaming updates.
{
"taskId": "task_abc123",
"status": "running",
"sseUrl": "/api/v1/tasks/task_abc123/stream"
}
Stream Task Updates
Connect to Server-Sent Events stream for real-time task updates.
GET /tasks/{taskId}/stream
Stream task execution updates via SSE.
Task status updates (queued, running, completed, failed).{
"taskId": "task_abc123",
"status": "running",
"timestamp": "2024-01-15T10:30:00Z"
}
Agent response messages.{
"taskId": "task_abc123",
"message": {
"text": "I found 5 files in the directory:",
"role": "agent"
}
}
Artifact creation notifications.{
"taskId": "task_abc123",
"artifact": {
"filename": "file_list.txt",
"version": 1,
"mimeType": "text/plain",
"size": 1024
}
}
Artifact upload/download progress.{
"taskId": "task_abc123",
"filename": "large_file.zip",
"status": "in-progress",
"bytesTransferred": 512000,
"totalBytes": 1048576
}
const eventSource = new EventSource(
`http://localhost:8080/api/v1/tasks/task_abc123/stream`
);
eventSource.addEventListener('task.message', (event) => {
const data = JSON.parse(event.data);
console.log('Agent response:', data.message.text);
});
eventSource.addEventListener('task.status', (event) => {
const data = JSON.parse(event.data);
if (data.status === 'completed') {
console.log('Task completed!');
eventSource.close();
}
});
Get Task Status
Retrieve current task status and results.
Get task information and final results.
Current status: “queued”, “running”, “completed”, “failed”, “cancelled”.
Task results (when status is “completed”).
Error details (when status is “failed”).
{
"taskId": "task_abc123",
"status": "completed",
"result": {
"message": {
"text": "Task completed successfully."
},
"artifacts": [
{
"filename": "result.json",
"version": 1
}
]
},
"startedAt": "2024-01-15T10:30:00Z",
"completedAt": "2024-01-15T10:30:15Z"
}
Cancel Task
Cancel a running or queued task.
Response:
{
"taskId": "task_abc123",
"status": "cancelled",
"message": "Task cancelled successfully"
}
Session Management
List Sessions
List all sessions for the authenticated user.
Maximum number of sessions to return (default: 50).
Pagination offset (default: 0).
{
"sessions": [
{
"sessionId": "user123_session",
"agentName": "FileSystemAgent",
"createdAt": "2024-01-15T10:00:00Z",
"lastActivityAt": "2024-01-15T10:30:00Z",
"messageCount": 5
}
],
"total": 1,
"limit": 50,
"offset": 0
}
Get Session History
GET /sessions/{sessionId}
Get conversation history for a session.
{
"sessionId": "user123_session",
"agentName": "FileSystemAgent",
"messages": [
{
"role": "user",
"text": "List all files",
"timestamp": "2024-01-15T10:30:00Z"
},
{
"role": "agent",
"text": "I found 5 files...",
"timestamp": "2024-01-15T10:30:05Z"
}
]
}
Delete Session
DELETE /sessions/{sessionId}
Delete a session and its history.
{
"message": "Session deleted successfully"
}
Agent Discovery
List Available Agents
Discover available agents in the mesh.
List of available agents with capabilities.
{
"agents": [
{
"agentName": "FileSystemAgent",
"displayName": "File System",
"description": "Interacts with the local filesystem",
"capabilities": {
"inputModes": ["text"],
"outputModes": ["text", "file"],
"supportsStreaming": true
},
"skills": [
{
"name": "read_files",
"description": "Read file contents"
},
{
"name": "write_files",
"description": "Create or update files"
}
]
}
]
}
Artifact Management
Upload Artifact
Upload a file as an artifact.
curl -X POST \
-F "[email protected]" \
-F "description=Important document" \
-F "sessionId=user123_session" \
http://localhost:8080/api/v1/artifacts
{
"filename": "document.pdf",
"version": 1,
"mimeType": "application/pdf",
"size": 524288,
"description": "Important document",
"uploadedAt": "2024-01-15T10:30:00Z"
}
Download Artifact
GET /artifacts/{filename}
Download an artifact file.
Specific version to download (default: latest).
Session identifier (required if artifact scope is “session”).
List Artifacts
List available artifacts.
Glob pattern to filter filenames.
{
"artifacts": [
{
"filename": "document.pdf",
"versions": [1],
"latestVersion": 1,
"mimeType": "application/pdf",
"size": 524288,
"createdAt": "2024-01-15T10:30:00Z"
}
]
}
Error Responses
All errors follow this format:
{
"error": {
"code": "INVALID_REQUEST",
"message": "Agent 'UnknownAgent' not found",
"details": {
"agentName": "UnknownAgent"
}
}
}
Error Codes
Malformed request or invalid parameters.
Missing or invalid authentication token.
Specified agent does not exist.
Specified session does not exist.
Specified task does not exist.
Specified artifact does not exist.
Rate Limiting
Default rate limits:
- 100 requests per minute per IP
- 1000 requests per hour per user
Rate limit headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000
Complete Example
Execute Task with Streaming
// 1. Create task
const createResponse = await fetch('http://localhost:8080/api/v1/tasks', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
agentName: 'FileSystemAgent',
sessionId: 'user123_session',
message: {
text: 'List all files and create a summary report',
},
}),
});
const { taskId, sseUrl } = await createResponse.json();
// 2. Connect to SSE stream
const eventSource = new EventSource(
`http://localhost:8080${sseUrl}`
);
// 3. Handle streaming updates
eventSource.addEventListener('task.message', (event) => {
const data = JSON.parse(event.data);
console.log('Agent:', data.message.text);
});
eventSource.addEventListener('artifact.created', (event) => {
const data = JSON.parse(event.data);
console.log('Artifact created:', data.artifact.filename);
});
eventSource.addEventListener('task.status', (event) => {
const data = JSON.parse(event.data);
if (data.status === 'completed') {
console.log('Task completed!');
eventSource.close();
// 4. Download artifact
window.location.href =
`http://localhost:8080/api/v1/artifacts/summary_report.md`;
}
});
See Also
