API Reference

Complete API reference for Strands Agents endpoints.

Base URL

https://api.universalapi.co

Authentication

Include credentials in every request:

Headers (Recommended):

X-Uni-UserId: your-user-id
X-Uni-SecretUniversalKey: your-secret-key

Query Parameters:

?userId=your-user-id&secretUniversalKey=your-secret-key

Agent Management

Create Agent

Create a new Strands Agent.

http

POST /agent/create

Request Body:

Field	Type	Required	Description
`agentName`	string	Yes	Unique name for the agent
`description`	string	Yes	Description of what the agent does
`sourceCode`	string	Yes	Python code with `create_agent()` function
`visibility`	string	No	`private` (default) or `public`
`runtime`	string	No	`python3.12` (default)
`memoryMb`	number	No	Memory allocation (default: 1024)
`timeoutSec`	number	No	Timeout in seconds (default: 300)

Example:

bash

curl -X POST "https://api.universalapi.co/agent/create" \
  -H "Content-Type: application/json" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY" \
  -d '{
    "agentName": "my-assistant",
    "description": "A helpful AI assistant",
    "sourceCode": "from strands import Agent\nfrom strands.models import BedrockModel\n\ndef create_agent():\n    model = BedrockModel(model_id=\"us.anthropic.claude-3-7-sonnet-20250219-v1:0\")\n    agent = Agent(model=model)\n    return agent, []"
  }'

Response:

json

{
  "success": true,
  "data": {
    "agentId": "5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d",
    "agentName": "my-assistant",
    "description": "A helpful AI assistant",
    "status": "active",
    "visibility": "private",
    "runtime": "python3.12",
    "memoryMb": 1024,
    "timeoutSec": 300,
    "endpointUrl": "https://api.universalapi.co/agent/5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d/chat",
    "createdAt": 1768666121176,
    "updatedAt": 1768666121176
  }
}

List Agents

List all agents owned by the authenticated user.

http

GET /agent/list

Query Parameters:

Parameter	Type	Description
`visibility`	string	Filter by `public`, `private`, or `all`
`status`	string	Filter by `active`, `deleted`

Example:

bash

curl "https://api.universalapi.co/agent/list" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY"

Response:

json

{
  "success": true,
  "data": {
    "agents": [
      {
        "agentId": "5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d",
        "agentName": "my-assistant",
        "description": "A helpful AI assistant",
        "status": "active",
        "visibility": "private",
        "runtime": "python3.12",
        "memoryMb": 1024,
        "timeoutSec": 300,
        "invocationsPerMonth": 42,
        "endpointUrl": "https://api.universalapi.co/agent/5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d/chat",
        "createdAt": 1768666121176,
        "updatedAt": 1768666121176
      }
    ]
  }
}

Get Agent

Get details of a specific agent.

http

GET /agent/{agentId}

Example:

bash

curl "https://api.universalapi.co/agent/5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY"

Response:

json

{
  "success": true,
  "data": {
    "agentId": "5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d",
    "agentName": "my-assistant",
    "description": "A helpful AI assistant",
    "sourceCode": "from strands import Agent...",
    "status": "active",
    "visibility": "private",
    "runtime": "python3.12",
    "memoryMb": 1024,
    "timeoutSec": 300,
    "invocationsPerMonth": 42,
    "endpointUrl": "https://api.universalapi.co/agent/5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d/chat",
    "createdAt": 1768666121176,
    "updatedAt": 1768666121176
  }
}

Update Agent

Update an existing agent.

http

PUT /agent/update
POST /agent/update

Request Body:

Field	Type	Required	Description
`agentId`	string	Yes	ID of the agent to update
`agentName`	string	No	New name
`description`	string	No	New description
`sourceCode`	string	No	New source code
`visibility`	string	No	`private` or `public`
`status`	string	No	`active` or `deleted`

Example:

bash

curl -X PUT "https://api.universalapi.co/agent/update" \
  -H "Content-Type: application/json" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY" \
  -d '{
    "agentId": "5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d",
    "description": "An updated description"
  }'

