Sequence Agent

curl --request POST \
  --url https://app.octavehq.com/api/v2/agents/sequence/run \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "email": "john.doe@example.com",
  "firstName": "<string>",
  "lastName": "<string>",
  "jobTitle": "<string>",
  "companyDomain": "example.com",
  "companyName": "<string>",
  "linkedInProfile": "<string>",
  "crmContactId": "<string>",
  "crmLeadId": "<string>",
  "crmAccountId": "<string>",
  "lang": "<string>",
  "requestId": "<string>",
  "outputFormat": "text",
  "runtimeContext": {
    "all": ""
  },
  "runtimeInstructions": {
    "all": ""
  },
  "playbookSelectionContext": "<string>",
  "customContext": {},
  "agentOId": "agent_123",
  "experimentOId": "experiment_123",
  "includeFullAnnotation": true
}
'

{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "found": true,
  "message": "Additional information",
  "data": {
    "emails": [
      {
        "email": "<string>",
        "subject": "<string>",
        "coreValueProp": "",
        "sections": {
          "greeting": "",
          "opening": "",
          "body": "",
          "closing": "",
          "cta": "",
          "ps": "",
          "signature": ""
        }
      }
    ],
    "product": {
      "data": {
        "type": "PRODUCT",
        "internalName": "<string>",
        "summary": "<string>",
        "capabilities": [
          "Capability 1",
          "Capability 2"
        ],
        "differentiatedValue": [
          "Differentiated Value 1",
          "Differentiated Value 2"
        ],
        "statusQuo": [
          "Status Quo 1",
          "Status Quo 2"
        ],
        "challengesAddressed": [
          "Challenge 1",
          "Challenge 2"
        ],
        "customerBenefits": [
          "Benefit 1",
          "Benefit 2"
        ],
        "customFields": [
          {
            "title": "<string>",
            "value": [
              "<string>"
            ]
          }
        ]
      },
      "oId": "<string>",
      "name": "<string>",
      "internalName": "Product Internal Name",
      "description": "Product Description",
      "primaryUrl": "https://www.product.com",
      "qualifyingQuestions": [
        {
          "question": "<string>",
          "rationale": "<string>",
          "fitType": "GOOD",
          "weight": "MEDIUM",
          "archivedAt": "<string>"
        }
      ],
      "matchConfidence": "LOW",
      "matchAnalysis": "<string>"
    },
    "playbook": {
      "oId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "type": "LEGACY",
      "keyInsight": [
        "<string>"
      ],
      "matchConfidence": "LOW",
      "matchAnalysis": "<string>"
    },
    "persona": {
      "oId": "<string>",
      "name": "<string>",
      "internalName": "Sally the Sales Leader",
      "qualifyingQuestions": [
        {
          "question": "<string>",
          "rationale": "<string>",
          "fitType": "GOOD",
          "weight": "MEDIUM",
          "archivedAt": "<string>"
        }
      ],
      "matchConfidence": "LOW",
      "matchAnalysis": "<string>"
    },
    "outputType": "SCOPED_PLAYBOOK",
    "annotations": {
      "annotations": [
        {
          "type": "<string>",
          "title": "<string>",
          "meta": null,
          "description": "<string>",
          "url": "<string>"
        }
      ],
      "metadata": null
    }
  }
}

POST

api

agents

sequence

run

Sequence Agent

curl --request POST \
  --url https://app.octavehq.com/api/v2/agents/sequence/run \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "email": "john.doe@example.com",
  "firstName": "<string>",
  "lastName": "<string>",
  "jobTitle": "<string>",
  "companyDomain": "example.com",
  "companyName": "<string>",
  "linkedInProfile": "<string>",
  "crmContactId": "<string>",
  "crmLeadId": "<string>",
  "crmAccountId": "<string>",
  "lang": "<string>",
  "requestId": "<string>",
  "outputFormat": "text",
  "runtimeContext": {
    "all": ""
  },
  "runtimeInstructions": {
    "all": ""
  },
  "playbookSelectionContext": "<string>",
  "customContext": {},
  "agentOId": "agent_123",
  "experimentOId": "experiment_123",
  "includeFullAnnotation": true
}
'

