SDKS
REST API
Use the API directly with cURL, Postman, or any HTTP client. All examples below use cURL for clarity.
Authentication
Auth header
curl https://api.yourautomation.ai/v1/agents \
-H "Authorization: Bearer ya_live_sk_your_key_here" \
-H "Content-Type: application/json"
Create an Agent
POST /v1/agents
curl -X POST https://api.yourautomation.ai/v1/agents \
-H "Authorization: Bearer ya_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Support Agent",
"model": "claude-sonnet-4-20250514",
"systemPrompt": "You are a helpful customer support agent...",
"parameters": {
"temperature": 0.3,
"maxTokens": 1024
}
}'
List Agents
GET /v1/agents
curl https://api.yourautomation.ai/v1/agents?limit=20 \
-H "Authorization: Bearer ya_live_sk_..."
Retrieve an Agent
GET /v1/agents/:id
curl https://api.yourautomation.ai/v1/agents/agt_abc123 \
-H "Authorization: Bearer ya_live_sk_..."
Update an Agent
PATCH /v1/agents/:id
curl -X PATCH https://api.yourautomation.ai/v1/agents/agt_abc123 \
-H "Authorization: Bearer ya_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"systemPrompt": "Updated instructions...",
"parameters": { "temperature": 0.5 }
}'
Delete an Agent
DELETE /v1/agents/:id
curl -X DELETE https://api.yourautomation.ai/v1/agents/agt_abc123 \
-H "Authorization: Bearer ya_live_sk_..."
Execute an Agent
POST /v1/agents/:id/execute
curl -X POST https://api.yourautomation.ai/v1/agents/agt_abc123/execute \
-H "Authorization: Bearer ya_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"input": "What is the status of order #12345?",
"conversationId": "conv_optional_id"
}'
Streaming Execution
POST with stream=true
curl -X POST https://api.yourautomation.ai/v1/agents/agt_abc123/execute \
-H "Authorization: Bearer ya_live_sk_..." \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"input": "Explain your return policy",
"stream": true
}'
# Response (Server-Sent Events):
# data: {"type":"text_delta","text":"Our"}
# data: {"type":"text_delta","text":" return"}
# data: {"type":"text_delta","text":" policy"}
# ...
# data: {"type":"done","usage":{"totalTokens":231}}
Note
Use -N with cURL to disable output buffering for streaming: curl -N -X POST ...
Multi-Turn Conversation
Multi-turn
# Turn 1
curl -X POST https://api.yourautomation.ai/v1/agents/agt_abc123/execute \
-H "Authorization: Bearer ya_live_sk_..." \
-H "Content-Type: application/json" \
-d '{"input": "I need to return a product"}'
# Response includes "conversationId": "conv_xyz789"
# Turn 2 (continue conversation)
curl -X POST https://api.yourautomation.ai/v1/agents/agt_abc123/execute \
-H "Authorization: Bearer ya_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"input": "It is order #12345, the blue widget",
"conversationId": "conv_xyz789"
}'
Create a Webhook
POST /v1/webhooks
curl -X POST https://api.yourautomation.ai/v1/webhooks \
-H "Authorization: Bearer ya_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/webhooks/ya-events",
"events": ["execution.completed", "execution.failed"],
"agentId": "agt_abc123"
}'
Create an API Key
POST /v1/keys
curl -X POST https://api.yourautomation.ai/v1/keys \
-H "Authorization: Bearer ya_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"name": "CI/CD Key",
"environment": "test",
"scopes": ["agents:read", "agents:execute"]
}'
Error Responses
Error example
# 401 Unauthorized
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The provided API key is not valid",
"requestId": "req_abc123"
}
}
# 429 Rate Limited
# Headers include: Retry-After: 5
{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Retry after 5 seconds.",
"requestId": "req_def456"
}
}