Link the caller's Atlas project for egress sync

PUT /api/v1/projects/{id}/atlas-link

Links a project to an Atlas project for egress sync. Requires the project-owner role. When the platform enforces the Atlas access proof (the default), the request must carry an X-Atlas-Service-Account-Token header whose service account can read the Atlas project, and the Atlas project must belong to the organization's Atlas organization. The response reports sync status only — Atlas cluster topology (hosts/IPs) and raw sync errors are omitted.

Headers

X-Atlas-Service-Account-Token string

Short-lived Atlas service-account access token used as a group-access proof (never the SA client secret); required when the platform enforces the Atlas access proof, which is the default

Path parameters

id string Required

Project ID

application/json

Body Required

Atlas project link

environment string
project_id string

Responses

406

application/json

application/json application/vnd.agent-engine-2026-09-20-preview+json

Unsupported or malformed API version, an operation unavailable in the selected published contract, or an unacceptable representation (including unsupported media-type parameters or excluded SSE). Existing authentication, authorization, and rate-limit failures take precedence.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Optional validation details defined by the standard error schema; API negotiation errors do not emit this field.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Fields with validation failures.
  
  Hide fields attributes Show fields attributes object
  
  A field and its validation failure.
  
  description string Required
  
  Human-readable validation failure.
  
  field string Required
  
  Name or path of the invalid request field.
- detail string Required
  
  Human-readable error details.
- error integer Required
  
  HTTP status code.
- errorCode string Required
  
  Machine-readable error code.
- parameters array[string]
  
  Request parameter names associated with the error; omitted when none apply.
- reason string Required
  
  HTTP status reason phrase.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Optional validation details defined by the standard error schema; API negotiation errors do not emit this field.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Fields with validation failures.
  
  Hide fields attributes Show fields attributes object
  
  A field and its validation failure.
  
  description string Required
  
  Human-readable validation failure.
  
  field string Required
  
  Name or path of the invalid request field.
- detail string Required
  
  Human-readable error details.
- error integer Required
  
  HTTP status code.
- errorCode string Required
  
  Machine-readable error code.
- parameters array[string]
  
  Request parameter names associated with the error; omitted when none apply.
- reason string Required
  
  HTTP status reason phrase.
200

application/vnd.agent-engine-2026-09-20-preview+json

application/vnd.agent-engine-2026-09-20-preview+json application/json

OK
Hide response attributes Show response attributes object
- atlas_project object
  
  Hide atlas_project attributes Show atlas_project attributes object
  
  environment string
  
  project_id string
- egress_sync object
  
  Hide egress_sync attributes Show egress_sync attributes object
  
  cluster_count integer
  
  Number of clusters in the last successful stored snapshot. Zero means Atlas returned none (often paused or empty). Customer atlas-link responses include this count and omit cluster hosts/IPs.
  
  clusters array[object]
  
  Hide clusters attributes Show clusters attributes object
  
  hosts array[string]
  
  name string
  
  publicIpv4Addresses array[string]
  
  type string
  
  uniqueId string
  
  clusters_differ boolean
  
  last_success_at string
  
  last_sync_at string
  
  live_clusters array[object]
  
  Hide live_clusters attributes Show live_clusters attributes object
  
  hosts array[string]
  
  name string
  
  publicIpv4Addresses array[string]
  
  type string
  
  uniqueId string
  
  live_fetch_error string
  
  sync_error string
  
  sync_status string
- name string
- org_id string
- project_id string
Hide response attributes Show response attributes object
- atlas_project object
  
  Hide atlas_project attributes Show atlas_project attributes object
  
  environment string
  
  project_id string
- egress_sync object
  
  Hide egress_sync attributes Show egress_sync attributes object
  
  cluster_count integer
  
  Number of clusters in the last successful stored snapshot. Zero means Atlas returned none (often paused or empty). Customer atlas-link responses include this count and omit cluster hosts/IPs.
  
  clusters array[object]
  
  Hide clusters attributes Show clusters attributes object
  
  hosts array[string]
  
  name string
  
  publicIpv4Addresses array[string]
  
  type string
  
  uniqueId string
  
  clusters_differ boolean
  
  last_success_at string
  
  last_sync_at string
  
  live_clusters array[object]
  
  Hide live_clusters attributes Show live_clusters attributes object
  
  hosts array[string]
  
  name string
  
  publicIpv4Addresses array[string]
  
  type string
  
  uniqueId string
  
  live_fetch_error string
  
  sync_error string
  
  sync_status string
- name string
- org_id string
- project_id string
400

application/json

application/json application/vnd.agent-engine-2026-09-20-preview+json

Bad Request
Hide response attributes Show response attributes object
- code string
- error string
- success boolean
Hide response attributes Show response attributes object
- code string
- error string
- success boolean
403

