Skip to main content
POST
Create A2A agent

Restrictions

Usage

  • instructions is required; a deprecated description field is still accepted for legacy clients and, if both are sent, must exactly match instructions.
  • card_url must be an absolute http/https URL with a non-empty host (reachability is enforced by the execution environment, not here); auth_type accepts only none, api_key, or bearer.
  • environment_kind accepts only empty (automatic) or byoc; cloud is rejected. byoc requires environment_id, and the runner must be visible to the caller.
  • Creating into a team (team_id > 0) requires the caller to actually belong to that team; only the account owner/admin may create at account scope (team_id=0).
  • Every call is recorded in the account audit log.

Authorizations

app_key
string
query
required

App key issued from the Flashduty console. Required on every public API call. Keep it secret — it grants the same access as the owning account.

Body

application/json

Registration parameters for a new A2A agent.

agent_name
string
required

Agent display name.

Maximum string length: 128
instructions
string
required

Natural-language instructions for the remote agent. Required — a deprecated description field is still accepted for legacy clients and, if both are sent, must exactly match instructions.

Maximum string length: 2000
card_url
string
required

URL of the remote agent card. Must be an absolute http or https URL with a non-empty host; reachability is enforced by the execution environment, not at creation time.

auth_type
string

Authentication type for reaching the remote agent: none, api_key, or bearer.

auth_config
object

Authentication config key-values, e.g. the API key or bearer token. Values for sensitive keys (api_key, token, client_secret) are masked back in responses.

streaming
boolean

Whether the remote agent supports streaming.

team_id
integer<int64>

Team scope: 0 = account-wide; >0 = team. Creating at account scope requires the owner/admin role; creating into a team requires actual membership in that team.

environment_kind
enum<string>

Execution environment binding. Omit or send empty for automatic routing; byoc pins the agent to a specific runner given by environment_id. cloud is not accepted — configured A2A agents need a persistent runner, not a disposable cloud sandbox.

Available options:
,
byoc
environment_id
string

BYOC runner ID. Required when environment_kind=byoc; the runner must belong to the account or a team the caller belongs to.

auth_mode
string

Authentication mode: shared (default) shares one credential across all users; per_user_secret requires secret_schema.header_name; per_user_oauth runs per-user OAuth.

secret_schema
string

JSON-encoded secret schema, e.g. {"header_name":"X-Api-Key"}; required when auth_mode=per_user_secret.

oauth_metadata
string

JSON-encoded OAuth metadata; populated by the OAuth discovery flow for per_user_oauth mode.

allow_insecure_oauth_http
boolean

Allow non-loopback HTTP OAuth discovery/metadata endpoints for this agent instead of requiring HTTPS. Defaults to false.

allow_insecure_tls_skip_verify
boolean

Skip TLS certificate verification when connecting to this agent's endpoint (self-signed/private certs). Defaults to false.

Response

Success

Standard response envelope used by every Flashduty public API. On success data contains the endpoint-specific payload and error is absent. On failure error is present and data is absent. request_id is always present and is also mirrored in the Flashcat-Request-Id response header.

request_id
string
required

Unique ID for this request. Mirrored in the Flashcat-Request-Id header. Include it when reporting issues.

Example:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

error
object

Error payload inside the response envelope. Present only on non-2xx responses.

data
object

Result of registering an A2A agent.