> For the complete documentation index, see [llms.txt](https://docs.nected.ai/nected-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nected.ai/nected-docs/management-api/deprecated-apis/pull-remote-data.md).
# 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.
```json
{
"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
```json
{
"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.
```json
{
"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.
```json
{
"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
```bash
curl -X POST "{{NECTED_BASE_URL}}/dev/remote/pull" \
-H "accept: application/json" \
-H "Nected-API-Key: " \
-H "Nected-Branch: staging" \
-d ''
```
#### JavaScript (fetch)
```javascript
const response = await fetch("{{NECTED_BASE_URL}}/dev/remote/pull", {
method: "POST",
headers: {
"accept": "application/json",
"Nected-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)
```python
import requests
url = "{{NECTED_BASE_URL}}/dev/remote/pull"
headers = {
"accept": "application/json",
"Nected-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.