{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "found": true,
  "message": "Additional information",
  "data": {
    "emails": [
      {
        "email": "<string>",
        "subject": "<string>",
        "coreValueProp": "",
        "sections": {
          "greeting": "",
          "opening": "",
          "body": "",
          "closing": "",
          "cta": "",
          "ps": "",
          "signature": ""
        }
      }
    ],
    "product": {
      "data": {
        "type": "PRODUCT",
        "internalName": "<string>",
        "summary": "<string>",
        "capabilities": [
          "Capability 1",
          "Capability 2"
        ],
        "differentiatedValue": [
          "Differentiated Value 1",
          "Differentiated Value 2"
        ],
        "statusQuo": [
          "Status Quo 1",
          "Status Quo 2"
        ],
        "challengesAddressed": [
          "Challenge 1",
          "Challenge 2"
        ],
        "customerBenefits": [
          "Benefit 1",
          "Benefit 2"
        ],
        "customFields": [
          {
            "title": "<string>",
            "value": [
              "<string>"
            ]
          }
        ]
      },
      "oId": "<string>",
      "name": "<string>",
      "internalName": "Product Internal Name",
      "description": "Product Description",
      "primaryUrl": "https://www.product.com",
      "qualifyingQuestions": [
        {
          "question": "<string>",
          "rationale": "<string>",
          "fitType": "GOOD",
          "weight": "MEDIUM",
          "archivedAt": "<string>"
        }
      ],
      "matchConfidence": "LOW",
      "matchAnalysis": "<string>"
    },
    "playbook": {
      "oId": "<string>",
      "name": "<string>",
      "description": "<string>",
      "type": "LEGACY",
      "keyInsight": [
        "<string>"
      ],
      "matchConfidence": "LOW",
      "matchAnalysis": "<string>"
    },
    "persona": {
      "oId": "<string>",
      "name": "<string>",
      "internalName": "Sally the Sales Leader",
      "qualifyingQuestions": [
        {
          "question": "<string>",
          "rationale": "<string>",
          "fitType": "GOOD",
          "weight": "MEDIUM",
          "archivedAt": "<string>"
        }
      ],
      "matchConfidence": "LOW",
      "matchAnalysis": "<string>"
    },
    "outputType": "SCOPED_PLAYBOOK",
    "annotations": {
      "annotations": [
        {
          "type": "<string>",
          "title": "<string>",
          "meta": null,
          "description": "<string>",
          "url": "<string>"
        }
      ],
      "metadata": null
    }
  }
}

Runtime Context & Instructions

The API uses runtimeContext and runtimeInstructions to pass dynamic per-contact data to your agent at execution time. These are not the same fields as the MCP tool schema (which uses allEmailsContext / allEmailsInstructions).

If you’re migrating from the MCP tool to the direct API, note the schema difference:

MCP Tool Field	API Field
`allEmailsContext`	`runtimeContext.all`
`allEmailsInstructions`	`runtimeInstructions.all`
`step1Context`	`runtimeContext.1`
`step1Instructions`	`runtimeInstructions.1`

How keys work

Both runtimeContext and runtimeInstructions accept an object where keys control which email steps receive the content:

Key	Scope
`"all"`	Applied to every email in the sequence
`"1"`	Applied to step 1 only
`"2"`	Applied to step 2 only
`"3"`	Applied to step 3 only
`"4"`	Applied to step 4 only

Step-specific values are merged with "all" — they don’t replace it. Use "all" when you have one block of context for the whole sequence (which is the most common case).

Context vs Instructions

runtimeContext — Factual information the agent should draw from: account research, LinkedIn data, recent activity, deal context. Think of this as “what the agent knows about this person.”
runtimeInstructions — Behavioral directives that steer how the agent writes: tone, length, what to emphasize, what to avoid. Think of this as “how the agent should write.”

Example: Event follow-up with rich context

