Getting started

Armada API reference

Workspace-scoped REST API for lists, Find, playbooks, sequences, enrollments, inbox, content, CRM, and webhooks. Generated from the live OpenAPI spec — every route below matches production, with request and response schemas where defined.

Authentication

Send your workspace API key on every request. Keys are minted in Settings → Developers after API access is approved.

Authorization: Bearer arm_…

Base URL

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

https://app.getarmada.com/api/v1

Scopes

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

lists:read
lists:write
find:run
campaigns:read
campaigns:write
campaigns:enroll
inbox:read
inbox:write
content:read
content:write
accounts:read
accounts:write
inventory:read
inventory:write
crm:read
crm:write
inbound:read
inbound:write
webhooks:manage
billing:read
billing:write
workspaces:read
workspaces: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 (Find, enroll, inbox write, content write, inventory, accounts)	30/min	120/min

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

Access

API access is approved per workspace. Request it in Settings → Developers; usage bills the same as the product UI.

Models

Schemas

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

CreateListBody

Properties

object

FieldTypeDescription

namerequired
string
entity
people | companies
origin
crm | find

Error

Properties

object

FieldTypeDescription

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

ListDetail

Properties

object

FieldTypeDescription

idrequired
string · uuid
namerequired
string
entityrequired
people | companies
originrequired
crm | find
row_countrequired
integer
created_atrequired
string
updated_atrequired
string
columnsrequired
object[]

ListSummary

Properties

object

FieldTypeDescription

idrequired
string · uuid
namerequired
string
entityrequired
people | companies
originrequired
crm | find
row_countrequired
integer
created_atrequired
string
updated_atrequired
string

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

Me

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

Scopes: Any valid key

GET/api/v1/me

Key identity, scopes, entitlements, credits, on-demand

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
401Missing or invalid API keyError
Response body
Errorobject
FieldTypeDescription
- errorrequired
  object
  coderequired
  string
  messagerequired
  string
  request_idrequired
  string
  details
  unknown
403Missing entitlement or scopeError
Response body
Errorobject
FieldTypeDescription
- errorrequired
  object
  coderequired
  string
  messagerequired
  string
  request_idrequired
  string
  details
  unknown
429Rate limitedError
Response body
Errorobject
FieldTypeDescription
- errorrequired
  object
  coderequired
  string
  messagerequired
  string
  request_idrequired
  string
  details
  unknown

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 URL for enable_on_demand / upgrade / portal

Request body

application/json

object

intent: enable_on_demand | buy_credits | portal

FieldTypeDescription

intentrequired
string
limit_centsrequired
integer

Example

{
  "intent": "enable_on_demand",
  "limit_cents": 40000
}

Responses

200OK

PATCH/api/v1/billing/on-demand

Update on-demand limit when already enabled

Request body

application/json

object

FieldTypeDescription

enabledrequired
boolean
limit_centsrequired
integer

Example

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

Responses

200OK

Lists

Create lists, rows, columns, ICP, Fit, Signal, Live, verify, and CSV export.

Scopes: lists:read · lists:write

GET/api/v1/lists

List workspace lists

Responses

200OK
Response body
object
FieldTypeDescription
- datarequired
  object[]
401Missing or invalid API keyError
Response body
Errorobject
FieldTypeDescription
- errorrequired
  object
  coderequired
  string
  messagerequired
  string
  request_idrequired
  string
  details
  unknown

POST/api/v1/lists

Create a list

Request body · required

application/json

CreateListBodyobject

FieldTypeDescription

namerequired
string
entity
people | companies
origin
crm | find

Responses

201CreatedListDetail
Response body
ListDetailobject
FieldTypeDescription
- idrequired
  string · uuid
- namerequired
  string
- entityrequired
  people | companies
- originrequired
  crm | find
- row_countrequired
  integer
- created_atrequired
  string
- updated_atrequired
  string
- columnsrequired
  object[]
401Missing or invalid API keyError
Response body
Errorobject
FieldTypeDescription
- errorrequired
  object
  coderequired
  string
  messagerequired
  string
  request_idrequired
  string
  details
  unknown

GET/api/v1/lists/{listId}

List detail + columns

Parameters

listIdstring · uuid
path · required

Responses

200OK

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

Stream list as CSV

Parameters

listIdstring · uuid
path · required
searchstring
query
filenamestring
query

Responses

200text/csv stream
403csvExport entitlement required

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

Page list rows

