Paperclip API Gateway: Everything You Need to Know

Every Paperclip agent deployed on HostAgentes gets a unique API endpoint. This is your API gateway — the bridge between your applications and your agent. Here’s how it works.

Your Agent’s API Endpoint

When you deploy an agent, you get a dedicated URL:

https://your-agent.hostagentes.com/api/v1/chat

This endpoint accepts POST requests with a JSON body and returns your agent’s response. It’s a standard REST API — use it from any language, framework, or tool that can make HTTP requests.

Authentication

Every request requires authentication via an API key:

curl -X POST https://your-agent.hostagentes.com/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, what can you help me with?"
  }'

API keys are generated in your dashboard. You can create multiple keys for different applications and revoke them individually.

Key Security

• Keys are prefixed with ha_ for easy identification
• Keys can be scoped to specific agents (not account-wide)
• Keys can be set to expire after a configurable period
• All key usage is logged for audit purposes

Request Format

Basic Chat

{
  "message": "What's the status of order #12345?"
}

With Context

{
  "message": "What's the status of my recent order?",
  "context": {
    "user_id": "usr_abc123",
    "session_id": "ses_xyz789"
  }
}

With Tool Override

{
  "message": "Search our docs for refund policy",
  "tools": ["web_search", "document_lookup"]
}

Response Format

{
  "response": "Your order #12345 is currently being processed and expected to ship within 2 business days.",
  "tool_calls": [
    {
      "tool": "order_lookup",
      "input": {"order_id": "12345"},
      "output": {"status": "processing", "eta": "2 business days"}
    }
  ],
  "metadata": {
    "model": "gpt-4",
    "tokens_used": 142,
    "latency_ms": 1230
  }
}

Rate Limiting

API endpoints have built-in rate limiting to protect your agent and control costs:

Plan	Requests/min	Requests/day
Starter	60	10,000
Pro	300	100,000
Scale	Custom	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1714022400

When you exceed the limit, the API returns a 429 Too Many Requests status with a Retry-After header.

Streaming Responses

For long-running agent responses, use the streaming endpoint:

POST https://your-agent.hostagentes.com/api/v1/chat/stream

Responses are sent as Server-Sent Events (SSE), allowing your application to display partial responses as they’re generated.

Error Handling

Status	Meaning	Action
200	Success	Read response
400	Bad request	Check request format
401	Unauthorized	Check API key
429	Rate limited	Wait and retry
500	Server error	Retry with backoff
503	Agent unavailable	Retry after a few seconds

Integration Examples

JavaScript/Node.js

const response = await fetch('https://your-agent.hostagentes.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ha_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ message: 'Hello!' })
});
const data = await response.json();

Python

import requests

response = requests.post(
    'https://your-agent.hostagentes.com/api/v1/chat',
    headers={
        'Authorization': 'Bearer ha_your_api_key',
        'Content-Type': 'application/json'
    },
    json={'message': 'Hello!'}
)
data = response.json()

Getting Started

Deploy an agent and get your API endpoint in under 5 minutes. Start with the free Pro trial.

Start building →