Getting started

Armada API reference

Workspace-scoped REST for people, companies, sequences, conversations, runs, content, and webhooks. Generated from the live OpenAPI spec — every route below matches production.

Authentication

Send your workspace API key on every request. Mint a key in Settings → Developers (any plan with API access, including Free).

Authorization: Bearer arm_…

Base URL

All paths below are relative to the product app host. Paths include the /api/v1 prefix.

https://app.goarmada.co/api/v1

Scopes

Mint keys with the scopes you need. Each endpoint lists its tag-level scope below.

lists:read
lists:write
find:run
data:read
data:run
sequence:read
sequence:write
campaigns:read
campaigns:write
campaigns:enroll
message:read
message:write
inbox:read
inbox:write
content:read
content:write
accounts:read
accounts:write
agent:run
inventory:read
inventory:write
webhooks:manage
billing:read
billing:write

Idempotency

Mutating POST, PUT, PATCH, and DELETE accept an optional Idempotency-Key header (1–256 chars). Successful responses are cached 24h per key; replays return the same body with idempotency-replayed: true.

Errors

Every error returns a stable JSON envelope. x-request-id is echoed on all responses.

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key",
    "request_id": "req_…"
  }
}

Rate limits

Bucket	Per key	Per workspace
Light reads / list writes	120/min	600/min
Heavy (data:run, enroll, message write, content write, agent:run)	30/min	120/min

429 responses include Retry-After and error.code = rate_limited.

Getting started

Create an account, open Settings → Developers, mint a workspace key, and call /api/v1. Usage bills the same as the product UI — no separate API approval step.

Models

Schemas

Shared object types referenced across endpoints. Field tables below match the OpenAPI components section.

AccountConnectRequest

Properties

object

FieldTypeDescription

channelrequired
email | linkedin | twitter
provider
string
e.g. google, microsoft, x (channel-dependent)

CompanyEnrichRequest

Properties

object

FieldTypeDescription

domain
string
Company domain (optional when path id is set)
provider
string
auto | platform slug | byok:slug

CompanySearchRequest

Search and upsert companies. Pass structured filters and/or a free-text query. provider defaults to auto (Armada waterfall). Always pass limit (omitted defaults to 25, max 100). Optional list_id writes matching companies as Audiences rows. For more than about 25 results, start a Find run instead of this sync search.

Properties

object

FieldTypeDescription

query
string
Natural-language company search (Exa-primary when auto)
industries
string[]
Firmographic industries / verticals
locations
string[]
Company or market locations
hq_locations
string[]
HQ locations (when distinct from market)
employee_ranges
string[]
Headcount bands, e.g. "51-200", "201-500"
funding_stages
string[]
lookalike_domains
string[]
Seed domains for lookalike company search
limit
integer
provider
string
auto | platform slug | byok:slug
list_id
string · uuid
Existing company list. Matching results are written as Audiences rows (spreadsheet cells), not only graph membership.

CreateInventoryOrderRequest

Properties

object

FieldTypeDescription

kindrequired
linkedin | email
quantityrequired
integer
term
monthly | quarterly | yearly
region
string
account_type
string
branding
string
agreements_acceptedrequired
boolean
agreement_ids
string[]
agreement_versions
string[]

CreateSequenceRequest

Properties

object

FieldTypeDescription

namerequired
string
channels
email | linkedin | twitter | phone[]
graph_snapshot
object
steps
object[]
edges
object[]

CreateWebhookRequest

Properties

object

FieldTypeDescription

urlrequired
string · uri
events
string[]
Event names to subscribe to (defaults to the live webhook enum)
description
string

Error

Properties

object

FieldTypeDescription

errorrequired
object
- coderequired
  string
- messagerequired
  string
- request_idrequired
  string
- details
  unknown

FindEmailRequest

Properties

object

FieldTypeDescription

person_id
string · uuid
linkedin_url
string
full_name
string
first_name
string
last_name
string
company_domain
string
provider
string
auto | platform slug | byok:slug

FindPhoneRequest

Properties

object

FieldTypeDescription

person_id
string · uuid
linkedin_url
string
email
string · email
provider
string
auto | platform slug | byok:slug

Me

Properties

object

FieldTypeDescription

workspace_idrequired
string · uuid
organization_idrequired
string · uuid
keyrequired
object
- idrequired
  string · uuid
- namerequired
  string
- scopesrequired
  string[]
entitlementsrequired
object
- api_accessrequired
  boolean
- csv_export
  boolean
- plan_id
  string | null
- credits_balance
  number

PersonEnrichRequest

Properties

object

FieldTypeDescription

linkedin_url
string
full_name
string
company_domain
string
provider
string
auto | platform slug | byok:slug

PersonSearchRequest

Search and upsert people. Prefer structured filters (titles, sizes, locations) for agent discovery; query is optional NL. Always pass limit (omitted defaults to 25, max 100). Optional list_id writes matching people as Audiences rows. For more than about 25 results, start a Find run instead of this sync search.

