API reference

Generated from the OpenAPI document, version 1.3.0. Base URL https://api.arm-age.com; every route needs a key with the scope it names.

Endpoints

The same document, machine-readable, for code generators and API tools: https://api.arm-age.com/v1/openapi.json.

The organization's stories, newest change first

GET/v1/storiesscope stories:read

Every story of the key's organization whatever its status (draft to published), with the current version's title and summary. Filter with status (comma-separated). Keyset pagination: pass next_cursor back as cursor. Scope stories:read. Cache-Control: private, no-store.

Parameters
Name	In	Type	Description
`status`	query	`string`	Comma-separated statuses to include: draft, ai_generated, review_required, approved, scheduled, publishing, published, failed, rejected, unpublished, archived.
`limit`	query	`integer`
`cursor`	query	`string`	The `next_cursor` of the previous page.

Responses
Status	Body	When
200	List of Story	A page of stories.
400	Error	Unknown status, limit outside 1-100 or a malformed cursor (`invalid_parameters`; `error.fields`).
401	Error	No key, a malformed, expired or revoked key, or a key for the other environment (`missing_api_key`, `invalid_api_key`, `wrong_environment`). `WWW-Authenticate: Bearer`.
403	Error	The key lacks the scope this route needs (`insufficient_scope`).
429	Error	More than 300 requests a minute for this key, or a flood from one client IP (`too_many_requests`). `Retry-After: 60`.
503	Error	The client API is not configured in this environment (`api_unavailable`).

curl

curl https://api.arm-age.com/v1/stories \
  -H "Authorization: Bearer $ARMAGE_API_KEY"

One story with its body and decision history

GET/v1/stories/{id}scope stories:read

The current version's structured body and every recorded approval decision, newest first. Only decisions recorded by the approval credential are listed (ADR 0038). Scope stories:read.

Parameters
Name	In	Type	Description
`id` (required)	path	`string (uuid)`

Responses
Status	Body	When
200	StoryDetail	The story.
401	Error	No key, a malformed, expired or revoked key, or a key for the other environment (`missing_api_key`, `invalid_api_key`, `wrong_environment`). `WWW-Authenticate: Bearer`.
403	Error	The key lacks the scope this route needs (`insufficient_scope`).
404	Error	No story with this id in the key's organization (`not_found`).
429	Error	More than 300 requests a minute for this key, or a flood from one client IP (`too_many_requests`). `Retry-After: 60`.
503	Error	The client API is not configured in this environment (`api_unavailable`).

curl

curl https://api.arm-age.com/v1/stories/<story id> \
  -H "Authorization: Bearer $ARMAGE_API_KEY"

The approval queue: stories waiting for a decision

GET/v1/approvalsscope approvals:read

Stories in review_required, newest change first. Decisions are made by people in the Armage workspace (email and Slack approvals are planned), never by an API key: nothing publishes unapproved. Scope approvals:read.

Parameters
Name	In	Type	Description
`limit`	query	`integer`
`cursor`	query	`string`	The `next_cursor` of the previous page.

Responses
Status	Body	When
200	List of Story	A page of waiting stories.
400	Error	Limit outside 1-100 or a malformed cursor (`invalid_parameters`).
401	Error	No key, a malformed, expired or revoked key, or a key for the other environment (`missing_api_key`, `invalid_api_key`, `wrong_environment`). `WWW-Authenticate: Bearer`.
403	Error	The key lacks the scope this route needs (`insufficient_scope`).
429	Error	More than 300 requests a minute for this key, or a flood from one client IP (`too_many_requests`). `Retry-After: 60`.
503	Error	The client API is not configured in this environment (`api_unavailable`).

curl

curl https://api.arm-age.com/v1/approvals \
  -H "Authorization: Bearer $ARMAGE_API_KEY"

Published stories as JSON Feed 1.1 (for a CMS to pull)

GET/v1/feed.jsonscope feed:read

The 50 most recent published stories with plain-text and minimal escaped HTML bodies. Scope feed:read. For importers that cannot send headers, the key may be given as ?key= - only a key whose sole scope is feed:read.

Responses
Status	Body	When
200	JSON Feed 1.1	The feed (`application/feed+json`).
401	Error	No key, a malformed, expired or revoked key, or a key for the other environment (`missing_api_key`, `invalid_api_key`, `wrong_environment`). `WWW-Authenticate: Bearer`.
403	Error	The key lacks the scope this route needs (`insufficient_scope`).
429	Error	More than 300 requests a minute for this key, or a flood from one client IP (`too_many_requests`). `Retry-After: 60`.
503	Error	The client API is not configured in this environment (`api_unavailable`).

