canonical: https://jentic.com/apis/amazonaws.com/amazon-sagemaker-edge-manager

# AWS Amazon SageMaker Edge Manager

Jentic publishes the only available OpenAPI specification for Amazon SageMaker Edge Manager, keeping it validated and agent-ready. SageMaker Edge Manager is the dataplane for active edge agents - it lets registered devices fetch their assigned model deployments, send periodic heartbeats with telemetry, and report registration metadata back to the SageMaker control plane. This API is consumed by the Edge Manager agent on each device, not typically called directly by application code, but it is the protocol that drives over-the-air model updates on edge fleets. Note that AWS announced SageMaker Edge Manager is on a deprecation path, so check current status before adopting.

## For AI agents

The dataplane that registered edge devices use to fetch model deployments and send heartbeats back to SageMaker.

## Scope

Does not register devices, create deployment plans, or run inference - use as the device-side dataplane for fetching assigned deployments, reading registration metadata, and sending heartbeats only.

## Capabilities

- Fetch the model deployment assigned to a registered edge device with GetDeployments
- Retrieve a device's registration metadata and assigned device fleet with GetDeviceRegistration
- Send a periodic heartbeat with model status, agent metrics, and metadata using SendHeartbeat
- Track per-device deployment progress through heartbeat reporting back to the control plane
- Operate as the dataplane protocol consumed by the SageMaker Edge Manager device agent

## Use cases

### Edge device polling for model updates

The SageMaker Edge Manager device agent polls GetDeployments on a regular interval to learn when a new model version has been assigned to its fleet. When a new deployment is returned, the agent downloads the model artifact from the indicated S3 location and swaps it into the local inference runtime. This API is the contract between the device-side agent and the cloud-side deployment plan.

Example prompt: Call GetDeployments for DeviceName='device-042' in DeviceFleetName='warehouse-cameras' and, on a non-empty response, download the model from the returned S3 URI.

### Device telemetry and heartbeat reporting

Each edge device sends SendHeartbeat at a regular interval with the current AgentVersion, model statuses, and any custom metrics. The control plane uses these heartbeats to surface device health in the SageMaker console - last-seen timestamps, stale models, and degraded agents. Without heartbeats, the cloud has no visibility into whether the deployment landed.

Example prompt: Call SendHeartbeat from device-042 with AgentVersion='1.20', ModelMetadata listing the currently loaded model and its status as RUNNING.

### Device registration verification

The Edge Manager agent calls GetDeviceRegistration on startup to confirm the device is registered, retrieve its fleet assignment, and load the IoT credentials needed for downstream operations. This is the bootstrap step before deployment polling can succeed - an unregistered device gets a clear error rather than silently failing.

Example prompt: Call GetDeviceRegistration for DeviceName='device-042' in DeviceFleetName='warehouse-cameras' to confirm the device is registered and receive the IoT certificate ARN.

### Agent-driven edge fleet diagnostics through Jentic

AI agents that diagnose edge fleet issues use Jentic to call GetDeployments and GetDeviceRegistration on behalf of operators without holding raw AWS credentials. Jentic stores keys in your Jentic One instance, signs each request with SigV4, and returns the structured response - letting the agent verify whether a missing deployment is a registration problem, a deployment-plan problem, or a device-side polling problem.

Example prompt: Search Jentic for 'fetch a SageMaker Edge deployment', call GetDeployments for the suspected device, and on empty response call GetDeviceRegistration to confirm it is registered to the right fleet.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /GetDeployments | Fetch the model deployment assigned to a device |
| POST | /GetDeviceRegistration | Retrieve a device's registration metadata |
| POST | /SendHeartbeat | Send a periodic heartbeat with model and agent status |

## Key resources

- **Deployment** — A model deployment assigned to a device fleet, identified by deployment name and S3 model URI
- **DeviceRegistration** — The per-device record including fleet, IoT certificate, and last-seen status
- **Heartbeat** — Periodic device-side report of agent version, model status, and custom metrics
- **DeviceFleet** — A logical grouping of edge devices that share a deployment plan

