Create an AI agent

curl --request POST \
  --url https://app.hookie.ai/admin/api/projects/{project_id}/ai-agents \
  --header 'Content-Type: application/json' \
  --cookie hookie_session= \
  --data '
{
  "name": "<string>",
  "active": true,
  "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
  "system_prompt": "",
  "prompt": "<string>",
  "tools": [
    "<unknown>"
  ],
  "memory_dataset": "<string>",
  "max_tokens": 1024
}
'

const options = {
  method: 'POST',
  headers: {cookie: 'hookie_session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    active: true,
    model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
    system_prompt: '',
    prompt: '<string>',
    tools: ['<unknown>'],
    memory_dataset: '<string>',
    max_tokens: 1024
  })
};

fetch('https://app.hookie.ai/admin/api/projects/{project_id}/ai-agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.hookie.ai/admin/api/projects/{project_id}/ai-agents"

payload = {
    "name": "<string>",
    "active": True,
    "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "system_prompt": "",
    "prompt": "<string>",
    "tools": ["<unknown>"],
    "memory_dataset": "<string>",
    "max_tokens": 1024
}
headers = {
    "cookie": "hookie_session=",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "<string>",
  "ok": true,
  "ai_agent": {
    "id": "<string>",
    "name": "<string>",
    "active": 0,
    "model": "<string>",
    "system_prompt": "<string>",
    "tools": "<string>",
    "memory_dataset": "<string>",
    "max_tokens": 123,
    "created_at": "<string>",
    "updated_at": "<string>"
  }
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

POST

admin

api

projects

{project_id}

ai-agents

Create an AI agent

curl --request POST \
  --url https://app.hookie.ai/admin/api/projects/{project_id}/ai-agents \
  --header 'Content-Type: application/json' \
  --cookie hookie_session= \
  --data '
{
  "name": "<string>",
  "active": true,
  "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
  "system_prompt": "",
  "prompt": "<string>",
  "tools": [
    "<unknown>"
  ],
  "memory_dataset": "<string>",
  "max_tokens": 1024
}
'

const options = {
  method: 'POST',
  headers: {cookie: 'hookie_session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    active: true,
    model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
    system_prompt: '',
    prompt: '<string>',
    tools: ['<unknown>'],
    memory_dataset: '<string>',
    max_tokens: 1024
  })
};

fetch('https://app.hookie.ai/admin/api/projects/{project_id}/ai-agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.hookie.ai/admin/api/projects/{project_id}/ai-agents"

payload = {
    "name": "<string>",
    "active": True,
    "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    "system_prompt": "",
    "prompt": "<string>",
    "tools": ["<unknown>"],
    "memory_dataset": "<string>",
    "max_tokens": 1024
}
headers = {
    "cookie": "hookie_session=",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "<string>",
  "ok": true,
  "ai_agent": {
    "id": "<string>",
    "name": "<string>",
    "active": 0,
    "model": "<string>",
    "system_prompt": "<string>",
    "tools": "<string>",
    "memory_dataset": "<string>",
    "max_tokens": 123,
    "created_at": "<string>",
    "updated_at": "<string>"
  }
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

Authorizations

hookie_session

string

required

The console's sealed session cookie, set by WorkOS AuthKit. Mutating requests also require the X-Requested-With CSRF header.

Headers

Idempotency-Key

string

Makes a POST safe to retry for 24 hours: the same key, credential, path and body returns the stored response (Idempotent-Replayed: true) instead of running again. 422 if the key was used for a different request; 409 while the first is in flight.

Required string length: 1 - 255

Path Parameters

project_id

string

required

Body

application/json

name

string

required

Trimmed before validation.

Required string length: 1 - 120

active

boolean

default:true

Only the literal false deactivates. An inactive agent makes an agent_call workflow step fail.

model

enum<string>

default:@cf/meta/llama-3.3-70b-instruct-fp8-fast

A model from GET /admin/api/ai-models. Absent or empty means the default (@cf/meta/llama-3.3-70b-instruct-fp8-fast); anything off the list is refused with 400 … is not a supported model (#196, FLOW-16). It used to be replaced by the default without a word.

Available options:

@cf/meta/llama-3.3-70b-instruct-fp8-fast,

@cf/meta/llama-3.1-8b-instruct,

@cf/meta/llama-3.1-8b-instruct-fast,

@cf/meta/llama-3.2-3b-instruct,

@cf/meta/llama-4-scout-17b-16e-instruct,

@cf/mistralai/mistral-small-3.1-24b-instruct,

@cf/google/gemma-3-12b-it

system_prompt

string

default:""

prompt is accepted as an alias.

Maximum string length: 8000

prompt

string

Alias for system_prompt.

tools

any[]

Not supported: an agent makes one model call and cannot call tools. An empty list is accepted; a non-empty one is refused with 400 (#196). It used to be stored and ignored.

memory_dataset

string | null

When set, each output is written there as a record, and the agent's latest 5 outputs there (its own, this project's, oldest first, at most 2,000 characters) are sent with its next call (#196).

Pattern: ^[a-zA-Z][a-zA-Z0-9_]{0,62}$

max_tokens

integer

default:1024

Clamped to 1..1024; a non-integer becomes 1024.

Response

Created.

string

required

enum<boolean>

required

Available options:

true

ai_agent

object

The created ai agent, as GET by id returns it (#201).

Show child attributes

Get started

Concepts

CLI

Guides

API reference

Create an AI agent

Authorizations

Headers

Path Parameters

Body

Response