Properties

object

FieldTypeDescription

query
string
Natural-language people search
titles
string[]
seniorities
string[]
locations
string[]
Person locations
company_domains
string[]
company_sizes
string[]
Company headcount bands, e.g. "51-200", "201-500"
industries
string[]
funding_stages
string[]
lookalike_domains
string[]
People at companies similar to these domains
lookalike_linkedin_urls
string[]
Seed LinkedIn profile URLs for similar-people search
limit
integer
provider
string
auto | platform slug | byok:slug
list_id
string · uuid
Existing people list. Matching results are written as Audiences rows (spreadsheet cells), not only graph membership.

ProviderMode

auto | platform slug | byok:slug

Properties

string

UpdateSequenceRequest

Properties

object

FieldTypeDescription

graph_snapshot
object
steps
object[]
edges
object[]

Me

Key identity, entitlements, credits, and on-demand status.

Scopes: Any valid key

GET/api/v1/me

Key identity, scopes, entitlements, credits

Responses

200OKMe
Response body
Meobject
FieldTypeDescription
- workspace_idrequired
  string · uuid
- organization_idrequired
  string · uuid
- keyrequired
  object
  idrequired
  string · uuid
  namerequired
  string
  scopesrequired
  string[]
- entitlementsrequired
  object
  api_accessrequired
  boolean
  csv_export
  boolean
  plan_id
  string | null
  credits_balance
  number
401Missing or invalid API keyError
Response body
Errorobject
FieldTypeDescription
- errorrequired
  object
  coderequired
  string
  messagerequired
  string
  request_idrequired
  string
  details
  unknown

Capabilities

Machine-readable Capability Registry (stable IDs for REST/MCP/skills).

Scopes: Any valid key

GET/api/v1/capabilities

List public capabilities

Parameters

domainstring
query

Responses

200OK

Graph

Companies, people, emails, phones, signals — provider: auto | slug | byok:slug.

Scopes: data:run

POST/api/v1/companies/{id}/enrich

Enrich company (capability data.company.enrich)

Parameters

idstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

CompanyEnrichRequestobject

FieldTypeDescription

domain
string
Company domain (optional when path id is set)
provider
string
auto | platform slug | byok:slug

Responses

200OK

POST/api/v1/companies/search

Search companies (capability data.company.search)

Parameters

Idempotency-Keystring
header

Request body

application/json

CompanySearchRequestobject

Capability data.company.search. Pass limit. Optional list_id writes Audiences rows. For more than ~25 results, start a Find run.

FieldTypeDescription

query
string
Natural-language company search (Exa-primary when auto)
industries
string[]
Firmographic industries / verticals
locations
string[]
Company or market locations
hq_locations
string[]
HQ locations (when distinct from market)
employee_ranges
string[]
Headcount bands, e.g. "51-200", "201-500"
funding_stages
string[]
lookalike_domains
string[]
Seed domains for lookalike company search
limit
integer
provider
string
auto | platform slug | byok:slug
list_id
string · uuid
Existing company list. Matching results are written as Audiences rows (spreadsheet cells), not only graph membership.

Example

{
  "industries": ["Software"],
  "employee_ranges": ["51-200"],
  "locations": ["United States"],
  "limit": 25,
  "provider": "auto"
}

Responses

200OK

POST/api/v1/emails/find

Find email (capability data.email.find)

Parameters

Idempotency-Keystring
header

Request body

application/json

FindEmailRequestobject

FieldTypeDescription

person_id
string · uuid
linkedin_url
string
full_name
string
first_name
string
last_name
string
company_domain
string
provider
string
auto | platform slug | byok:slug

Example

{
  "full_name": "Alex Rivera",
  "company_domain": "acme.co",
  "provider": "auto"
}

Responses

200OK

POST/api/v1/emails/verify

Verify email (capability data.email.verify)

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

emailrequired
string · email

Responses

200OK

POST/api/v1/people/{id}/enrich

Enrich person (capability data.person.enrich)

Parameters

idstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

PersonEnrichRequestobject

FieldTypeDescription

linkedin_url
string
full_name
string
company_domain
string
provider
string
auto | platform slug | byok:slug

Responses

200OK

POST/api/v1/people/search

Search people (capability data.person.search)

Parameters

Idempotency-Keystring
header

Request body

application/json

PersonSearchRequestobject

Preferred agent discovery path (capability data.person.search). Pass limit. Optional list_id writes Audiences rows. For more than ~25 results, start a Find run.

FieldTypeDescription

query
string
Natural-language people search
titles
string[]
seniorities
string[]
locations
string[]
Person locations
company_domains
string[]
company_sizes
string[]
Company headcount bands, e.g. "51-200", "201-500"
industries
string[]
funding_stages
string[]
lookalike_domains
string[]
People at companies similar to these domains
lookalike_linkedin_urls
string[]
Seed LinkedIn profile URLs for similar-people search
limit
integer
provider
string
auto | platform slug | byok:slug
list_id
string · uuid
Existing people list. Matching results are written as Audiences rows (spreadsheet cells), not only graph membership.

