Create declares a sync between two endpoints and returns it.
Create declares a sync between two endpoints and returns it.
POST /v1/sync
| Address | https://api.hanzo.ai/v1/sync |
| Method | POST |
| Operation | post_sync |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Create declares a sync between two endpoints and returns it. It is an UPSERT: re-declaring the same source and target updates that link rather than piling up duplicates, so a console that re-submits is safe. The org comes from the validated principal, never from the request, so a sync can only ever bind endpoints inside the caller's own org. A git source must be an https clone URL on the provider's own host with no embedded credentials; a target left empty is derived as a native repository named after the source. With run=true the first reconcile is queued in the background, so a large initial import never blocks this response.
Request
13 fields, body application/json (required).
| Field | In | Type | Required | Description |
|---|---|---|---|---|
actor | body | string | — | Actor is the identity the sync writes as, used as the loop guard so its own writes do not re-trigger it. |
direction | body | string | — | Direction is both (the default), pull, push or off. |
kind | body | string | — | Kind is what is being synced. |
run | body | boolean | — | Run reconciles once immediately after the upsert, in the background. |
source | body | endpointReq | — | |
source.connector | body | string | — | Connector names the stored credential to reach this endpoint with. |
source.locator | body | string | — | Locator addresses the resource. For a git source it is the https clone URL on the provider's own host, with no embedded credentials; for a native target it is… |
source.provider | body | string | — | Provider is the platform: github or gitlab for a source; a target defaults to the native Hanzo Git plane. |
target | body | endpointReq | — | |
target.connector | body | string | — | Connector names the stored credential to reach this endpoint with. |
target.locator | body | string | — | Locator addresses the resource. For a git source it is the https clone URL on the provider's own host, with no embedded credentials; for a native target it is… |
target.provider | body | string | — | Provider is the platform: github or gitlab for a source; a target defaults to the native Hanzo Git plane. |
trigger | body | string | — | Trigger is what starts a reconcile: webhook (the default), poll or manual. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | syncView | ok |
200 body — 15 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
actor | body | string | — | Actor is the identity a reconcile writes AS. |
createdAt | body | string | — | CreatedAt is when the link was first declared, RFC3339 in UTC. |
direction | body | string | — | Direction is which way work flows: "both", "pull" (target ← source), "push" (source → target), or "off" — which keeps the link declared and moves nothing. |
id | body | string | — | ID is the link's handle, derived from its source and target — which is what makes re-declaring the same pair an update rather than a duplicate. |
kind | body | string | — | Kind is what is being synced. |
source | body | endpointView | — | |
source.connector | body | string | — | Connector names a connected account from the org's connector registry, when the endpoint reaches its provider through one. |
source.locator | body | string | — | Locator addresses the thing INSIDE that provider, in the provider's own terms — an https clone URL for a hosted forge, a bare repository name for hanzo-git. |
source.provider | body | string | — | Provider is the concrete integration: "github", "gitlab" or "hanzo-git". |
target | body | endpointView | — | |
target.connector | body | string | — | Connector names a connected account from the org's connector registry, when the endpoint reaches its provider through one. |
target.locator | body | string | — | Locator addresses the thing INSIDE that provider, in the provider's own terms — an https clone URL for a hosted forge, a bare repository name for hanzo-git. |
target.provider | body | string | — | Provider is the concrete integration: "github", "gitlab" or "hanzo-git". |
trigger | body | string | — | Trigger is what starts a reconcile: "webhook" (the provider tells us), "poll" (we ask on a schedule), or "manual" (only an explicit call). |
updatedAt | body | string | — | UpdatedAt is bumped by every reconcile, so it reads as the LAST-SYNCED time rather than the last edit. |
Failure carries the platform error shape — see Errors.
Examples
hanzo sync createimport { Configuration, SyncApi } from 'hanzoai';
const api = new SyncApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postSync({ actor: "<actor>", direction: "<direction>" });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import SyncApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = SyncApi(client).post_sync(actor="<actor>", direction="<direction>")cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.SyncAPI.PostSync(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, sync_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = sync_api::post_sync(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.SyncApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new SyncApi(client).postSync();curl -X POST https://api.hanzo.ai/v1/sync \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"actor": "<actor>",
"direction": "<direction>"
}'The door reaches sync through the sync tool, which names its 6 operations with its own verbs — this one among them, under a name only the door declares. describe explains any of them:
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "describe",
"arguments": {
"op": "get_sync"
}
}
}'How is this guide?