Docs
API Reference
Everything you need to integrate with your Paperclip agent's API endpoint.
Base URL
https://your-agent.hostagentes.com/api/v1
Authentication
All requests require a Bearer token in the Authorization header. Generate API keys in your agent's dashboard under Settings → API Keys.
Authorization: Bearer ha_your_api_key_here
Key Features
- Scoped to specific agents
- Configurable expiration
- Individual revocation
- Usage audit logging
Key Prefix
All keys start with ha_ for easy identification in logs and configs.
Send a Message
POST /chat
Request Body
{
"message": "string (required)",
"context": {
"user_id": "string (optional)",
"session_id": "string (optional)"
},
"tools": ["string (optional)"],
"temperature": 0.7,
"max_tokens": 1000
}
Response
{
"response": "string",
"tool_calls": [
{
"tool": "string",
"input": {},
"output": {}
}
],
"metadata": {
"model": "string",
"tokens_used": 0,
"latency_ms": 0
}
}
Example
curl -X POST https://your-agent.hostagentes.com/api/v1/chat \
-H "Authorization: Bearer ha_your_key" \
-H "Content-Type: application/json" \
-d '{
"message": "What is my account status?",
"context": { "user_id": "usr_123" }
}'
Streaming
POST /chat/stream
Returns Server-Sent Events (SSE) for real-time partial responses. Each event contains a chunk of the agent's response as it's generated.
event: token
data: {"content": "Your"}
event: token
data: {"content": " account"}
event: token
data: {"content": " is active."}
event: done
data: {"tokens_used": 45, "latency_ms": 820}
Rate Limits
| Plan | Req/min | Req/day |
|---|---|---|
| Starter | 60 | 10,000 |
| Pro | 300 | 100,000 |
| Scale | Custom | Unlimited |
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Error Codes
200 Success
Read the response body
400 Bad request — invalid JSON or missing fields
Check your request format
401 Unauthorized — invalid or missing API key
Verify your API key
429 Rate limited — too many requests
Wait for Retry-After header, then retry
500 Server error
Retry with exponential backoff
503 Agent temporarily unavailable
Retry after a few seconds