Example

{
  "titles": ["VP Sales"],
  "company_sizes": ["51-200", "201-500"],
  "locations": ["United States"],
  "limit": 25,
  "provider": "auto"
}

Responses

200OK

POST/api/v1/phones/find

Find phone (capability data.phone.find)

Parameters

Idempotency-Keystring
header

Request body

application/json

FindPhoneRequestobject

FieldTypeDescription

person_id
string · uuid
linkedin_url
string
email
string · email
provider
string
auto | platform slug | byok:slug

Example

{
  "person_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "provider": "auto"
}

Responses

200OK

POST/api/v1/signal-monitors

Request signal monitor (returns pending_approval until fully implemented)

Parameters

Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

query
string
signal_type
string
provider
string
auto | platform slug | byok:slug

Responses

201Queued for approval

POST/api/v1/signals/search

Search signals (capability signals.search)

Parameters

Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

query
string
Natural-language or keyword signal query
limit
integer
provider
string
auto | platform slug | byok:slug

Responses

200OK

Sequences

Create sequences and enroll by person_ids.

Scopes: sequence:read · sequence:write · campaigns:enroll

GET/api/v1/sequences

List sequences (campaigns with graphs)

Responses

200OK

POST/api/v1/sequences

Create sequence (capability sequence.create)

Parameters

Idempotency-Keystring
header

Request body · required

application/json

CreateSequenceRequestobject

FieldTypeDescription

namerequired
string
channels
email | linkedin | twitter | phone[]
graph_snapshot
object
steps
object[]
edges
object[]

Example

{
  "name": "Outbound — VP Sales",
  "channels": ["email", "linkedin"]
}

Responses

201Created

GET/api/v1/sequences/{id}

Get sequence

Parameters

idstring · uuid
path · required

Responses

200OK

PATCH/api/v1/sequences/{id}

Update sequence graph (capability sequence.update)

Parameters

idstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

UpdateSequenceRequestobject

FieldTypeDescription

graph_snapshot
object
steps
object[]
edges
object[]

Responses

200OK

POST/api/v1/sequences/{id}/enrollments

Enroll people (capability sequence.enroll) — prefer person_ids

Parameters

idstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

Prefer person_ids. list_row_ids is optional for list-build UIs.

FieldTypeDescription

person_ids
string · uuid[]
list_row_ids
string · uuid[]
Optional legacy projection ids
list_id
string · uuid

Example

{
  "person_ids": [
    "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
  ]
}

Responses

201Created

Conversations

Unified multi-channel threads and replies.

Scopes: message:read · message:write

GET/api/v1/conversations

List conversations (capability conversation.list)

Parameters

limitinteger
query
unread_onlyboolean
query
statusopen | archived | snoozed
query
qstring
query
channelemail | linkedin | twitter | sms | phone
query
campaign_idstring · uuid
query

Responses

200OK

GET/api/v1/conversations/{id}

Get conversation + messages

Parameters

idstring · uuid
path · required

Responses

200OK

PATCH/api/v1/conversations/{id}

Archive, snooze, or reopen (capability conversation.patch)

Parameters

idstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

status
open | archived | snoozed
snoozed_until
string · date-time | null

Responses

200OK

POST/api/v1/conversations/{id}/drafts

Queue HITL inbox reply (capability message.draft)

Parameters

idstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

bodyrequired
string
subject
string

Responses

202Pending approval

POST/api/v1/conversations/{id}/messages

Reply (capability message.reply)

Parameters

idstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

bodyrequired
string
subject
string
require_approval
boolean

Example

{
  "body": "Thanks for the reply — happy to share a 15-min overview next week."
}

Responses

202Accepted

Runs & approvals

Skill runs, approvals, and skill catalog.

Scopes: agent:run

GET/api/v1/approvals

List approvals

Parameters

statusstring
query

Responses

200OK

POST/api/v1/approvals

Create approval

Request body

application/json

object

Responses

201Created

POST/api/v1/approvals/{id}/decide

Decide approval (capability approval.decide)

Parameters

idstring · uuid
path · required

Request body

application/json

object

FieldTypeDescription

decisionrequired
approve | deny

Example

{
  "decision": "approve"
}

Responses

200OK

POST/api/v1/runs

Start skill run (capability run.start)

Parameters

Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

skillrequired
string
e.g. outbound, outbound/targeting, content, signals
goal
string
inputs
object
require_approval
boolean

Example

{
  "skill": "outbound",
  "goal": "Find and enroll VP Sales at Series B SaaS",
  "inputs": {}
}

Responses

201Created

GET/api/v1/runs/{id}

Get run

Parameters

idstring · uuid
path · required

Responses

200OK

POST/api/v1/runs/{id}/cancel

Cancel run

Parameters

idstring · uuid
path · required

Request body

application/json

object

Responses

200OK

GET/api/v1/runs/{id}/events

Run event stream

Parameters

idstring · uuid
path · required

Responses

200OK

GET/api/v1/skills

List skill → capability map

Responses

200OK

Agents

List, publish, pause, and run catalog + canvas agents.

Scopes: agent:run

GET/api/v1/agents

List catalog + canvas agents (capability agent.list)

Responses

200Agents plus node_types for publish_agent steps
401Missing or invalid API keyError
Response body
Errorobject
FieldTypeDescription
- errorrequired
  object
  coderequired
  string
  messagerequired
  string
  request_idrequired
  string
  details
  unknown

POST/api/v1/agents

Create or update a canvas agent (capability agent.publish)

Parameters

Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

id
string
from_catalog_id
string
namerequired
string
summary
string
trigger
manual | inbound | watchlist | form | meeting_booked | schedule | webhook | crm_event
cron
string
Five-field cron when trigger=schedule
timezone
string
IANA tz for schedule (default America/New_York)
crm_event
contact_created | list_membership | closed_won
campaign_id
string
steps
object[]
publish
boolean
Default true — turns the agent on

Responses

200id, status, canvas_href; webhook agents may return trigger_url + trigger_secret once
400Validation (unknown step, invalid cron, missing sequence, …)

GET/api/v1/agents/{id}

Get one agent (capability agent.get)

Parameters

idstring
path · required

Responses

200Graph with webhook secrets stripped
404Unknown agent

PATCH/api/v1/agents/{id}

Set agent status (capability agent.set_status)

Parameters

idstring
path · required
Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

statusrequired
on | off | retired
off pauses triggers; does not cancel an in-flight run

Responses

200id, status, canvas_href
404Unknown agent

POST/api/v1/agents/{id}/runs

Start an agent run (capability agent.run)

Parameters

idstring
path · required
Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

dry_run
boolean
Skip enroll/HTTP/CRM/alerts
trigger_payload
object
JSON object merged into step variables (max ~32KB)

Responses

202run_id, status, dry_run, step_count, canvas_href
409Agent is retired
503AGENT_RUNS_ENABLED=0

POST/api/v1/agents/{id}/trigger

HMAC trigger for a published canvas agent

Requires `agent:run`. When the agent has a webhook secret, send `X-Armada-Signature: sha256=<hex>` (HMAC-SHA256 of the raw body) or `t=<unix>,v1=<hex>` (HMAC of `{t}.{body}`, ±5 min). Public HMAC-only URL is `POST /api/hooks/agents/{workspaceId}/{agentId}`. Prefer `POST /agents/{id}/runs` to start without HMAC.

Parameters

idstring
path · required
Idempotency-Keystring
header

Request body

application/json

object

Responses

202run_id, status, step_count
401Invalid X-Armada-Signature when the agent has a secret

Billing

Credits, on-demand limits, and Stripe checkout links.

Scopes: billing:read · billing:write

GET/api/v1/billing

Credits + on-demand status

Responses

200OK

POST/api/v1/billing/checkout-link

Stripe checkout / portal URL

Request body

application/json

object

intent: activate_plan | enable_on_demand | upgrade | change_plan | portal

FieldTypeDescription

intentrequired
string

Example

{
  "intent": "activate_plan"
}

Responses

200OK

PATCH/api/v1/billing/on-demand

Update on-demand limit

Request body

application/json

object

FieldTypeDescription

enabledrequired
boolean
limit_centsrequired
integer

Example

{
  "enabled": true,
  "limit_cents": 40000
}

Responses

200OK

Lists

Named collections (views) over Person/Company + spreadsheet projection.

Scopes: lists:read · lists:write

GET/api/v1/lists

List workspace lists (views over Person/Company)

Responses

200OK

POST/api/v1/lists

Create list (capability list.create)

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

namerequired
string
entity
people | companies
description
string

Responses

201Created

GET/api/v1/lists/{listId}

List detail

Parameters

listIdstring · uuid
path · required

Responses

200OK

GET/api/v1/lists/{listId}/export

CSV export

Parameters

listIdstring · uuid
path · required

Responses

200text/csv

POST/api/v1/lists/{listId}/members

Add members and write Audiences spreadsheet rows

Parameters

listIdstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

person_ids
string · uuid[]
company_ids
string · uuid[]

Example

{
  "person_ids": [
    "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
  ]
}

Responses

201Created

GET/api/v1/lists/{listId}/rows

Page spreadsheet projection rows (list-build)

Parameters

listIdstring · uuid
path · required

Responses

200OK

POST/api/v1/lists/{listId}/rows

Append rows and write Audiences cells

Parameters

listIdstring · uuid
path · required
Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

rowsrequired
object[]

Example

{
  "rows": [
    {
      "data": {
        "email": "alex@acme.co",
        "first_name": "Alex",
        "company_name": "Acme"
      }
    }
  ]
}

Responses

201Created

Find (list-build)

Heavy list-build Find jobs — prefer /people/search for agents.

Scopes: find:run · lists:read

POST/api/v1/find-runs

Create list + start Find (list-build)

Parameters

Idempotency-Keystring
header

Request body

application/json

object

List-build helper — prefer searchPeople for agent discovery.

FieldTypeDescription

playbook_idrequired
string
list_namerequired
string
slotsrequired
object
- industryrequired
  string

Example

{
  "playbook_id": "recent-funding",
  "list_name": "Funded SaaS — March",
  "slots": {
    "industry": "B2B SaaS"
  }
}

Responses

202Accepted

GET/api/v1/find-runs/{runId}

Find run status

Parameters

runIdstring · uuid
path · required

Responses

200OK

POST/api/v1/lists/{listId}/enrich

Enqueue enrich jobs for list rows

Parameters

listIdstring · uuid
path · required

Request body

application/json

object

List-build enrich — prefer find_email / enrich_person for agents.

FieldTypeDescription

fieldsrequired
string[]
limitrequired
integer
skip_filledrequired
boolean

Example

{
  "fields": ["email", "owner"],
  "limit": 200,
  "skip_filled": true
}

Responses

202Accepted

POST/api/v1/lists/{listId}/find-runs

Start list-build Find on existing list

Parameters

listIdstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

List-build job (prefer /people/search for agents). Exactly one of plan, playbook_id, or playbook_ids.

FieldTypeDescription

playbook_idrequired
string
slotsrequired
object
- titlerequired
  string
- hqLocationsrequired
  string[]

Example

{
  "playbook_id": "hiring-vp-sales",
  "slots": {
    "title": "VP Sales",
    "hqLocations": ["United States"]
  }
}

Responses

202Accepted

Campaigns

Launch, pause, and sequence graphs for outbound campaigns.

Scopes: campaigns:read · campaigns:write

GET/api/v1/campaigns

List campaigns

Responses

200OK

POST/api/v1/campaigns

Create draft campaign

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

namerequired
string
channels
email | linkedin | twitter | phone[]

Example

{
  "name": "Outbound — VP Sales",
  "channels": ["email", "linkedin"]
}

Responses

201Created

GET/api/v1/campaigns/{campaignId}

Campaign summary

Parameters

campaignIdstring · uuid
path · required

Responses

200OK

PATCH/api/v1/campaigns/{campaignId}

Patch campaign metadata

Parameters

campaignIdstring · uuid
path · required

Request body

application/json

object

FieldTypeDescription

name
string
account_scope
all | selected
account_ids
string · uuid[]

Example

{
  "name": "Outbound — VP Sales (v2)",
  "account_scope": "selected",
  "account_ids": ["11111111-1111-1111-1111-111111111111"]
}

Responses

200OK

POST/api/v1/campaigns/{campaignId}/launch

Launch campaign (capability campaign.launch)

Parameters

campaignIdstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

Empty body is valid. Send Idempotency-Key on mutating calls.

object

Example

{}

Responses

200OK

POST/api/v1/campaigns/{campaignId}/pause

Pause campaign (capability campaign.pause)

Parameters

campaignIdstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

Example

{}

Responses

200OK

GET/api/v1/campaigns/{campaignId}/sequence

Get campaign sequence graph

Parameters

campaignIdstring · uuid
path · required

Responses

200OK

PUT/api/v1/campaigns/{campaignId}/sequence

Set campaign sequence graph

Parameters

campaignIdstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

Provide dsl, graph, or typed *_graph. dsl is compiled server-side.

FieldTypeDescription

typerequired
string
dslrequired
object
- stepsrequired
  object[]

Example

{
  "type": "multi",
  "dsl": {
    "steps": [
      { "kind": "email", "subject": "Quick question", "body": "Hi {{first_name}}…" },
      { "kind": "delay", "days": 3 },
      { "kind": "linkedin_connect", "note": "Saw your post on {{company_name}}…" }
    ]
  }
}

Responses

200OK

POST/api/v1/outbound/copy/generate

Generate outbound copy for list rows (capability outbound.copy.generate)

Generates icebreaker / opener / PS for up to 50 list rows. Batches over 20 rows enqueue asynchronously (status processing) onto agent:runs. HITL queues items on Home; autonomous writes list cells immediately.

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

list_idrequired
string · uuid
list_row_ids
string · uuid[]
fieldsrequired
icebreaker | opener | ps[]
campaign_id
string · uuid
require_approval
boolean

Responses

201Batch created (ready / completed / processing)
402Insufficient credits
403Outbound copy agent off

Enrollments

Pause, resume, or cancel enrollments (prefer person_ids on create).

Scopes: campaigns:enroll · campaigns:read

GET/api/v1/campaigns/{campaignId}/enrollments

List campaign enrollments

Parameters

campaignIdstring · uuid
path · required

Responses

200OK

POST/api/v1/campaigns/{campaignId}/enrollments

Enroll (prefer person_ids; list_row_ids optional)

Parameters

campaignIdstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

Prefer person_ids; list_row_ids optional.

FieldTypeDescription

person_ids
string · uuid[]
list_row_ids
string · uuid[]
Optional legacy projection ids
list_id
string · uuid

Example

{
  "person_ids": [
    "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
  ]
}

Responses

201Created

GET/api/v1/enrollments/{enrollmentId}

Enrollment status

Parameters

enrollmentIdstring · uuid
path · required

Responses

200OK

POST/api/v1/enrollments/{enrollmentId}/cancel

Cancel enrollment (capability enrollment.cancel)

Parameters

enrollmentIdstring · uuid
path · required

Request body

application/json

object

Example

{}

Responses

200OK

POST/api/v1/enrollments/{enrollmentId}/pause

Pause enrollment

Parameters

enrollmentIdstring · uuid
path · required

Request body

application/json

object

Example

{}

Responses

200OK

POST/api/v1/enrollments/{enrollmentId}/resume

Resume enrollment

Parameters

enrollmentIdstring · uuid
path · required

Request body

application/json

object

Example

{}

Responses

200OK

POST/api/v1/sequences/{id}/enrollments

Enroll people (capability sequence.enroll) — prefer person_ids

Parameters

idstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

Prefer person_ids. list_row_ids is optional for list-build UIs.

FieldTypeDescription

person_ids
string · uuid[]
list_row_ids
string · uuid[]
Optional legacy projection ids
list_id
string · uuid

Example

{
  "person_ids": [
    "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
  ]
}

Responses

201Created

Content

Draft, schedule, and publish LinkedIn/X posts.

Scopes: content:read · content:write

POST/api/v1/content/drafts

Create draft (capability content.draft)

Parameters

Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

account_idrequired
string · uuid
channelrequired
linkedin | twitter
bodyrequired
string
campaign_id
string · uuid

Example

{
  "account_id": "44444444-4444-4444-4444-444444444444",
  "channel": "linkedin",
  "body": "Three things we learned shipping outbound at scale…"
}

Responses

201Created

POST/api/v1/content/generate

Constrained generate (hooks + draft + variants)

Request body

application/json

object

Responses

200OK

GET/api/v1/content/ideas

List content ideas

Responses

200OK

POST/api/v1/content/ideas

Generate content ideas

Request body

application/json

object

Responses

201Created

POST/api/v1/content/ideas/{ideaId}/feedback

Feedback on a content idea

Parameters

ideaIdstring · uuid
path · required

Request body

application/json

object

Responses

200OK

GET/api/v1/content/memories

List content memories

Responses

200OK

POST/api/v1/content/memories

Create content memory

Request body

application/json

object

Responses

201Created

GET/api/v1/content/posts

List content posts

Responses

200OK

POST/api/v1/content/posts

Schedule a post (legacy shape)

Parameters

Idempotency-Keystring
header

Request body

application/json

object

Alias of scheduleContent — same body.

FieldTypeDescription

account_idrequired
string · uuid
channelrequired
linkedin | twitter
bodyrequired
string
scheduled_atrequired
string · date-time
campaign_id
string · uuid | null

Example

{
  "account_id": "44444444-4444-4444-4444-444444444444",
  "channel": "linkedin",
  "body": "Three things we learned shipping outbound at scale…",
  "scheduled_at": "2026-08-27T14:00:00-07:00"
}

Responses

201Created

GET/api/v1/content/posts/{postId}

Get content post

Parameters

postIdstring · uuid
path · required

Responses

200OK

POST/api/v1/content/posts/{postId}/cancel

Cancel scheduled post

Parameters

postIdstring · uuid
path · required

Request body

application/json

object

Example

{}

Responses

200OK

POST/api/v1/content/posts/{postId}/publish

Publish existing post by id (capability content.publish)

Parameters

postIdstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

Responses

202Accepted

POST/api/v1/content/posts/{postId}/schedule

Schedule existing draft/post by id

Parameters

postIdstring · uuid
path · required
Idempotency-Keystring
header

Request body

application/json

object

Schedules an existing draft — does not create a new post.

FieldTypeDescription

scheduled_atrequired
string · date-time

Example

{
  "scheduled_at": "2026-08-27T14:00:00-07:00"
}

Responses

200OK

POST/api/v1/content/schedule

Schedule post (capability content.schedule)

Parameters

Idempotency-Keystring
header

Request body

application/json

object

Preferred schedule path (capability content.schedule).

FieldTypeDescription

account_idrequired
string · uuid
channelrequired
linkedin | twitter
bodyrequired
string
scheduled_atrequired
string · date-time
campaign_id
string · uuid | null
thread_segments
string[]
media_urls
string · uri[]

