Skip to main content
POST
/
api
/
v2
/
agents
/
create
Create Agent
curl --request POST \
  --url https://app.octavehq.com/api/v2/agents/create \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "name": "Cold Outbound Sequence",
  "description": "A cold outbound email sequence agent",
  "productOId": "<string>",
  "serviceOId": "<string>",
  "playbookOId": "<string>",
  "personaOIds": [
    "<string>"
  ],
  "useCaseOIds": [
    "<string>"
  ],
  "segmentOIds": [
    "<string>"
  ],
  "competitorOIds": [
    "<string>"
  ],
  "referenceOIds": [
    "<string>"
  ],
  "proofPointOIds": [
    "<string>"
  ],
  "enableBrandVoice": true,
  "enableWebSearch": true,
  "webSearchInstructions": "<string>",
  "enableCrmActivity": true,
  "crmActivityInstructions": "<string>",
  "enableHighEffortMode": true,
  "sequenceSettings": {
    "numEmails": 123,
    "sequenceTypeCustomInstructions": "<string>",
    "sequenceCustomInstructions": "<string>",
    "writingStyleOId": "<string>",
    "generateUniqueSubjectLines": true,
    "applyCtaToAllEmails": true,
    "applySubjectToAllEmails": true
  },
  "stepPatches": {},
  "instructions": "<string>",
  "examples": [
    "<string>"
  ],
  "jsonSchemaInstructions": "<string>",
  "data": {}
}
'
{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "data": {
    "oId": "<string>",
    "name": "<string>",
    "description": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "costToRun": 123,
    "data": "<unknown>",
    "warnings": [
      "<string>"
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.octavehq.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

api_key
string
header
required

Body

application/json

Agent creation input

name
string
required

The name of the agent

Minimum string length: 1
Example:

"Cold Outbound Sequence"

description
string
required

The description of the agent

Minimum string length: 1
Example:

"A cold outbound email sequence agent"

type
enum<string>
required

The type of agent to create

Available options:
PROSPECTOR,
CONTENT,
EMAIL,
ENRICH_PERSON,
ENRICH_COMPANY,
QUALIFY_PERSON,
QUALIFY_COMPANY,
CALL_PREP,
CONTEXT
model
enum<string>

The model to use for the agent

Available options:
NOTE,
PULSE,
ECHO,
HARMONY,
CHORUS,
SYMPHONY
productOId
string

The OId of the product/offering to associate with the agent

serviceOId
string

Alias for productOId — use either field, not both. Maps to the same internal product/offering.

playbookOId
string

The OId of the playbook to associate with the agent

personaOIds
string[]

The OIds of the personas to associate with the agent

useCaseOIds
string[]

The OIds of the use cases to associate with the agent

segmentOIds
string[]

The OIds of the segments to associate with the agent

competitorOIds
string[]

The OIds of the competitors to associate with the agent

referenceOIds
string[]

The OIds of the reference customers to associate with the agent

proofPointOIds
string[]

The OIds of the proof points to associate with the agent

enableBrandVoice
boolean

Whether to enable brand voice for the agent

Whether to enable web search. Only enable when explicitly requested

webSearchInstructions
string

Custom instructions for the web search tool

enableCrmActivity
boolean

Whether to enable CRM activity for the agent

crmActivityInstructions
string

Custom instructions for the CRM activity tool

enableHighEffortMode
boolean

Whether to enable high-effort mode for the agent

sequenceSettings
object

EMAIL agents only: sequence-level settings (type, numEmails, tone, reading level, instructions, writingStyleOId, etc.)

stepPatches
object

EMAIL agents only: map of 1-based step index to partial email builder config (methodology, focus, length, cta, subject, trainingExamples: paste or updatePaste — no raw smart-example oIds), same numbering as sequence run runtimeContext keys. Deep-merged into writingStyle.emails[i]. trainingExamples.targetTrainingIndex is 1-based (default 1).

callPrepMethodology
enum<string>

Call prep methodology (CALL_PREP agents only). Controls discovery questions and call script framing.

Available options:
BANT,
SPIN,
CHAMP,
MEDDIC,
SANDLER,
CHALLENGER,
AIDA,
NEAT,
SPICED,
WHY_CHANGE
instructions
string

Instructions for content generation (CONTENT agents only)

examples
string[]

Example outputs for content generation (CONTENT agents only)

outputFormat
enum<string>

The output format for content generation (CONTENT agents only)

Available options:
JSON,
TEXT,
HTML,
MARKDOWN
jsonSchemaInstructions
string

JSON schema instructions for content generation (CONTENT agents only, used with JSON output format)

data
object

Full agent configuration data passthrough. When provided, this will be merged with the simplified fields above, with simplified fields taking precedence.

Response

Agent created successfully

_metadata
object
required
data
object
required