{
  "agentOId": "ca_JxNickJCXUdxFQe2CFKCF",
  "outputFormat": "text",
  "firstName": "Sarah",
  "lastName": "Jackson",
  "companyName": "NICE Ltd",
  "companyDomain": "nice.com",
  "jobTitle": "Strategic Alliance Director",
  "email": "sarah.jackson@nice.com",
  "linkedInProfile": "https://www.linkedin.com/in/sarah-jackson-nice",
  "runtimeContext": {
    "all": "ACCOUNT RESEARCH:\nNICE Ltd expanded their AI partner program from 25 to 200 partners in 18 months. Sarah led the AWS SCA partnership and drove the partner enablement strategy.\n\nEVENT ATTENDANCE:\nAttended Partner Signal Live on 2025-03-15. Participated in the 'Scaling Partner-Led Growth' breakout session.\n\nLINKEDIN CONTEXT:\n12 years in strategic alliances. Previously at Genesys building channel programs. Posts frequently about partner ecosystem strategy."
  },
  "runtimeInstructions": {
    "all": "Keep emails under 150 words. Reference specific details from the event and her LinkedIn background. Use a peer-to-peer tone — she's a senior alliances leader, not a prospect to be pitched.",
    "1": "Lead with a specific detail from the event breakout session she attended. Do not use a generic 'thanks for attending' opener."
  }
}

Example: Simple context (all steps)

If you only need one block of context for the whole sequence, use the "all" key:

{
  "agentOId": "YOUR_AGENT_OID",
  "firstName": "Alex",
  "lastName": "Chen",
  "companyName": "Datadog",
  "jobTitle": "VP Engineering",
  "email": "alex.chen@datadoghq.com",
  "outputFormat": "text",
  "runtimeContext": {
    "all": "Datadog recently announced a new AI observability product. Alex's team is responsible for the core monitoring platform and has been hiring for ML engineers."
  }
}

Authorizations

api_key

string

header

required

Body

application/json

Generate emails input

string | null

Email of the person to generate emails for

Example:

"john.doe@example.com"

firstName

string | null

First name of the person to generate emails for

lastName

string | null

jobTitle

string | null

Job title of the person to generate emails for

companyDomain

string | null

Company domain of the person to generate emails for

Example:

"example.com"

companyName

string | null

Company name of the person to generate emails for

linkedInProfile

string | null

LinkedIn profile of the person to generate emails for

crmContactId

string | null

crmLeadId

string | null

crmAccountId

string | null

lang

string | null

Language of the person to generate emails for

requestId

string | null

outputFormat

enum<string> | null

default:text

Output format of the emails to generate

Available options:

text,

html,

markdown

runtimeContext

object

Runtime context of the person to generate emails for

Show child attributes

runtimeInstructions

object

Runtime instructions of the person to generate emails for

Show child attributes

playbookSelectionContext

string | null

Playbook selection context of the person to generate emails for

customContext

object

Show child attributes

agentOId

string

AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.

Example:

"agent_123"

experimentOId

string

ExperimentOId is required when running an experiment

Example:

"experiment_123"

includeFullAnnotation

boolean

If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size.

Response

Generate emails successful

_metadata

object

required

Show child attributes

found

boolean

required

Whether the operation was successful

Example:

true

message

string | null

Message

Example:

"Additional information"

data

object

Show child attributes

Content Agent Prospector Agent

Agents

Async

Workspace

API Key

Persona

Playbook

Use Case

Reference

Product

Segment

Competitor

Proof Point

Alternative

Buying Trigger

Brand Voice

Workflow

Analytics

Resource

Sequence Agent

Runtime Context & Instructions

How keys work

Context vs Instructions

Example: Event follow-up with rich context

Example: Simple context (all steps)

Authorizations

Body

Response

Agents

Async

Workspace

API Key

Persona

Playbook

Use Case

Reference

Product

Segment

Competitor

Proof Point

Alternative

Buying Trigger

Brand Voice

Workflow

Analytics

Resource

Documentation Index

​Runtime Context & Instructions

​How keys work

​Context vs Instructions

​Example: Event follow-up with rich context

​Example: Simple context (all steps)

Authorizations

Body

Response

Runtime Context & Instructions

How keys work

Context vs Instructions

Example: Event follow-up with rich context

Example: Simple context (all steps)