curl

curl https://api.arm-age.com/v1/feed.json \
  -H "Authorization: Bearer $ARMAGE_API_KEY"

Published stories as RSS 2.0 (for a CMS to pull)

GET/v1/feed.xmlscope feed:read

The same 50 stories as /v1/feed.json, with content:encoded bodies. Scope feed:read; the same ?key= rule.

Responses
Status	Body	When
200	—	The feed (`application/rss+xml`).
401	Error	No key, a malformed, expired or revoked key, or a key for the other environment (`missing_api_key`, `invalid_api_key`, `wrong_environment`). `WWW-Authenticate: Bearer`.
403	Error	The key lacks the scope this route needs (`insufficient_scope`).
429	Error	More than 300 requests a minute for this key, or a flood from one client IP (`too_many_requests`). `Retry-After: 60`.
503	Error	The client API is not configured in this environment (`api_unavailable`).

curl

curl https://api.arm-age.com/v1/feed.xml \
  -H "Authorization: Bearer $ARMAGE_API_KEY"

The organization's webhook endpoints

GET/v1/webhook_endpointsscope webhooks:read

Every endpoint, enabled or not, newest first; never its signing secret (only secret_hint, its last four characters). Endpoints are added, tested, disabled and re-enabled by an owner or admin in the Armage workspace. Scope webhooks:read.

Responses
Status	Body	When
200	List of WebhookEndpoint	The endpoints (one page).
401	Error	No key, a malformed, expired or revoked key, or a key for the other environment (`missing_api_key`, `invalid_api_key`, `wrong_environment`). `WWW-Authenticate: Bearer`.
403	Error	The key lacks the scope this route needs (`insufficient_scope`).
429	Error	More than 300 requests a minute for this key, or a flood from one client IP (`too_many_requests`). `Retry-After: 60`.
503	Error	The client API is not configured in this environment (`api_unavailable`).

curl

curl https://api.arm-age.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $ARMAGE_API_KEY"

The webhook delivery log, newest first

GET/v1/webhook_deliveriesscope webhooks:read

One row per event per endpoint: status (pending while retries remain, delivered, failed), attempts, the last HTTP status and a short error. Payloads are not kept. Filter with endpoint_id; keyset pagination as /v1/stories. Scope webhooks:read.

Parameters
Name	In	Type	Description
`endpoint_id`	query	`string (uuid)`	Only this endpoint's deliveries.
`limit`	query	`integer`
`cursor`	query	`string`	The `next_cursor` of the previous page.

Responses
Status	Body	When
200	List of WebhookDelivery	A page of deliveries.
400	Error	A malformed `endpoint_id`, limit outside 1-100 or a malformed cursor (`invalid_parameters`).
401	Error	No key, a malformed, expired or revoked key, or a key for the other environment (`missing_api_key`, `invalid_api_key`, `wrong_environment`). `WWW-Authenticate: Bearer`.
403	Error	The key lacks the scope this route needs (`insufficient_scope`).
429	Error	More than 300 requests a minute for this key, or a flood from one client IP (`too_many_requests`). `Retry-After: 60`.
503	Error	The client API is not configured in this environment (`api_unavailable`).

curl

curl https://api.arm-age.com/v1/webhook_deliveries \
  -H "Authorization: Bearer $ARMAGE_API_KEY"

Webhook events

Coming Armage POSTs these to your endpoint, signed. Setting up an endpoint and verifying a request: Webhooks.

Events
Type	Body	When
`story.submitted`	WebhookEvent	A story was sent for review: it is now in the approval queue. Sent to every enabled endpoint subscribed to `story.submitted`, signed per Standard Webhooks.
`story.approved`	WebhookEvent	A person approved the current version of a story. Sent to every enabled endpoint subscribed to `story.approved`, signed per Standard Webhooks.
`story.rejected`	WebhookEvent	A person sent a story back with a note. Sent to every enabled endpoint subscribed to `story.rejected`, signed per Standard Webhooks.
`story.published`	WebhookEvent	A story was published. Sent to every enabled endpoint subscribed to `story.published`, signed per Standard Webhooks.
`story.unpublished`	WebhookEvent	A published story was taken down. Sent to every enabled endpoint subscribed to `story.unpublished`, signed per Standard Webhooks.
`webhook.test`	WebhookTestEvent	Sent once when someone presses "Send test event" in the Armage workspace. Signed like every event; never recorded as a delivery and never retried.

Objects

Responses may gain fields without a new version: ignore fields you do not recognize. Timestamps are ISO 8601 with an offset.

Story

