Documentation

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 dashboard under Settings → API Keys.

Authorization: Bearer ha_your_api_key_here
Key Features
  • Scoped to specific agents
  • Configurable expiration
  • Individual revocation
  • Usage audit log
Key Prefix

All keys start with ha_ for easy identification in logs and configurations.

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 the status of my account?", "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 is 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 Requests/min Requests/day
Starter6010,000
Pro300100,000
ScaleCustomUnlimited

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 — missing or invalid API key
Verify your API key
429
Rate limit exceeded — too many requests
Wait for the Retry-After header and try again
500
Server error
Retry with exponential backoff
503
Agent temporarily unavailable
Retry after a few seconds

Ready to integrate?

Deploy an agent and get your API endpoint in under 5 minutes.

Get Started

API FAQ

How do I authenticate with the HostAgentes agent API?

Every request requires a Bearer token in the Authorization header. Generate API keys in your agent dashboard under Settings → API Keys. Keys are scoped to specific agents, support configurable expiration and individual revocation, and every use is recorded in a usage audit log.

What is the base URL for the Paperclip agent API?

Each deployed agent gets its own endpoint at https://your-agent.hostagentes.com/api/v1. Send messages with POST /chat and stream responses with POST /chat/stream.

Does the HostAgentes API support streaming responses?

Yes. 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 is generated.

What are the API rate limits?

Starter: 60 requests/min and 10,000 requests/day. Pro: 300 requests/min and 100,000 requests/day. Scale: custom limits with unlimited daily requests. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

What does a 429 error code mean?

429 means you exceeded the rate limit — wait for the time given in the Retry-After header and try again. A 401 means your API key is missing or invalid; 500 and 503 are server-side and should be retried after a few seconds or with exponential backoff.