Create a new app

POST

/v1/apps

const url = 'https://app.everruns.com/api/v1/apps';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"agent_id":"agent_01933b5a00007000800000000000001","agent_identity_id":"identity_01933b5a00007000800000000000001","agent_version_id":"agentver_01933b5a00007000800000000000001","agent_version_policy":"default","channel_config":"example","channel_type":"slack","description":"Customer support bot connected to Slack","harness_id":"harness_01933b5a00007000800000000000001","name":"Support Bot"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://app.everruns.com/api/v1/apps \
  --header 'Content-Type: application/json' \
  --data '{ "agent_id": "agent_01933b5a00007000800000000000001", "agent_identity_id": "identity_01933b5a00007000800000000000001", "agent_version_id": "agentver_01933b5a00007000800000000000001", "agent_version_policy": "default", "channel_config": "example", "channel_type": "slack", "description": "Customer support bot connected to Slack", "harness_id": "harness_01933b5a00007000800000000000001", "name": "Support Bot" }'

Request Body^required

application/json

Request to create a new app

object

agent_id

Optional ID of the agent to use.

string | null

Example

agent_01933b5a00007000800000000000001

agent_identity_id

Optional resident agent identity for unattended/channel execution.

string | null

Example

identity_01933b5a00007000800000000000001

agent_version_id

string | null

Example

agentver_01933b5a00007000800000000000001

agent_version_policy

How an App resolves the Agent version it runs. Example shape is defined on AgentVersionPolicy.

string

Allowed values: default latest pinned

Example

pinned

channel_config

Initial channel configuration. Shape depends on channel_type. Examples: {"token": "whk_redacted", "message": "Run support triage"} for webhook, {"cron_expression": "0 9 * * *", "message": "Daily standup"} for schedule.

object | null

channel_type

One of:

null
string

null

Optional initial channel type (creates the first channel on the app). Example shape is defined on ChannelType.

string

Allowed values: slack ag_ui schedule webhook a2a fcp

Example

webhook

description

Description of what the app does.

string | null

Example

Customer support bot connected to Slack

harness_id

required

ID of the harness to use.

string

Example

harness_01933b5a00007000800000000000001

name

required

Display name of the app.

string

Example

Support Bot

Responses

201

App created successfully

application/json

Wrapper that adds API and UI links to a serialized resource.

Uses self_url (not url) for the API link to avoid collision with resources that already have a url field (e.g. McpServer).

object

agent_id

Optional ID of the agent to use (format: agent_{32-hex}).

string | null

agent_identity_id

Optional virtual identity that represents the app in unattended/channel execution.

string | null

agent_version_id

Pinned agent version. Required when policy is pinned.

string | null

agent_version_policy

Version resolution policy for the optional agent.

string

Allowed values: default latest pinned

archived_at

Timestamp when the app was archived.

string | null format: date-time

channels

Distribution channels attached to this app.

Array<object>

A single distribution channel attached to an App. Each channel has its own type, config, and lifecycle status.

object

channel_config

Channel-specific configuration (validated per channel type).

channel_type

required

Channel type (e.g. slack).

string

Allowed values: slack ag_ui schedule webhook a2a fcp

created_at

required

Timestamp when this channel was created.

string format: date-time

enabled

Whether this channel is enabled.

boolean

required

External identifier (appchan_<32-hex>). Shown as “id” in API.

string

updated_at

required

Timestamp when this channel was last updated.

string format: date-time

created_at

required

Timestamp when the app was created.

string format: date-time

deleted_at

Timestamp when the app was deleted.

string | null format: date-time

description

Human-readable description of what the app does.

string | null

effective_owner

One of:

null
object

null

harness_id

required

ID of the harness to use (format: harness_{32-hex}).

string

required

External identifier (app_<32-hex>). Shown as “id” in API.

string

name

required

Display name of the app.

string

owner

One of:

null
object

null

owner_principal_id

required

Owning principal for this app.

string

published_at

Timestamp when the app was last published.

string | null format: date-time

resolved_owner_user_id

Denormalized effective human owner of the owning principal lineage.

string | null format: uuid

status

required

Current lifecycle status.

string

Allowed values: draft published archived deleted

updated_at

required

Timestamp when the app was last updated.

string format: date-time

self_url

required

Full API endpoint URL for this resource.

string

ui_link

required

Alias for view_url, used by command and MCP outputs.

string

view_url

required

Full UI URL for viewing this resource.

string

Example

{
  "agent_id": "agent_01933b5a00007000800000000000001",
  "agent_identity_id": "identity_01933b5a00007000800000000000001",
  "agent_version_id": "agentver_01933b5a00007000800000000000001",
  "agent_version_policy": "default",
  "channels": [
    {
      "channel_type": "slack",
      "id": "appchan_01933b5a000070008000000000000001"
    }
  ],
  "effective_owner": {
    "id": "principal_01933b5a000070008000000000000001",
    "kind": "user"
  },
  "harness_id": "harness_01933b5a00007000800000000000001",
  "id": "app_01933b5a000070008000000000000001",
  "owner": {
    "id": "principal_01933b5a000070008000000000000001",
    "kind": "user"
  },
  "owner_principal_id": "principal_01933b5a000070008000000000000001",
  "status": "draft"
}

400

Invalid input

application/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable recovery hint attached to an error response.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”).

string | null

href

Optional absolute or relative URL the caller may invoke directly.

string | null

operation_id

OpenAPI operationId the caller should invoke to recover.

string | null

rel

required

Link relation describing the action (e.g. retry, get-existing, unarchive, retry-later).

string

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example ^generated

{
  "allowed_actions": [
    {
      "hint": "example",
      "href": "example",
      "operation_id": "example",
      "rel": "example"
    }
  ],
  "code": "example",
  "detail": "example",
  "instance": "example",
  "retry_after_seconds": 1,
  "status": 1,
  "title": "example",
  "type": "example"
}

500

Internal server error

application/json

Standard error response.

object

allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable recovery hint attached to an error response.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”).

string | null

href

Optional absolute or relative URL the caller may invoke directly.

string | null

operation_id

OpenAPI operationId the caller should invoke to recover.

string | null

rel

required

Link relation describing the action (e.g. retry, get-existing, unarchive, retry-later).

string

code

Stable, machine-readable error code (snake_case).

string | null

detail

Human-readable explanation specific to this occurrence.

string | null

instance

Request URI for this occurrence.

string | null

retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

status

required

HTTP status code; mirrors the response status line.

integer format: int32

title

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

Example ^generated

{
  "allowed_actions": [
    {
      "hint": "example",
      "href": "example",
      "operation_id": "example",
      "rel": "example"
    }
  ],
  "code": "example",
  "detail": "example",
  "instance": "example",
  "retry_after_seconds": 1,
  "status": 1,
  "title": "example",
  "type": "example"
}

Create a new app

Request Body required

Example

Example

Example

Example

Example

Example

Example

Example

Responses

201

Example

400

Example generated

500

Example generated

Request Body^required

Example ^generated

Example ^generated