# 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`

<a href="https://www.postman.com/tech-team-1209/nected-public-workspace/request/39497877-36bdc4d9-c62d-4949-9bac-59e83a863b08?action=share&#x26;source=copy-link&#x26;creator=39498393&#x26;ctx=documentation" class="button primary" data-icon="webhook">Try it here</a>

### 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: <YOUR_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": "<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)

```python
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nected.ai/nected-docs/management-api/pull-remote-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.