Hanzo
OpenapiSync

Create declares a sync between two endpoints and returns it.

Create declares a sync between two endpoints and returns it.

POST /v1/sync

Addresshttps://api.hanzo.ai/v1/sync
MethodPOST
Operationpost_sync
AuthAuthorization: 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).

FieldInTypeRequiredDescription
actorbodystringActor is the identity the sync writes as, used as the loop guard so its own writes do not re-trigger it.
directionbodystringDirection is both (the default), pull, push or off.
kindbodystringKind is what is being synced.
runbodybooleanRun reconciles once immediately after the upsert, in the background.
sourcebodyendpointReq
source.connectorbodystringConnector names the stored credential to reach this endpoint with.
source.locatorbodystringLocator 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.providerbodystringProvider is the platform: github or gitlab for a source; a target defaults to the native Hanzo Git plane.
targetbodyendpointReq
target.connectorbodystringConnector names the stored credential to reach this endpoint with.
target.locatorbodystringLocator 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.providerbodystringProvider is the platform: github or gitlab for a source; a target defaults to the native Hanzo Git plane.
triggerbodystringTrigger is what starts a reconcile: webhook (the default), poll or manual.

Response

StatusBodyMeaning
200syncViewok

200 body — 15 fields.

FieldInTypeAlwaysDescription
actorbodystringActor is the identity a reconcile writes AS.
createdAtbodystringCreatedAt is when the link was first declared, RFC3339 in UTC.
directionbodystringDirection is which way work flows: "both", "pull" (target ← source), "push" (source → target), or "off" — which keeps the link declared and moves nothing.
idbodystringID 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.
kindbodystringKind is what is being synced.
sourcebodyendpointView
source.connectorbodystringConnector names a connected account from the org's connector registry, when the endpoint reaches its provider through one.
source.locatorbodystringLocator 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.providerbodystringProvider is the concrete integration: "github", "gitlab" or "hanzo-git".
targetbodyendpointView
target.connectorbodystringConnector names a connected account from the org's connector registry, when the endpoint reaches its provider through one.
target.locatorbodystringLocator 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.providerbodystringProvider is the concrete integration: "github", "gitlab" or "hanzo-git".
triggerbodystringTrigger is what starts a reconcile: "webhook" (the provider tells us), "poll" (we ask on a schedule), or "manual" (only an explicit call).
updatedAtbodystringUpdatedAt 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 create

Sync API · All Hanzo APIs · Interactive reference

How is this guide?

On this page