## Why Jentic

- **Setup:** Wiring Amazon SageMaker Edge Manager by hand means implementing AWS SigV4 signing, resolving the edge.sagemaker regional host, and modelling the device-side heartbeat and deployment-poll payloads the Edge agent normally sends. Through Jentic you install once, import Amazon SageMaker Edge Manager from the API Directory, store your AWS access key and secret once, and your agent calls it.
- **Permission scoping:** Edge Manager carries DeviceName and DeviceFleetName in the request body of POST operations rather than in the URL path, so scope your agent to the operations it needs: for example allow GetDeployments and GetDeviceRegistration for read-only fleet diagnostics. You choose the operations it may call, so SendHeartbeat writes are not included unless you add them.
- **Credential handling:** Your AWS access key and secret are stored once, encrypted, by your own Jentic One instance and each request is signed with SigV4 at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'fetch a SageMaker Edge deployment' or 'confirm an edge device is registered', and Jentic returns the matching operation like GetDeployments or GetDeviceRegistration with its input schema so the agent calls it without reading the AWS reference.

## Related APIs

- **Amazon SageMaker** — The control plane that registers devices, creates fleets, and authors deployment plans
- **AWS IoT Greengrass** — Component-based edge runtime that AWS positions as the longer-term home for edge ML deployments
- **AWS IoT Core (data)** — MQTT and HTTPS dataplane for IoT messaging that often coexists with Edge Manager telemetry

## FAQ

### Why is there no official OpenAPI spec for Amazon SageMaker Edge Manager?

AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Amazon SageMaker Edge Manager via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Amazon SageMaker Edge Manager API use?

Edge Manager Runtime uses AWS Signature Version 4 HMAC signing with an access key ID and secret access key, optionally with a session token. On real edge devices, the SageMaker Edge Manager agent typically uses IoT certificates issued during device registration to obtain temporary credentials. Through Jentic, your AWS credentials sit in your Jentic One instance and Jentic signs each request server-side.

### Can I register or deploy to devices with the Amazon SageMaker Edge Manager API?

No - registration, fleet creation, and deployment planning live on the SageMaker control plane (RegisterDevices, CreateDeviceFleet, CreateEdgeDeploymentPlan). This dataplane API is what registered devices call at runtime to fetch their assigned deployment and send heartbeats.

### What are the rate limits for the Amazon SageMaker Edge Manager API?

AWS does not publish a fixed RPS in the spec; standard AWS API throttling applies and the service returns ThrottlingException on overage. The Edge Manager agent on devices applies sensible default poll and heartbeat intervals (typically tens of seconds to minutes) to stay well within service quotas.

### How do I fetch the assigned deployment for a device with Amazon SageMaker Edge Manager through Jentic?

Search Jentic for 'fetch a SageMaker Edge deployment', load GetDeployments, and call POST /GetDeployments with DeviceName and DeviceFleetName. The response contains the assigned model name, version, and S3 URI to download the artifact. Install with pip install jentic.

### Is Amazon SageMaker Edge Manager still actively supported?

AWS announced SageMaker Edge Manager is on a deprecation path, with new feature work focused on alternatives such as IoT Greengrass component-based ML deployments. The dataplane endpoints documented here continue to function for existing deployments, but check current AWS service status before building new edge fleets on Edge Manager.

### Can I limit what my agent is allowed to do with the AWS SageMaker Edge Manager API?

Yes. Because you run Jentic One self-hosted, your own rules decide which of the three Edge Manager operations the agent can call and which AWS credentials it may use. For read-only fleet diagnostics you can allow only GetDeployments and GetDeviceRegistration and leave out SendHeartbeat, so the agent can fetch a device's assigned deployment and confirm its registration without writing heartbeat telemetry. Since DeviceName and DeviceFleetName travel in the request body rather than the URL path, scoping is done at the operation level you configure.