Parameters

listIdstring · uuid
path · required
limitinteger · min 1 · max 200
query
offsetinteger · min 0
query
searchstring
query

Responses

200OK

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

Append rows

Parameters

listIdstring · uuid
path · required

Request body

application/json

object

FieldTypeDescription

rowsrequired
object[]

Example

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

Responses

201Created

Find

Run Find from a plan or playbook recipe; poll run status.

Scopes: find:run · lists:read

POST/api/v1/find-runs

Create list from plan and start Find

Request body

application/json

object

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

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 Find on an existing list

Parameters

listIdstring · uuid
path · required

Request body

application/json

object

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

Playbooks, sequence authoring, audience binding, launch, pause, and analytics.

Scopes: campaigns:read · campaigns:write

GET/api/v1/campaigns

List campaigns

Responses

200OK

GET/api/v1/campaigns/{campaignId}

Campaign summary

Parameters

campaignIdstring · uuid
path · required

Responses

200OK

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

Launch draft/paused campaign

Parameters

campaignIdstring · uuid
path · required
Idempotency-Keystring
Optional. 1–256 chars [A-Za-z0-9._-]. Successful responses cached 24h per key.
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 active campaign

Parameters

campaignIdstring · uuid
path · required
Idempotency-Keystring
Optional. 1–256 chars [A-Za-z0-9._-]. Successful responses cached 24h per key.
header

Request body

application/json

object

Example

{}

Responses

200OK

Enrollments

Enroll list rows, list enrollments, pause, resume, or remove.

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 list row ids (max 100)

Parameters

campaignIdstring · uuid
path · required
Idempotency-Keystring
Optional. 1–256 chars [A-Za-z0-9._-]. Successful responses cached 24h per key.
header

Request body

application/json

object

FieldTypeDescription

list_row_idsrequired
string[]

Example

{
  "list_row_ids": [
    "33333333-3333-3333-3333-333333333333"
  ]
}

Responses

201Created

GET/api/v1/enrollments/{enrollmentId}

Enrollment status

Parameters

enrollmentIdstring · uuid
path · required

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}/remove

Remove 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

Content

Schedule posts, inspiration, watch lists, library, and post metrics.

Scopes: content:read · content:write

GET/api/v1/content/posts

List content posts

Responses

200OK

POST/api/v1/content/posts

Schedule a post

Request body

application/json

object

FieldTypeDescription

account_idrequired
string
channelrequired
string
bodyrequired
string
scheduled_atrequired
string

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

Inbox

Read and reply on Unibox threads (email, LinkedIn, SMS, X).

Scopes: inbox:read · inbox:write

GET/api/v1/inbox/threads

Campaign inbox thread summary

Responses

200OK

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)

Parameters

channelemail | linkedin | twitter | phone | sms
query

Responses

200OK

POST/api/v1/accounts/connect

Start Armada-branded personal account connect (browser URL)

Request body

application/json

object

FieldTypeDescription

channelrequired
string
providerrequired
string

Example

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

Responses

200OK (connect_id, url, expires_at)

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

Poll connect session status

Parameters

connectIdstring · 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 (regions, terms, email retail, stock)

Parameters

channelemail | linkedin
query

Responses

200OK

GET/api/v1/inventory/orders

List inventory orders

Responses

200OK

POST/api/v1/inventory/orders

Purchase LinkedIn seats or email infra (card on file or Checkout URL)

Request body

application/json

object

FieldTypeDescription

kindrequired
string
quantityrequired
integer
termrequired
string
regionrequired
string
account_typerequired
string
brandingrequired
string
agreements_acceptedrequired
boolean
agreement_idsrequired
string[]
agreement_versionsrequired
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 (order_id, charged, url, seats_created, holds_missing)

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

Get inventory order status

Parameters

orderIdstring · uuid
path · required

Responses

200OK

Webhooks

Subscribe to Find, enrollment, inbox, and content events (HMAC-signed).

Scopes: webhooks:manage

GET/api/v1/webhooks

List webhook endpoints

Responses

200OK

POST/api/v1/webhooks

Register webhook endpoint

Request body

application/json

object

FieldTypeDescription

urlrequired
string
eventsrequired
string[]
descriptionrequired
string

Example

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

Responses

201Created (includes secret once)

DELETE/api/v1/webhooks/{webhookId}

Disable webhook endpoint

Parameters

webhookIdstring · uuid
path · required

Responses

200OK