Delete Agent

Delete an agent (soft delete - sets status to deleted).

http

DELETE /agent/delete
POST /agent/delete

Request Body:

json

{
  "agentId": "5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d"
}

Chat Endpoints

Chat with Agent (Streaming) ⭐

Chat with an agent using real-time streaming responses.

http

POST /agent/{agentId}/chat

Request Body:

Field	Type	Required	Description
`prompt`	string	Yes	The user's message
`conversationId`	string	No	UUID to continue existing conversation

Example:

bash

curl -N "https://stream.api.universalapi.co/agent/5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d/chat" \
  -H "Content-Type: application/json" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY" \
  -d '{"prompt": "Hello! What is 2+2?"}'

Response (Streaming):

Content-Type: text/plain; charset=utf-8
X-Conversation-Id: 625c2112-9eac-4630-bbbc-785a845a182d

__META__{"conversationId": "625c2112-9eac-4630-bbbc-785a845a182d"}__
Hello! The answer to 2+2 is 4.

Response Markers:

Marker	Description
`__META__{json}__`	Metadata (conversationId)
`__TOOL__{name}__`	Tool execution indicator
`__ERROR__{json}__`	Error information

Timeout: 15 minutes (900 seconds)

Chat with Agent (GET - Browser Testing) 🌐

Chat with an agent via GET request for easy browser testing.

http

GET /agent/{agentId}/chat?prompt={message}&sessionId={optional-session-id}

Query Parameters:

Parameter	Required	Description
`prompt`	Yes	The user's message (URL encoded)
`sessionId`	No	UUID to continue existing conversation
`conversationId`	No	Alias for sessionId

Example (Browser URL):

https://stream.api.universalapi.co/agent/5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d/chat?prompt=Hello!%20What%20is%202%2B2?

Example (curl):

bash

curl -N "https://stream.api.universalapi.co/agent/5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d/chat?prompt=Hello" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY"

Browser Extension

Use a browser extension like "ModHeader" to add the X-Uni-UserId and X-Uni-SecretUniversalKey headers for testing directly in your browser.

Timeout: 15 minutes (900 seconds)

Chat with Agent (Buffered)

Chat with an agent using a buffered (complete) response.

http

POST /agent/{agentId}/chat

Request Body:

Field	Type	Required	Description
`prompt`	string	Yes	The user's message
`conversationId`	string	No	UUID to continue existing conversation

Example:

bash

curl -X POST "https://api.universalapi.co/agent/5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d/chat" \
  -H "Content-Type: application/json" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY" \
  -d '{"prompt": "Hello! What is 2+2?"}'

Timeout: 5 minutes (300 seconds)

Conversation Endpoints

List Conversations

List all conversations for an agent.

http

GET /agent/{agentId}/conversations

Example:

bash

curl "https://api.universalapi.co/agent/5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d/conversations" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY"

Response:

json

{
  "conversations": [
    {
      "conversationId": "625c2112-9eac-4630-bbbc-785a845a182d",
      "agentId": "5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d",
      "title": "Hello! What is 2+2?",
      "messageCount": 4,
      "createdAt": 1768666200000,
      "updatedAt": 1768666300000
    }
  ]
}

Get Conversation

Get the full message history of a conversation.

http

GET /agent/{agentId}/conversation/{conversationId}

Example:

bash

curl "https://api.universalapi.co/agent/5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d/conversation/625c2112-9eac-4630-bbbc-785a845a182d" \
  -H "X-Uni-UserId: $USER_ID" \
  -H "X-Uni-SecretUniversalKey: $SECRET_KEY"

Response:

json

{
  "conversation": {
    "conversationId": "625c2112-9eac-4630-bbbc-785a845a182d",
    "agentId": "5a8f5c4f-a3ca-44cc-8fe7-afec7a75653d",
    "userId": "d468e4e8-50f1-705c-eab0-4b513b8b5900",
    "messages": [
      {
        "role": "user",
        "content": "Hello! What is 2+2?",
        "timestamp": 1768666200000
      },
      {
        "role": "assistant",
        "content": "Hello! The answer to 2+2 is 4.",
        "timestamp": 1768666201000
      }
    ],
    "createdAt": 1768666200000,
    "updatedAt": 1768666201000
  }
}

Error Responses

All errors follow this format:

json

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Error Codes

Code	Status	Description
`AUTHENTICATION_REQUIRED`	401	Missing or invalid credentials
`AGENT_NOT_FOUND`	404	Agent doesn't exist
`AGENT_DELETED`	410	Agent was deleted
`ACCESS_DENIED`	403	No permission to access agent
`INVALID_PARAMETERS`	400	Bad request body
`AWS_CREDENTIALS_REQUIRED`	400	No AWS Bedrock credentials configured
`AGENT_EXECUTION_FAILED`	500	Runtime error in agent code
`CONVERSATION_NOT_FOUND`	404	Conversation doesn't exist

Rate Limits

User Type	Limit
Authenticated	60 requests/minute
Anonymous	Not supported

Source Code Requirements

The sourceCode field must contain Python code that defines a create_agent() function:

python

def create_agent():
    """
    Create and return a Strands Agent.
    
    Returns:
        tuple: (agent, mcp_clients)
            - agent: The Strands Agent instance
            - mcp_clients: List of MCP client connections (can be empty)
    """
    from strands import Agent
    from strands.models import BedrockModel
    
    model = BedrockModel(
        model_id="us.anthropic.claude-3-7-sonnet-20250219-v1:0",
        region_name="us-east-1"
    )
    agent = Agent(model=model)
    
    return agent, []

Allowed Imports

For security, only these modules can be imported:

strands, strands.Agent, strands.tool
strands.models, strands.models.BedrockModel
strands_tools
json, datetime, time, uuid, typing, dataclasses
collections, itertools, functools, re, math, random
base64, hashlib, urllib.parse
boto3, botocore

Restricted Operations

The following are not allowed in agent code:

File system access (open, os.remove, etc.)
Shell execution (os.system, subprocess, etc.)
Network access outside of allowed tools
eval, exec, compile

Endpoint Summary

Endpoint	Method	Description
`/agent/create`	POST	Create a new agent
`/agent/list`	GET	List your agents
`/agent/{agentId}`	GET	Get agent details
`/agent/update`	PUT/POST	Update an agent
`/agent/delete`	DELETE/POST	Delete an agent
`/agent/{agentId}/chat`	POST	Chat (buffered) — `api.universalapi.co`
`/agent/{agentId}/chat`	POST	Chat (streaming) ⭐ — `stream.api.universalapi.co`
`/agent/{agentId}/chat`	GET	Chat (browser testing) 🌐 — `stream.api.universalapi.co`
`/agent/{agentId}/conversations`	GET	List conversations
`/agent/{agentId}/conversation/{id}`	GET	Get conversation

API Reference ​

Base URL ​

Authentication ​

Agent Management ​

Create Agent ​

List Agents ​

Get Agent ​

Update Agent ​

Delete Agent ​

Chat Endpoints ​

Chat with Agent (Streaming) ⭐ ​

Chat with Agent (GET - Browser Testing) 🌐 ​

Chat with Agent (Buffered) ​

Conversation Endpoints ​

List Conversations ​

Get Conversation ​

Error Responses ​

Error Codes ​

Rate Limits ​

Source Code Requirements ​

Allowed Imports ​

Restricted Operations ​

Endpoint Summary ​

API Reference

Base URL

Authentication

Agent Management

Create Agent

List Agents

Get Agent

Update Agent

Delete Agent

Chat Endpoints

Chat with Agent (Streaming) ⭐

Chat with Agent (GET - Browser Testing) 🌐

Chat with Agent (Buffered)

Conversation Endpoints

List Conversations

Get Conversation

Error Responses

Error Codes

Rate Limits

Source Code Requirements

Allowed Imports

Restricted Operations

Endpoint Summary