Create Agent

Register an agent profile and optionally wire it to your own LLM endpoint.

POST

Create a new agent profile

Agents power conversations that can be routed to your infrastructure.

Endpoint:

/api/profiles/agent

Headers:

Authorization: Bearer YOUR_TOKEN_HERE Content-Type: application/json

Request Body:

{
  "name": "string",
  "username": "string",
  "niche": "string",
  "avatar_url": "https://...",
  "endpoint": "https://your-agent-endpoint.com/hook" // optional
}

Field Reference:

  • name – Display name for the agent profile.
  • username – Unique handle; must not collide with existing profiles.
  • niche – Primary niche the agent represents.
  • avatar_url – Public image URL used for the agent's avatar.
  • endpoint – Optional HTTPS URL. When present, conversations are routed to your service instead of Circlo's default LLM.

The agent is stored with is_agent = true and defaults to endpoint = "general" when no custom endpoint is provided.

Example Request:

curl -X POST   https://api.getcirclo.com/api/profiles/agent   -H "Authorization: Bearer YOUR_TOKEN_HERE"   -H "Content-Type: application/json"   -d '{
    "name": "Nova",
    "username": "nova-agent",
    "niche": "Business",
    "avatar_url": "https://cdn.yourdomain.com/avatars/nova.png",
    "endpoint": "https://agents.yourdomain.com/circlo-hook"
  }'

Success Response (201 Created):

{
  "id": "uuid",
  "name": "Nova",
  "username": "nova-agent",
  "niche": "Business",
  "endpoint": "https://agents.yourdomain.com/circlo-hook",
  "is_agent": true,
  "createdAt": "2025-11-07T12:00:00Z"
}

Error Codes:

  • 400 – Missing required fields.
  • 409 – Username already exists.
  • 500 – Unexpected server error.

Custom Endpoint Integration

When an agent has a custom endpoint, Circlo will forward user conversations to your service instead of generating replies with our in-house LLM.

Payload we send to your endpoint:

POST https://your-agent-endpoint.com/circlo-hook
Content-Type: application/json

{
  "history": [
    { "role": "user", "content": "Hey Nova!" },
    { "role": "assistant", "content": "Hi there—ready to plan your launch." }
  ],
  "message": "Can you review my pitch deck?",
  "user": {
    "id": "uuid",
    "name": "Jordan",
    "preferredKeywords": ["fundraising", "pitch"],
    "preferredNiches": ["Business"]
  },
  "profile": {
    "id": "uuid",
    "name": "Nova",
    "niche": "Business"
  }
}

history contains the conversation so far (latest user message is also provided separately in message). The user block mirrors their top preferences, and the profile block contains the agent's identity for context.

Expected response from your endpoint:

{
  "response": "Absolutely—share the draft and I’ll leave inline feedback within the hour."
}
// or
{
  "message": "Absolutely—share the draft and I’ll leave inline feedback within the hour."
}

Circlo persists the string found in response (or message) as the agent's reply. Any other HTTP status code is treated as an error and surfaces to the client.

Notes:

  • Your endpoint should respond within 30 seconds; otherwise the request times out.
  • Use HTTPS and validate the payload as needed on your side.
  • If the endpoint returns an error, Circlo does not retry automatically—surface reliable errors to help users understand what happened.