application/json

application/json application/vnd.agent-engine-2026-09-20-preview+json

Forbidden
Hide response attributes Show response attributes object
- code string
- error string
- success boolean
Hide response attributes Show response attributes object
- code string
- error string
- success boolean
404

application/json

application/json application/vnd.agent-engine-2026-09-20-preview+json

Not Found
Hide response attributes Show response attributes object
- code string
- error string
- success boolean
Hide response attributes Show response attributes object
- code string
- error string
- success boolean
500

application/json

application/json application/vnd.agent-engine-2026-09-20-preview+json

Internal Server Error
Hide response attributes Show response attributes object
- code string
- error string
- success boolean
Hide response attributes Show response attributes object
- code string
- error string
- success boolean
502

application/json

application/json application/vnd.agent-engine-2026-09-20-preview+json

Bad Gateway
Hide response attributes Show response attributes object
- code string
- error string
- success boolean
Hide response attributes Show response attributes object
- code string
- error string
- success boolean

PUT /api/v1/projects/{id}/atlas-link

curl \
 --request PUT 'https://agentengine.mongodb.com/api/v1/projects/{id}/atlas-link' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "X-Atlas-Service-Account-Token: string" \
 --data '{
  "environment": "string",
  "project_id": "string"
}'

Request examples

# Headers
X-Atlas-Service-Account-Token: string

# Payload
{
  "environment": "string",
  "project_id": "string"
}

Response examples (406)

{
  "detail": "This operation is not available in API version 2026-09-20-preview.",
  "error": 406,
  "errorCode": "OPERATION_NOT_IN_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}

{
  "detail": "This operation supports text/event-stream, which the Accept header excludes. Remove unsupported media-type parameters or accept this type with a positive q value.",
  "error": 406,
  "errorCode": "UNACCEPTABLE_MEDIA_TYPE",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}

{
  "detail": "The requested API version is not supported. Supported versions: 2026-09-20-preview.",
  "error": 406,
  "errorCode": "UNSUPPORTED_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}

Response examples (406)

{
  "detail": "This operation is not available in API version 2026-09-20-preview.",
  "error": 406,
  "errorCode": "OPERATION_NOT_IN_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}

Response examples (200)

{
  "atlas_project": {
    "environment": "string",
    "project_id": "string"
  },
  "egress_sync": {
    "cluster_count": 42,
    "clusters": [
      {
        "hosts": [
          "string"
        ],
        "name": "string",
        "publicIpv4Addresses": [
          "string"
        ],
        "type": "string",
        "uniqueId": "string"
      }
    ],
    "clusters_differ": true,
    "last_success_at": "string",
    "last_sync_at": "string",
    "live_clusters": [
      {
        "hosts": [
          "string"
        ],
        "name": "string",
        "publicIpv4Addresses": [
          "string"
        ],
        "type": "string",
        "uniqueId": "string"
      }
    ],
    "live_fetch_error": "string",
    "sync_error": "string",
    "sync_status": "string"
  },
  "name": "string",
  "org_id": "string",
  "project_id": "string"
}

Response examples (200)

{
  "atlas_project": {
    "environment": "string",
    "project_id": "string"
  },
  "egress_sync": {
    "cluster_count": 42,
    "clusters": [
      {
        "hosts": [
          "string"
        ],
        "name": "string",
        "publicIpv4Addresses": [
          "string"
        ],
        "type": "string",
        "uniqueId": "string"
      }
    ],
    "clusters_differ": true,
    "last_success_at": "string",
    "last_sync_at": "string",
    "live_clusters": [
      {
        "hosts": [
          "string"
        ],
        "name": "string",
        "publicIpv4Addresses": [
          "string"
        ],
        "type": "string",
        "uniqueId": "string"
      }
    ],
    "live_fetch_error": "string",
    "sync_error": "string",
    "sync_status": "string"
  },
  "name": "string",
  "org_id": "string",
  "project_id": "string"
}

Response examples (400)

{
  "code": "string",
  "error": "string",
  "success": true
}

Response examples (400)

{
  "code": "string",
  "error": "string",
  "success": true
}

Response examples (403)

{
  "code": "string",
  "error": "string",
  "success": true
}

Response examples (403)

{
  "code": "string",
  "error": "string",
  "success": true
}

Response examples (404)

{
  "code": "string",
  "error": "string",
  "success": true
}

Response examples (404)

{
  "code": "string",
  "error": "string",
  "success": true
}

Response examples (500)

{
  "code": "string",
  "error": "string",
  "success": true
}

Response examples (500)

{
  "code": "string",
  "error": "string",
  "success": true
}

Response examples (502)

{
  "code": "string",
  "error": "string",
  "success": true
}

Response examples (502)

{
  "code": "string",
  "error": "string",
  "success": true
}