API Reference & Configuration

Every API endpoint the platform exposes, plus deploy-time configuration variables, Lambda environment variables, and SSM parameters.

← Back to README

API Endpoints

Workflow Management

Deployment

Deployment targets

Registration accepts only a full target-Region customer-managed KMS key ARN. The backend verifies account, Region, enabled state, symmetric ENCRYPT_DECRYPT usage, and the default key policy's target-account and scoped bedrock-agentcore.amazonaws.com grants. It reads metadata and policy only—no key material. Target rows created before this field existed remain visible to admins but are not deployable until re-registered. New deployment and version rows freeze the exact ARN; promotion refuses missing or disagreeing authority.

CloudFormation export naming and tags

POST /api/generate-cfn-template accepts these optional governance fields in the normal DeployRequest body:

{
  "resourceTags": {
    "CostCentre": "ECB-42"
  },
  "tagProfile": "regulated-production",
  "namingProfile": {
    "prefix": "ecb",
    "resourceNames": {
      "gateway": "{prefix}-{deployment}-gw",
      "runtime": "{prefix}_{deployment}_agent"
    }
  }
}

tagProfile is resolved server-side and merged with resourceTags; the emitted template contains concrete tags, not a platform profile reference. namingProfile is CloudFormation-only: /api/deploy and /api/export-python return 400 if it is sent, preventing a naming request from being silently discarded.

The prefix must match ^[a-z][a-z0-9]{0,11}$. Override templates use {prefix} and {deployment}; component families require {component}, while stack-unique domains, vector buckets, and IAM roles require {suffix}. The complete family list and coupling behavior are documented in Deployment Internals.

With a profile, DeploymentName is limited to 20 lowercase alphanumeric characters and long user-controlled components receive a deterministic hash suffix before they can exceed an AWS name limit. Without a profile, the legacy physical-name formulas remain unchanged, but each exported template publishes a component-specific DeploymentName.MaxLength derived from the names it actually emits. This prevents a value that passes parameter validation from failing later at an AWS service boundary.

Legacy explicit IAM role names include the CloudFormation stack name, which is a separate input from DeploymentName. The generated deploy.sh automatically uses CloudFormation-generated role names when a stack name exceeds the emitted safe limit (currently 47 characters), and fails early if explicit names are forced. A direct CloudFormation or Terraform consumer must set UseExplicitRoleNames=false for a stack name beyond the limit stated in that bundle.

Full component templates can exceed CloudFormation's 51,200-byte inline body limit. The generated script stages template.yaml with --s3-bucket; Terraform consumers must upload it and use aws_cloudformation_stack.template_url, not template_body = file(...). They must also stage the ZIPs in the download and pass the corresponding artifact keys and digests. The generated README contains the per-bundle parameter table and a minimal HCL wrapper.

Live-deploy credential and customer-resource authorization

POST /api/deploy treats every caller-supplied AWS ARN or resource ID as inventory, not as permission to use that resource.

• Model-provider and per-canvas OTEL source secrets must be complete Secrets Manager ARNs in their approved namespace and carry this platform stack's exact ownership tag plus the authenticated caller binding. The platform-default OTEL source is read only from operator-controlled configuration. In both cases the raw value is copied into a new agentcore-connector/* secret in the selected deployment account and region. Only that deployment-bound copy is placed in Step Functions input or granted to the runtime; the long-lived source is not granted to the runtime or deleted with the deployment.
• A customer-owned resource used by a Knowledge Base must opt in with AgentCoreFlowsAccess=allow. This applies to an existing Knowledge Base, S3 data bucket, S3 Vectors bucket/index, OpenSearch Serverless collection/index, Aurora cluster, transformation Lambda, KMS key, and Knowledge Base credential source secret. Account, region, and ARN resource family are also checked where the service exposes them.
• OwnerSubHash is optional. When present, it must equal the first 32 hex characters of SHA-256 over the intended caller's Cognito sub; omitting it makes the opt-in intentionally shared among authenticated users of this platform stack.
• Customer Knowledge Base credential values are copied into the same deployment-bound target-secret lifecycle before Step Functions starts. The customer source ARN never reaches the Bedrock service role.
• Resources created by the platform use a stricter proof: exact stack, deployment, and caller tags. A same-name conflict that cannot prove that binding aborts rather than being adopted or modified.

This contract is for the platform's live Step Functions deployment path. A downloaded CloudFormation bundle is a customer-owned artifact and is governed by the IAM roles and parameters in the account where the customer deploys it.

