Pull Remote Data

Initiate a remote pull operation to synchronize data from a remote source. This operation is asynchronous and returns a task identifier that can be used to track the operation status. The pull operation retrieves and synchronizes remote configurations, rules, workflows, or other entities into your workspace branch.

Endpoint

POST /dev/remote/pull

Try it here

URL Format

The endpoint does not require any path or query parameters. All configuration is handled via request headers.

Example: POST /dev/remote/pull

Authentication

All requests require authentication via headers. The endpoint requires both the Nected-API-Key and Nected-Branch headers for proper authentication and branch context.

Required Headers:

• Nected-API-Key (string, required): Your Nected API key for authentication

• Nected-Branch (string, required): Branch name for the operation (e.g., "staging", "main", "development")

---

Request

This endpoint does not require a request body. All configuration and context are provided through request headers.

Request Headers

Header	Type	Required	Description
Nected-API-Key	string	Yes	Your Nected API key for authentication
Nected-Branch	string	Yes	Branch name for the pull operation
accept	string	No	Response content type (default: application/json)
Content-Type	string	No	Request content type (not required for empty body)

Request Body

This endpoint does not require a request body. Send an empty body or omit the body entirely.

---

Response

Status Code: 200 OK

Successfully initiated the remote pull operation. The response contains a task identifier and task state for tracking the asynchronous operation. The pull operation will continue processing in the background, and you can use the taskId to query the status of the operation.

{
  "code": "",
  "data": {
    "taskId": "string",
    "taskState": "string"
  },
  "message": "",
  "pageNo": 0,
  "pageSize": 0,
  "totalCount": 0,
  "totalPages": 0
}

Response Fields

• code: Response code (empty string indicates success)

• data: Object containing task information

  • taskId: Unique identifier for the pull operation task. Use this ID to track the operation status.

  • taskState: Current state of the task. Possible values include:

    • "pending": Task is queued and waiting to start

    • "in-progress": Task is currently executing

    • "completed": Task has finished successfully

    • "failed": Task encountered an error and failed

• message: Human-readable message (empty string for success)

• pageNo: Page number (always 0 for this endpoint as it's not paginated)

• pageSize: Items per page (always 0 for this endpoint)

• totalCount: Total count (always 0 for this endpoint)

• totalPages: Total pages (always 0 for this endpoint)

---

Error Responses

400 Bad Request

Invalid request or validation error. This may occur if:

• The Nected-Branch header contains an invalid branch name

• The branch does not exist in the workspace

• The request format is incorrect

{
  "code": "",
  "data": {},
  "message": "",
  "pageNo": 0,
  "pageSize": 0,
  "totalCount": 0,
  "totalPages": 0
}

401 Unauthorized

Authentication failed. The Nected-API-Key header is missing, empty, or invalid.

{
  "data": null,
  "code": "nected_api_key_empty",
  "message": "Nected-API-Key is empty, please provide nected-api-key"
}

Common causes:

• Missing Nected-API-Key header

• Invalid or expired API key

• API key not associated with the workspace

500 Internal Server Error

An unexpected server error occurred while processing the request. This may indicate a temporary service issue.

{
  "code": "",
  "data": {},
  "message": "",
  "pageNo": 0,
  "pageSize": 0,
  "totalCount": 0,
  "totalPages": 0
}

Recommended actions:

• Retry the request after a short delay

• Verify that the service is operational

• Contact support if the error persists

---

Data Models

Task Response Object

The task response object contains information about the asynchronous pull operation.

Field	Type	Description
taskId	string	Unique identifier for the pull operation task. Use this to query task status.
taskState	string	Current state of the task. Possible values: "pending", "in-progress", "completed", "failed"

Standard Response Object

All endpoints return a consistent response structure.

Field	Type	Description
code	string	Response code (empty string for success, error code for failures)
data	object	Response data containing task information or error details
message	string	Human-readable message (empty string for success, error message for failures)
pageNo	integer	Current page number (always 0 for non-paginated endpoints)
pageSize	integer	Number of items per page (always 0 for non-paginated endpoints)
totalCount	integer	Total number of items (always 0 for non-paginated endpoints)
totalPages	integer	Total number of pages (always 0 for non-paginated endpoints)

---

Example Usage

cURL

curl -X POST "{{NECTED_BASE_URL}}/dev/remote/pull" \
  -H "accept: application/json" \
  -H "Nected-API-Key: <YOUR_API_KEY>" \
  -H "Nected-Branch: staging" \
  -d ''

JavaScript (fetch)

const response = await fetch("{{NECTED_BASE_URL}}/dev/remote/pull", {
  method: "POST",
  headers: {
    "accept": "application/json",
    "Nected-API-Key": "<YOUR_API_KEY>",
    "Nected-Branch": "staging"
  }
});

const data = await response.json();

if (response.ok) {
  console.log("Task ID:", data.data.taskId);
  console.log("Task State:", data.data.taskState);
} else {
  console.error("Error:", data.message);
}

Python (requests)

import requests

url = "{{NECTED_BASE_URL}}/dev/remote/pull"
headers = {
    "accept": "application/json",
    "Nected-API-Key": "<YOUR_API_KEY>",
    "Nected-Branch": "staging"
}

response = requests.post(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(f"Task ID: {data['data']['taskId']}")
    print(f"Task State: {data['data']['taskState']}")
else:
    print(f"Error: {response.json()['message']}")

---

Notes

Asynchronous Operation

• This endpoint initiates an asynchronous operation. The pull operation continues processing in the background after the initial response.

• Use the returned taskId to track the status of the pull operation through a task status endpoint (if available).

• The taskState field indicates the current status and may change over time as the pull progresses.

Branch Requirements

• The Nected-Branch header must match a valid branch name in your workspace.

• Ensure you have appropriate permissions to perform pull operations on the specified branch.

• Different branches may have different remote configurations and data sources.

Task Tracking

• Store the taskId from the response to monitor the operation's progress.

• The task state will transition from "pending" → "in-progress" → "completed" or "failed".

• Poll the task status endpoint (if available) to check when the operation completes.

Best Practices

• Always include both Nected-API-Key and Nected-Branch headers in your requests.

• Handle error responses appropriately, especially 401 errors which indicate authentication issues.

• Implement retry logic for 500 errors with exponential backoff.

• Monitor the task state to ensure the pull operation completes successfully.