# Outpost API

Create an Outpost key in Settings. The secret is shown once. Send it in the Authorization header on each /v1 call. A read key opens the environment, its listeners, caught events, and the catalog. A manage key changes listeners and automations, edits a definition, and replays an event. An agency admin can create a key for every environment. Register the listener URL in Bluestone PIM. Bluestone signs that call with the listener secret.

Authorization: Bearer, with a key created in Settings. The secret starts with op_ and is shown once.
A missing or revoked bearer returns 401 and {"error":"Missing or revoked bearer."}.
A key that does not cover the environment returns 404 and {"error":"Environment not found"}.
A read key on a manage route returns 403 and {"error":"An organisation admin does this."}.

## POST /v1/accounts/admins

Invite an agency admin

The person must already have signed in on this account.

## DELETE /v1/actions/{id}

Delete an automation

Caught events stay. The body does not need confirm.

## PATCH /v1/actions/{id}

Edit an automation

Keeps the kind. The name, the target, and the saved rule can change.

## POST /v1/actions/{id}/pause

Pause an automation

Say whether the action is enabled.

## GET /v1/environments/{id}

Read an environment

Key status, listeners, actions, and the latest finished events. The payload of a caught event is not included.

## GET /v1/environments/{id}/assignees

List assignees

One page of users and one page of user groups. An organisation admin does this.

## POST /v1/environments/{id}/check

Check stored API keys

Opens the seal and asks Bluestone PIM for a new token. The secret stays hidden.

## POST /v1/environments/{id}/connect

Save API keys

Asks Bluestone PIM for a token, then seals the client id and client secret on this environment.

## GET /v1/environments/{id}/definitions

List definitions

Walks the definition list, at most five pages.

## POST /v1/environments/{id}/listeners

Create a listener

Returns the webhook secret once. Register that URL in Bluestone PIM. Do not call it with a bearer.

## GET /v1/environments/{id}/studio/attributes

Read the attribute catalog

Groups, then ungrouped definitions.

## GET /v1/environments/{id}/studio/cla

Read category attributes

One page of category-level attributes.

## POST /v1/environments/{id}/studio/delete

Remove category attributes

Removes the definition from those categories. The definition stays. The body does not need confirm.

## POST /v1/environments/{id}/studio/edit

Edit a definition cell

Name, number, group, unit, or scope. Data type stays.

## GET /v1/environments/{id}/studio/map

Read the saved map

The snapshot from the last refresh. This does not call Bluestone PIM.

## GET /v1/environments/{id}/studio/map/categories/{categoryId}

List products in a category

The first page of products in that category.

## POST /v1/environments/{id}/studio/map/refresh

Refresh the map

Starts a new snapshot. An organisation admin does this.

## POST /v1/environments/{id}/studio/move

Move a definition

Puts the definition in a group, or leaves it ungrouped when groupId is null.

## GET /v1/environments/{id}/studio/products

Read product assignments

Products assigned to one definition, or the count when count=1.

## POST /v1/events/{id}/replay

Replay an event

A skipped or failed row runs again. The attempt log stays.

## POST /v1/invites

Send an invite

Returns the sign-up URL once. It expires 14 days after it is created.

## POST /v1/invites/{id}/revoke

Revoke an invite

The invite can no longer be used.

## GET /v1/keys

List keys

Lists keys that cover the environment, or every key on the account when the bearer covers the account. Revoked keys are left out. The secret is not listed.

## POST /v1/keys

Create a key

A manage key for one environment needs an organisation admin. A key for every environment needs an agency admin. The secret is returned once.

## DELETE /v1/keys/{id}

Revoke a key

Sets revoked_at. A later call with that bearer is refused.

## DELETE /v1/listeners/{id}

Delete a listener

Removes the listener, its automations, and its caught events. The body does not need confirm.

## PATCH /v1/listeners/{id}

Rename a listener

The name is at most 80 characters. rotateSecret true returns a new secret once.

## POST /v1/listeners/{id}/actions

Create an automation

A calculation, a code, or a task. The name is required.

## GET /v1/listeners/{id}/deliveries

List caught events

One page of 20 rows. Cleared rows are left out.

## GET /v1/listeners/{id}/deliveries/{eventId}

Read one caught event

The stored payload and the write-back. A skipped row has no write-back.

## POST /v1/listeners/{id}/events/clear

Clear the event list

Clears rows that are not leased. The body does not need confirm.

## POST /v1/listeners/{id}/labels

Fetch product names

Names at most 20 events. Ids that already have a product label are returned as stored.

## PATCH /v1/listeners/{id}/monitor

Fetch names on ingress

Choose whether new events fetch the product name.

## POST /v1/listeners/{id}/pause

Pause a listener

Say whether the listener is enabled. A paused listener still stores webhooks.

## POST /v1/organisations

Add an organisation

Creates the organisation and its first environment. An agency admin does this.

## DELETE /v1/organisations/{id}

Remove an organisation

The body confirm is the organisation name. Environments, API keys for those environments, listeners, and caught events are removed.

## POST /v1/organisations/{id}/environments

Add an environment

Test or Production. It keeps its own API keys.