> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.flockx.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.flockx.io/_mcp/server.

# Create

POST https://api.flockx.io/api/v1/agents
Content-Type: application/json

Create a new agent.

Reference: https://docs.flockx.io/api-reference/agents/create-agent

## Authentication

- `Authorization` header (required) — Either 'Bearer \<token>' or 'Token \<token>'

## Request

### Body (application/json)

This endpoint expects an AgentCreate.

- `name` (string, optional, default: Personal AI Agent) — The name of an AI Agent
- `personal` (boolean, optional, nullable, default: false) — Is the agent a personal agent or a public agent. If personal is true the agent will not be listed on marketplaces, if it false then it will be.
- `personality` (string, optional, default: ) — Describe how your AI acts and behaves. This is used to generate the base prompt of your AI. The base prompt is what gives personality to how your AI responds and interacts with users.
- `image_url` (AgentCreateImageUrl, optional, default: https://res.cloudinary.com/fetch-ai/image/upload/v1739813981/flockx-webapp/default_graphics/default_avatar_rbmfo3.jpg) — Image of the AI, this is the image that appears as the profile picture of the AI. If this AI is connected to a Community then this image will be the Community's profile picture too.
- `custom_welcome_message` (string, optional, default: ) — A custom first message that this agent will send
- `website` (AgentCreateWebsite, optional, default: ) — The primary website the AI should use to seed and maintain its knowledge base.
- `category` (enum, optional, nullable) — The category of the agent
  - Allowed values: `business_owner`, `co_founder`, `marketing`, `sales`, `operations`, `research`, `freelancer`, `influencers`, `gig_economy`, `companies`, `brands`, `community_leader`, `developer`, `education`, `personal`, `asi`, `solo_preneur`, `content_creator`, `consultant`, `tech_startup`, `agent_creator`
- `agent_capabilities` (string, optional, nullable) — Text describing the capabilities of the agent
- `interest_tags` (list of string, optional, nullable) — Interest tags for agent discovery (max 10)
- `agent_handle` (string, optional, nullable) — Agentverse handle for the agent (e.g. 'my-agent-handle' for @my-agent-handle.av)
- `point_of_interest_id` (string, optional, nullable) — The id of a Point of Interest representing the agent's location. Resolve or create one via POST /v2/points_of_interest, then pass its id here. Takes precedence over the deprecated place_id.
- `meta_data` (map from string to any, optional)
- `character` (string, optional, default: , deprecated) — Describe how your AI looks (e.g. surfing seal).
- `place_id` (string, optional, nullable, deprecated) — DEPRECATED: Use point_of_interest_id instead. A Google Place ID representing the agent's location.

## Response

### 200

Successful Response

- `id` (string, required)
- `name` (string, required)
- `description` (string, required)
- `organization` (OrganizationSummarySchema, required, nullable) — Schema for the Organization
- `images` (AgentImages, required)
- `features` (AgentFeatures, required)
- `personality` (string, optional, default: )
- `personal` (boolean, optional, nullable, default: false) — Is the agent a personal agent or a public agent. If personal is true the agent will not be listed on marketplaces, if it false then it will be.
- `knowledge_graph` (KnowledgeGraphSummarySchema, optional, nullable) — Knowledge graph for the agent
- `website` (AgentSchemaWebsite, optional, default: )
- `agent_capabilities` (string, optional, nullable)
- `logic_model_temperature` (double, optional, default: 0.1) — Temperature for the logic model
- `agent_address` (string, optional, nullable)
- `agent_handle` (string, optional, nullable) — Agentverse handle for the agent (e.g. 'my-agent-handle' for @my-agent-handle.av)
- `voice_id` (string, optional, default: jqcCZkN6Knx8BJ5TBdYR) — ElevenLabs voice ID used for TTS playback of this agent's responses.
- `point_of_interest` (PointOfInterestSchema, optional, nullable) — Location information for the agent.
- `category` (enum, optional, nullable)
  - Allowed values: `business_owner`, `co_founder`, `marketing`, `sales`, `operations`, `research`, `freelancer`, `influencers`, `gig_economy`, `companies`, `brands`, `community_leader`, `developer`, `education`, `personal`, `asi`, `solo_preneur`, `content_creator`, `consultant`, `tech_startup`, `agent_creator`
- `interest_tags` (list of string, optional)
- `meta_data` (map from string to any, optional)

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### AgentCreateImageUrl

Image of the AI, this is the image that appears as the profile picture of the AI. If this AI is connected to a Community then this image will be the Community's profile picture too.

- string
- string

### AgentCreateWebsite

The primary website the AI should use to seed and maintain its knowledge base.

- string
- string

### OrganizationSummarySchema

Schema for the Organization

- `id` (string, required)
- `name` (string, required)
- `owner` (UserSummarySchema, optional, nullable) — Summary of the organization owner's details
- `application` (enum, optional, nullable) — Application this organization belongs to (e.g. asi_one, fetch_business). Clients use this to scope viewer-facing behavior, such as pairing an agent participant onto its owner's card only when the agent's organization matches the viewer's active application.
  - Allowed values: `flockx`, `asi_one`, `fetch_business`, `artprize`, `health`, `agentverse`
- `is_personal` (boolean, optional, default: false) — True only for the per-user Personal organization. The source of truth for which organization is the user's Personal context; clients use it to gate team-context behavior instead of the name='Personal' convention.

### AgentImages

- `image_url` (AgentImagesImageUrl, optional, default: https://res.cloudinary.com/fetch-ai/image/upload/v1739813981/flockx-webapp/default_graphics/default_avatar_rbmfo3.jpg)
- `banner_url` (AgentImagesBannerUrl, optional, default: https://res.cloudinary.com/fetch-ai/image/upload/v1739710237/flockx-webapp/default_graphics/Hero_ahp7qp.jpg)

### AgentFeatures

- `discover_activity` (boolean, required)
- `location_learning` (boolean, required)
- `enable_proactive_message` (boolean, required)
- `general_web_search` (boolean, required)
- `general_agent_search` (boolean, required)
- `planner_mode` (boolean, required)
- `enable_media_capability` (boolean, required)
- `telegram` (boolean, required)
- `discord` (boolean, required)
- `calendar_enabled` (boolean, required)
- `whatsapp` (boolean, required)
- `sms` (boolean, required)
- `asi` (boolean, required)
- `agentverse` (boolean, required)
- `widget_enabled` (boolean, required)

### KnowledgeGraphSummarySchema

- `id` (string, required)
- `name` (string, required)

### AgentSchemaWebsite

- string
- string

### PointOfInterestSchema

Schema for creating and updating Points of Interest in the system.

- `name` (string, required)
- `display_name` (string, required)
- `provider_type` (string, required)
- `street` (string, required)
- `city` (string, required)
- `state` (string, required)
- `postal_code` (string, required)
- `country` (string, required)
- `timezone` (string, required, nullable) — IANA timezone derived from the POI coordinates, when resolvable.
- `id` (string, optional)
- `description` (string, optional, default: )
- `external_id` (string, optional, nullable)
- `location` (GeoPoint, optional, nullable) — Geographical location as a GeoJSON Point
- `url` (string, optional, default: )
- `image_url` (string, optional, default: )
- `metadata` (map from string to any, optional)

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `input` (any, optional)
- `ctx` (ValidationErrorCtx, optional)

### UserSummarySchema

Summary schema for User with display name and image URL. Uses base class pattern - no custom from_django needed since: - display_name has default="" to handle empty values - image_url has default matching User.DEFAULT_IMAGE_URL - Both fields are simple attributes on the User model

- `display_name` (string, optional, default: )
- `image_url` (string, optional, default: https://res.cloudinary.com/fetch-ai/image/upload/v1724200421/Default_Avatar_uk7jyj.svg)

### AgentImagesImageUrl

- string
- string

### AgentImagesBannerUrl

- string
- string

### GeoPoint

- `type` (string, optional, default: Point)
- `coordinates` (list of double, optional, nullable, default: [0,0])

### ValidationErrorLocItems

- string
- integer

### ValidationErrorCtx

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "id": "string",
  "name": "string",
  "description": "string",
  "organization": {
    "id": "string",
    "name": "string",
    "owner": {
      "display_name": "",
      "image_url": "https://res.cloudinary.com/fetch-ai/image/upload/v1724200421/Default_Avatar_uk7jyj.svg"
    },
    "application": "flockx",
    "is_personal": false
  },
  "images": {
    "image_url": "string",
    "banner_url": "string"
  },
  "features": {
    "discover_activity": true,
    "location_learning": true,
    "enable_proactive_message": true,
    "general_web_search": true,
    "general_agent_search": true,
    "planner_mode": true,
    "enable_media_capability": true,
    "telegram": true,
    "discord": true,
    "calendar_enabled": true,
    "whatsapp": true,
    "sms": true,
    "asi": true,
    "agentverse": true,
    "widget_enabled": true
  },
  "personality": "",
  "personal": true,
  "knowledge_graph": {
    "id": "string",
    "name": "string"
  },
  "website": "string",
  "agent_capabilities": "string",
  "logic_model_temperature": 0.1,
  "agent_address": "string",
  "agent_handle": "string",
  "voice_id": "jqcCZkN6Knx8BJ5TBdYR",
  "point_of_interest": {
    "name": "string",
    "display_name": "string",
    "provider_type": "string",
    "street": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string",
    "timezone": "string",
    "id": "string",
    "description": "",
    "external_id": "string",
    "location": {
      "type": "Point",
      "coordinates": [
        1.1
      ]
    },
    "url": "",
    "image_url": "",
    "metadata": {}
  },
  "category": "business_owner",
  "interest_tags": [
    "string"
  ],
  "meta_data": {}
}
```

**SDK Code**

```python
import requests

url = "https://api.flockx.io/api/v1/agents"

payload = {}
headers = {
    "Authorization": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.flockx.io/api/v1/agents';
const options = {
  method: 'POST',
  headers: {Authorization: '<apiKey>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.flockx.io/api/v1/agents"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.flockx.io/api/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.flockx.io/api/v1/agents")
  .header("Authorization", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.flockx.io/api/v1/agents', [
  'body' => '{}',
  'headers' => [
    'Authorization' => '<apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.flockx.io/api/v1/agents");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.flockx.io/api/v1/agents")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```