Example

{
  "account_id": "44444444-4444-4444-4444-444444444444",
  "channel": "linkedin",
  "body": "Three things we learned shipping outbound at scale…",
  "scheduled_at": "2026-08-27T14:00:00-07:00"
}

Responses

201Created

DELETE/api/v1/content/watch

Delete content watch target

Responses

200OK

GET/api/v1/content/watch

List content watch targets

Responses

200OK

POST/api/v1/content/watch

Upsert content watch target

Request body

application/json

object

Responses

201Created

POST/api/v1/content/watch/ingest

Enqueue live watch ingest

Request body

application/json

object

Responses

200OK

Identities

Connected senders (no secrets).

Scopes: accounts:read · accounts:write

GET/api/v1/identities

List identities (capability identity.list)

Responses

200OK

POST/api/v1/identities/connect

Start identity connect

Parameters

Idempotency-Keystring
header

Request body · required

application/json

AccountConnectRequestobject

FieldTypeDescription

channelrequired
email | linkedin | twitter
provider
string
e.g. google, microsoft, x (channel-dependent)

Example

{
  "channel": "email",
  "provider": "google"
}

Responses

201Created

Accounts

Connect email, LinkedIn, and X via Armada-branded browser hop.

Scopes: accounts:read · accounts:write

GET/api/v1/accounts

List channel seats (no credentials)

Responses

200OK

POST/api/v1/accounts/connect

Start account connect (browser URL)

Parameters

Idempotency-Keystring
header

Request body · required

application/json

AccountConnectRequestobject

FieldTypeDescription

channelrequired
email | linkedin | twitter
provider
string
e.g. google, microsoft, x (channel-dependent)

Example

{
  "channel": "email",
  "provider": "google"
}

Responses

200OK

GET/api/v1/accounts/connect/{connectId}

Poll connect session

Parameters

connectIdstring · uuid
path · required

Responses

200OK

Providers

Advanced per-provider escape hatch (prefer resource capabilities).

Scopes: data:read · data:run

GET/api/v1/providers

Provider catalog (escape hatch)

Responses

200OK

GET/api/v1/providers/{provider}

Provider detail

Parameters

providerstring
path · required

Responses

200OK

GET/api/v1/providers/{provider}/{path}

Invoke provider endpoint (GET)

Parameters

providerstring
path · required
pathstring
Endpoint path segments joined by /
path · required

Responses

200OK

POST/api/v1/providers/{provider}/{path}

Invoke provider endpoint (POST)

Parameters

providerstring
path · required
pathstring
path · required
Idempotency-Keystring
header

Request body

application/json

object

Responses

200OK

Events

Workspace event log for agents and webhooks.

Scopes: agent:run · webhooks:manage

GET/api/v1/events

Workspace event log

Parameters

typestring
query
limitinteger
query

Responses

200OK

GET/api/v1/runs/{id}/events

Run event stream

Parameters

idstring · uuid
path · required

Responses

200OK

Inventory

Browse catalog and purchase LinkedIn seats or email infra.

Scopes: inventory:read · inventory:write

GET/api/v1/inventory/catalog

Inventory catalog

Responses

200OK

GET/api/v1/inventory/orders

List inventory orders

Responses

200OK

POST/api/v1/inventory/orders

Create inventory order

Parameters

Idempotency-Keystring
header

Request body · required

application/json

CreateInventoryOrderRequestobject

FieldTypeDescription

kindrequired
linkedin | email
quantityrequired
integer
term
monthly | quarterly | yearly
region
string
account_type
string
branding
string
agreements_acceptedrequired
boolean
agreement_ids
string[]
agreement_versions
string[]

Example

{
  "kind": "linkedin",
  "quantity": 2,
  "term": "quarterly",
  "region": "western",
  "account_type": "standard",
  "branding": "armada_sdr",
  "agreements_accepted": true,
  "agreement_ids": ["linkedin-rental"],
  "agreement_versions": ["2026-01"]
}

Responses

200OK

GET/api/v1/inventory/orders/{orderId}

Get inventory order

Parameters

orderIdstring · uuid
path · required

Responses

200OK

Webhooks

Subscribe to workspace events (HMAC-signed).

Scopes: webhooks:manage

GET/api/v1/webhooks

List webhook endpoints

Responses

200OK

POST/api/v1/webhooks

Register webhook

Parameters

Idempotency-Keystring
header

Request body · required

application/json

CreateWebhookRequestobject

FieldTypeDescription

urlrequired
string · uri
events
string[]
Event names to subscribe to (defaults to the live webhook enum)
description
string

Example

{
  "url": "https://your-app.com/webhooks/armada",
  "events": ["enrollment.replied", "find_run.completed"],
  "description": "Prod CRM sync"
}

Responses

201Created

DELETE/api/v1/webhooks/{webhookId}

Disable webhook

Parameters

webhookIdstring · uuid
path · required

Responses

200OK

analytics

GET/api/v1/analytics/campaigns/{id}

Campaign send/reply KPIs

Parameters

idstring · uuid
path · required

Responses

200OK

GET/api/v1/analytics/outbound

Workspace outbound KPIs

Responses

200OK

calendar

GET/api/v1/calendar/events

List Armada-created calendar holds (calendar.events.list)

Parameters

statusconfirmed | cancelled
query
limitinteger · min 1 · max 100
query

Responses

200OK

POST/api/v1/calendar/events

Create Google/Outlook hold (calendar.events.create)

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

titlerequired
string
startrequired
string · date-time
endrequired
string · date-time
timezone
string
description
string
attendees
object[]
provider
google | outlook
send_updates
boolean
add_meet_link
boolean

Responses

200Created (id = provider event id; hold_id = Armada row)

DELETE/api/v1/calendar/events/{id}

Delete/cancel hold (calendar.events.delete)

Parameters

idstring
path · required

Responses

200Deleted

PATCH/api/v1/calendar/events/{id}

Update hold (calendar.events.update) — hold_id or provider event id

Parameters

idstring
path · required
Idempotency-Keystring
header

Request body

application/json

object

FieldTypeDescription

title
string
start
string · date-time
end
string · date-time
timezone
string
description
string
attendees
object[]
send_updates
boolean

Responses

200OK

POST/api/v1/calendar/freebusy

Google/Outlook free/busy (calendar.freebusy.get)

Request body · required

application/json

object

FieldTypeDescription

fromrequired
string · date-time
torequired
string · date-time
timezone
string
provider
google | outlook

Responses

200OK

POST/api/v1/calendar/propose-slots

Propose 2–3 meeting slots (calendar.slots.propose)

Request body

application/json

object

FieldTypeDescription

from
string · date-time
to
string · date-time
timezone
string
max
integer
duration_minutes
integer
provider
calcom | calendly | google | outlook

Responses

200OK

calls

GET/api/v1/calls

List call sessions

Parameters

limitinteger · min 1 · max 200
query
offsetinteger · min 0
query

Responses

200OK

POST/api/v1/calls

Place outbound call (enqueue place_call)

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

toE164required
string
E.164 destination
fromNumberId
string · uuid
listRowId
string · uuid

Responses

202Queued

GET/api/v1/calls/{sessionId}

Get call session detail

Parameters

sessionIdstring · uuid
path · required

Responses

200OK

POST/api/v1/calls/{sessionId}/disposition

Set call disposition

Parameters

sessionIdstring · uuid
path · required
Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

dispositionrequired
string
notes
string

Responses

200OK

GET/api/v1/calls/{sessionId}/recording

Get call recording URL

Parameters

sessionIdstring · uuid
path · required

Responses

200OK

GET/api/v1/phone-numbers

List workspace DIDs

Responses

200OK

POST/api/v1/sms

Enqueue SMS (capability sms.send)

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

toE164required
string
bodyrequired
string
fromNumberId
string · uuid
listRowId
string · uuid

Responses

202Queued

crm

POST/api/v1/crm/activity

Enqueue CRM activity/call log

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

connection_idrequired
string · uuid
list_row_id
string · uuid
call_session_id
string · uuid
notes
string
disposition
string

Responses

202Queued

GET/api/v1/crm/connections

List CRM connections (no secrets)

Responses

200OK

POST/api/v1/crm/deals

Enqueue CRM deal from a list row

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

connection_idrequired
string · uuid
list_row_idrequired
string · uuid
name
string
amount
string

Responses

202Queued

POST/api/v1/crm/sync

Enqueue CRM list sync

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

connection_idrequired
string · uuid
list_idrequired
string · uuid
kind
import | export | sync
object
people | companies

Responses

202Queued

gtm

POST/api/v1/gtm/inbox

Inbox work queue (capability gtm.work_inbox)

Request body

application/json

object

FieldTypeDescription

limit
integer
unread_only
boolean
channel
string
q
string

Responses

200OK

POST/api/v1/gtm/outbound

Build outbound job (capability gtm.build_outbound). Never launches.

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

icprequired
string
playbook_id
string
campaign_id
string · uuid
list_name
string
limit
integer
entity
people | companies
require_approval
boolean

Responses

202Accepted

POST/api/v1/gtm/research

Account research job (capability gtm.research_account)

Parameters

Idempotency-Keystring
header

Request body · required

application/json

object

FieldTypeDescription

queryrequired
string
domain
string
titles
string[]
limit
integer
find_email
boolean

Responses

200OK

GET/api/v1/gtm/standup

Outbound standup (capability gtm.campaign_standup)

Parameters

campaign_idstring · uuid
query

Responses

200OK

mcp

POST/api/v1/mcp

Hosted Streamable HTTP MCP (JSON-RPC). Auth Bearer arm_.

Request body

application/json

object

Responses

200JSON-RPC response