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.
  • environments restricts where the agent can run: a list of cloud and/or BYOC runner environment IDs; omitted or empty means all environments, and each 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: a Markdown document with optional summary frontmatter and a non-empty body, at most 50 KiB (51200 bytes). Required — a deprecated description field is still accepted for legacy clients and, if both are sent, must exactly match instructions.

Maximum string length: 51200
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
enum<string>

Authentication type for reaching the remote agent: none (default when omitted), api_key, or bearer.

Available options:
none,
api_key,
bearer
auth_config
object

Authentication config key-values, e.g. the API key or bearer token. Values under credential-looking keys (name containing KEY, SECRET, TOKEN, PASSWORD, etc.) 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.

environments
string[]

Execution environments this agent is callable from: cloud and/or BYOC runner environment IDs. Omitted or empty means all environments.

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.