> ## Documentation Index > Fetch the complete documentation index at: https://docs.internal.nscale.com/llms.txt > Use this file to discover all available pages before exploring further. # Trigger a topology sync for a site > Declare a Sync Intent on the site's topology-service Region and trigger a sync. Every declaration triggers a sync; a trigger arriving mid-sync queues one follow-up. ## OpenAPI ````yaml /openapi/fleet-manager-openapi.yaml post /api/v1/sites/{id}/topology-sync/ openapi: 3.0.3 info: title: Fleet Manager API version: 1.0.0 description: API for the Nscale Fleet Manager servers: [] security: [] paths: /api/v1/sites/{id}/topology-sync/: post: tags: - Topology Groups summary: Trigger a topology sync for a site description: >- Declare a Sync Intent on the site's topology-service Region and trigger a sync. Every declaration triggers a sync; a trigger arriving mid-sync queues one follow-up. operationId: api_v1_sites_topology_sync_create parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this site. required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/SiteTopologySync' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SiteTopologySync' multipart/form-data: schema: $ref: '#/components/schemas/SiteTopologySync' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/SiteTopologySyncResult' description: '' '400': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication credentials were not provided or are invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: You do not have permission to perform this action. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- The intent id is already declared in this Region with other names, or the intent swaps a node the Region's active topology does not place. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: No topology-service Region is configured for this site. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Topology-service is unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - oauth2: - site:topology_sync - cookieAuth: [] components: schemas: SiteTopologySync: type: object description: >- Request to sync a site's topology-service Region, declaring an intent first. properties: intent: $ref: '#/components/schemas/TopologySyncIntent' required: - intent SiteTopologySyncResult: type: object description: topology-service's answer to the sync trigger. properties: region: type: string status: $ref: '#/components/schemas/TopologySyncTriggerStatusEnum' intent: $ref: '#/components/schemas/DeclaredTopologySyncIntent' request_id: type: string required: - intent - region - request_id - status ErrorResponse: type: object description: >- Uniform error body for every 4xx/5xx response. `detail` is a human-readable message, always present, safe to display to end users. `code` is the machine-readable identifier. `field_errors` lists per-input-field validation messages and is empty for non-field errors (auth, permission, not-found, conflict, server). required: - detail - code - field_errors properties: detail: type: string code: $ref: '#/components/schemas/ErrorCodeEnum' field_errors: type: array items: $ref: '#/components/schemas/FieldError' TopologySyncIntent: type: object description: >- What the first topology-service sync starting after this request should show. properties: id: type: string description: >- Caller-chosen intent id, unique per Region. Re-sending the same id with the same names returns the stored intent without resetting its deadline. expect_nodes_absent: type: array items: type: string description: >- NetBox device names that should leave the Region's topology. A sync that starts after the intent publishes their removal instead of holding it. maxItems: 100 expect_nodes_swapped: type: array items: type: array items: type: string maxItems: 2 minItems: 2 description: >- Pairs of NetBox device names that traded places, as a cabled node swap does. A sync that starts after the intent publishes the exchange instead of holding it; swapping back stays held. maxItems: 100 ttl_seconds: type: integer maximum: 86400 minimum: 1 description: How long the intent can excuse the change, in seconds. required: - id - ttl_seconds TopologySyncTriggerStatusEnum: enum: - started - already_running type: string description: |- * `started` - STARTED * `already_running` - ALREADY_RUNNING DeclaredTopologySyncIntent: type: object description: The stored intent as topology-service reports it. properties: id: type: string state: $ref: '#/components/schemas/TopologySyncIntentStateEnum' expires_at: type: string format: date-time required: - expires_at - id - state ErrorCodeEnum: type: string description: >- Stable machine-readable error identifier. New members may be added within this API version; clients must tolerate unknown values. enum: - error - invalid - parse_error - authentication_failed - not_authenticated - permission_denied - not_found - method_not_allowed - not_acceptable - unsupported_media_type - conflict - enrollment_infrastructure_reference_pending - enrollment_infrastructure_reference_changed - unprocessable_entity - throttled - service_unavailable FieldError: type: object description: One input field's validation messages. required: - field - messages properties: field: type: string description: >- Dotted path to the offending input field, or to the collection row when the whole row is invalid (e.g. `filters.end_date`, `memberships.0.role`, `memberships.0`). messages: type: array minItems: 1 items: type: string TopologySyncIntentStateEnum: enum: - pending - satisfied - expired type: string description: |- * `pending` - PENDING * `satisfied` - SATISFIED * `expired` - EXPIRED securitySchemes: oauth2: type: oauth2 flows: {} cookieAuth: type: apiKey in: cookie name: sessionid ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.