Add an api_endpoint channel (returns plaintext key once).

Path Parameters

app_id

required

string

App ID

Request Body^required

application/json

Request body for the add_api_endpoint_channel_http operation.

object

auth

One of:

null
object

null

Optional endpoint auth. Example shape is defined on AppEndpointAuthConfig.

object

mode

required

App-published endpoint authentication mode.

Stored inline on app_channels.channel_config.auth so users can protect a single App/channel without first creating org-level identity-provider state.

string

Allowed values: anonymous shared_secret api_key google_oidc oidc o_auth2_introspection http_basic mtls

provider

One of:

null
object

null

One of:

object

allowed_domains

Array<string>

client_id

required

string

type

required

string

Allowed values: google_oidc

object

allowed_values

Array<string>

header_name

required

string

proxy_secret

Shared secret the trusted proxy includes in proxy_secret_header. Write-only: redacted in GET responses. See TM-AUTH-021.

string | null

proxy_secret_header

Header the trusted reverse proxy uses to prove its identity. Required. Configs without this field fail closed at verification time.

string | null

type

required

string

Allowed values: mtls

requirements

Claim and credential requirements common to App endpoint auth providers.

object

audiences

JWT aud values to require on inbound tokens. Empty list disables audience checking.

Array<string>

claims

Arbitrary claim equality predicates. Empty map disables claim filtering.

object

key

additional properties

domains

Allowlist of email/identifier domains. Empty list disables domain filtering.

Array<string>

groups

Allowlist of group memberships (from groups claim). Empty list disables group filtering.

Array<string>

scopes

OAuth scope strings to require (space-delimited per scope entry). Empty list disables scope checking.

Array<string>

subjects

Allowlist of sub claim values. Empty list disables subject filtering.

Array<string>

Example

{
  "mode": "api_key",
  "requirements": {
    "audiences": [
      "everruns-api"
    ],
    "scopes": [
      "app:invoke"
    ]
  }
}

enabled

Whether this resource is enabled.

boolean | null

Example

true

session_mode

How invocations route into sessions (shared_session to reuse one durable session, or session_per_invocation for a fresh session).

string

Allowed values: shared_session session_per_invocation

Example

shared_session

201

Api_endpoint channel created. The api_key field is the plaintext key returned exactly once and never recoverable later.

application/json

Output of [AddApiEndpointChannelCmd] — includes the plaintext API key (returned once, never persisted) plus the resulting [AppChannel].

object

api_key

required

Plaintext API key. Persist this — it cannot be recovered later.

string

channel

required

The created api_endpoint channel.

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 api_endpoint

created_at

required

Timestamp when this channel was created.

string format: date-time

enabled

Whether this channel is enabled.

boolean

id

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

Example

{
  "channel": {
    "channel_type": "slack",
    "id": "appchan_01933b5a000070008000000000000001"
  }
}

400

Validation error

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 link describing a follow-up the caller can take. Used in two contexts:

Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string

schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

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

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

401

Unauthorized

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 link describing a follow-up the caller can take. Used in two contexts:

Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string

schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

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

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

403

Forbidden

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 link describing a follow-up the caller can take. Used in two contexts:

Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string

schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

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

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

404

App not found

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 link describing a follow-up the caller can take. Used in two contexts:

Error recovery — ErrorResponse.allowed_actions carries rels like retry, retry-later, unarchive, get-existing so the agent knows the right next call after a 4xx/429.
Entity hypermedia — WithUrls<T>.allowed_actions carries state-aware rels like cancel, events, self, update on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed rel vocabulary documented in specs/api-conventions.md distinguishes them.

object

hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

href

Absolute (preferred) or relative URL the caller may invoke directly. Always present on entity hypermedia actions (WithUrls<T>.allowed_actions); optional on error-recovery actions (ErrorResponse.allowed_actions) where the matching operation_id is enough and the URI is implicit from the failed call.

string | null

method

HTTP method to use against href. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

operation_id

OpenAPI operationId the caller should invoke. Lets an MCP client resolve the call without parsing href.

string | null

rel

required

Link relation describing the action. Closed vocabulary documented in specs/api-conventions.md — examples: self, cancel, pause, resume, events, retry, retry-later, unarchive, get-existing, delete, update.

string

schema_ref

OpenAPI $ref to the request-body schema, when the action takes one (e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

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

{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}

Add an api_endpoint channel (returns plaintext key once).

Parameters

Path Parameters

Request Body required

Example

Example

Example

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

Request Body^required