Fields
Field	Type	Notes
`object`	`"story"`	always present
`id`	`string`	always present
`type`	`"insight" \| "press_release" \| "announcement" \| "in_the_news" \| "event" \| "video"`	always present
`slug`	`string`	always present
`status`	`"draft" \| "ai_generated" \| "review_required" \| "approved" \| "scheduled" \| "publishing" \| "published" \| "failed" \| "rejected" \| "unpublished" \| "archived"`	always present
`title`	`string`	always present; may be null
`summary`	`string`	always present; may be null
`version`	`integer`	always present; may be null
`topics`	`string[]`	always present
`published_at`	`string (date-time)`	always present; may be null
`created_at`	`string (date-time)`	always present
`updated_at`	`string (date-time)`	always present

StoryDetail

Fields
Field	Type	Notes
`object`	`"story"`	always present
`id`	`string`	always present
`type`	`"insight" \| "press_release" \| "announcement" \| "in_the_news" \| "event" \| "video"`	always present
`slug`	`string`	always present
`status`	`"draft" \| "ai_generated" \| "review_required" \| "approved" \| "scheduled" \| "publishing" \| "published" \| "failed" \| "rejected" \| "unpublished" \| "archived"`	always present
`title`	`string`	always present; may be null
`summary`	`string`	always present; may be null
`version`	`integer`	always present; may be null
`topics`	`string[]`	always present
`published_at`	`string (date-time)`	always present; may be null
`created_at`	`string (date-time)`	always present
`updated_at`	`string (date-time)`	always present
`body`	`object[]`	always present
`approvals`	`ApprovalDecision[]`	always present

ApprovalDecision

Fields
Field	Type	Notes
`object`	`"approval_decision"`	always present
`id`	`string`	always present
`version`	`integer`	always present; may be null
`decision`	`"approved" \| "rejected"`	always present
`actor_type`	`string`	always present
`actor_role`	`string`	always present
`note`	`string`	always present; may be null
`decided_at`	`string (date-time)`	always present

WebhookEndpoint

Fields
Field	Type	Notes
`object`	`"webhook_endpoint"`	always present
`id`	`string`	always present
`url`	`string`	always present
`events`	`"story.submitted" \| "story.approved" \| "story.rejected" \| "story.published" \| "story.unpublished"[]`	always present
`status`	`"enabled" \| "disabled"`	always present
`disabled_reason`	`"failing" \| "by_client" \| "by_armage"`	always present; may be null
`secret_hint`	`string`	always present
`created_at`	`string (date-time)`	always present
`updated_at`	`string (date-time)`	always present

WebhookDelivery

Fields
Field	Type	Notes
`object`	`"webhook_delivery"`	always present
`id`	`string`	always present
`endpoint_id`	`string`	always present
`event_id`	`string`	always present
`event_type`	`"story.submitted" \| "story.approved" \| "story.rejected" \| "story.published" \| "story.unpublished"`	always present
`story_id`	`string`	always present; may be null
`status`	`"pending" \| "delivered" \| "failed"`	always present
`attempts`	`integer`	always present
`last_status_code`	`integer`	always present; may be null
`last_error`	`string`	always present; may be null
`next_attempt_at`	`string (date-time)`	always present; may be null
`created_at`	`string (date-time)`	always present
`delivered_at`	`string (date-time)`	always present; may be null

WebhookEvent

Fields
Field	Type	Notes
`id`	`string`	always present. The event id; also the `webhook-id` header. Dedupe on it.
`object`	`"event"`	always present
`type`	`"story.submitted" \| "story.approved" \| "story.rejected" \| "story.published" \| "story.unpublished"`	always present
`created_at`	`string (date-time)`	always present. When the story changed.
`data`	`object`	always present

WebhookTestEvent

Fields
Field	Type	Notes
`id`	`string`	always present
`object`	`"event"`	always present
`type`	`"webhook.test"`	always present
`created_at`	`string (date-time)`	always present
`data`	`object`	always present

Error

Fields
Field	Type	Notes
`error`	`object`	always present

Build against a sandbox workspace

Or writehello@arm-age.com

Ask for a sandbox Your API page

Navigation

Quick links

Client access

API reference

Endpoints

The organization's stories, newest change first

One story with its body and decision history

The approval queue: stories waiting for a decision

Published stories as JSON Feed 1.1 (for a CMS to pull)

Published stories as RSS 2.0 (for a CMS to pull)

The organization's webhook endpoints

The webhook delivery log, newest first

Webhook events

Objects

Story

StoryDetail

ApprovalDecision

WebhookEndpoint

WebhookDelivery

WebhookEvent

WebhookTestEvent

Error

Build against a sandbox workspace