Flows

Observability

Platform configuration (feature flags)

Operators flip a flag with aws ssm put-parameter --name /agentcore-workflow/<env>/platform-features --type String --overwrite --value '{"platformFlagsCanary": true}'; it lands within the TTL, no redeploy. Flagged-off backend routes are declared with Depends(require_feature("<flag>")) placed before require_scopes, and the UI hides the surface with useFeatureFlags() / <FeatureGate>; the backend 404 is the control, the UI is a courtesy. | POST | /api/observability/credentials | Stores OTLP auth credentials in Secrets Manager and returns the secret ARN. |

Versioning & Slots

Evaluation, Cost & Observability (runtime-scoped)

Invocation authorization (owner/agent/tag scoped)

Production-mediated invocation operations require at least one applicable definition. A bounded MCP handshake and tool call consume one operation. Owner, agent, and matching tag limits are condition-checked and reserved in one DynamoDB transaction. Exhausted capacity returns 429 with Retry-After: 3600; unavailable storage returns 503 before dispatch. The cost response's owner_budget includes authorized, reserved, committed, remaining_authorization, reservation_unit, authorization_scope="platform-mediated-invocation-operation", and is_actual_cost_cap=false. Those USD-denominated values authorize dispatches; they are not reconciled AWS charges or an account-level spending guarantee.

Triggers (runtime-scoped)

Cron, EventBridge, and S3 triggers create stack-tagged EventBridge rules that send version-pinned invocation envelopes through the platform's durable SQS queue and DLQ. Webhooks use a static HMAC-authenticated route. A first delivery returns 202 with duplicate=false after SQS acceptance; the same valid delivery ID returns 202 with duplicate=true without another enqueue. The marker binds the ID to the request-body SHA-256; reusing it for different authenticated bytes returns 409. A concurrent in-flight request returns 409 plus Retry-After: 1; a crashed ingress lease can be taken over after 60 seconds. Queued ingress markers and completed worker markers expire after seven days, and worker-side transactional dedup remains the safety net for an ambiguous SQS send. Optional result callbacks are HTTPS-only, network filtered, DNS-rebinding resistant, and do not follow redirects. S3 triggers require EventBridge notifications to be enabled on each source bucket.

Agent Registry

AWS Agent Registry federation (opt-in)

Federates deployed agents into the AWS Agent Registry — a GA AWS service in its own right (it is no longer part of bedrock-agentcore). Requires the backend to run boto3 >= 1.43.66, the first release carrying the agent-registry service models, and the agent-registry:* IAM actions.

sdk_supported: false means this deployment's boto3 predates the GA API, so no agent-registry client can be built — a redeploy, not a configuration change. POST returns 400 naming the SDK in that case rather than blaming the registry_id.

LiteLLM as the catalog backend (opt-in)

Makes a LiteLLM proxy the authoritative catalog in place of the internal DynamoDB one. Additive: the default backend is dynamodb and nothing above changes until an admin activates this. See Registry & RBAC.

activate: false saves and probes the config without switching the catalog over, so reachability can be tested first. verified: false means the control plane could not probe the proxy — normal for a VPC-private LiteLLM, since the control plane has no VPC egress, and not an error.

Because LiteLLM has no write API for MCP server records, entries projected from LiteLLM are read-only: publish, update, delete, approve, reject and clone return 501 naming LiteLLM rather than silently accepting a write that would then diverge. Entries published from a canvas live in the platform sidecar and stay fully mutable — the limit is per entry, not per operation. capabilities (including read_only_sources) on GET /litellm-config is the machine-readable form of that. The pre-deploy governance gate stays fail-closed: if the catalog cannot be read, deploys referencing an integration return 503.

Prompt Library

HITL, Connectors, Workspaces & GitOps

JIT permission requests

An active approval lease makes concurrent approve/reject return 409. Definitive IAM refusal returns the row to PENDING; an ambiguous IAM outcome returns 502 with Retry-After: 300 and leaves APPLYING, preventing a false rejection until an admin reclaims and retries the same deterministic policy. Gateway/target/Cedar control-plane mutation actions are refused even when hidden behind an action wildcard.

NL Agent Generation & Code Export

Configuration

Deploy-time variables consumed by ./scripts/deploy.sh and passed as CDK context parameters to the infrastructure stack:

Environment Variables (Lambda)

SSM Parameters

Application configuration is stored under /agentcore-workflow/{env}/ in SSM Parameter Store: