Sync an Agent Source

curl --request POST \
  --url https://api.checkfu.com/v1/agent-sources/{id}/sync \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "expected_version": 1,
  "acted_as": "<string>"
}
'

import requests

url = "https://api.checkfu.com/v1/agent-sources/{id}/sync"

payload = {
    "expected_version": 1,
    "acted_as": "<string>"
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({expected_version: 1, acted_as: '<string>'})
};

fetch('https://api.checkfu.com/v1/agent-sources/{id}/sync', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/agent-sources/{id}/sync",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expected_version' => 1,
    'acted_as' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/agent-sources/{id}/sync"

	payload := strings.NewReader("{\n  \"expected_version\": 1,\n  \"acted_as\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.checkfu.com/v1/agent-sources/{id}/sync")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expected_version\": 1,\n  \"acted_as\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/agent-sources/{id}/sync")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expected_version\": 1,\n  \"acted_as\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "workspace_id": "<string>",
  "name": "<string>",
  "project_id": "<string>",
  "description": "<string>",
  "root": "<string>",
  "status": "pending",
  "last_sync": {
    "project_revision": 1,
    "commit_sha": "<string>",
    "author_login": "<string>",
    "synced_at": "<string>",
    "draft": {
      "action": "created",
      "agent_id": "<string>",
      "draft_revision": 1,
      "agent_version": 1
    },
    "publication": {
      "action": "published",
      "version": 1,
      "attributed_to": "<string>"
    }
  },
  "last_sync_error_code": "<string>",
  "version": 1,
  "created_at": "<string>",
  "updated_at": "<string>"
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Sync an Agent Source

Refresh the bound Project to an exact commit, read the source’s subtree as a D19 agent directory through the Project’s governed Connection, and land it as the definition’s draft with exactly the validation an agent import applies. The draft outcome reports created, updated, unchanged, adopted (a definition whose canonical directory bytes already equal the tree), invalid, or missing; nothing is ever deleted for you. Publication is the human merge made durable: a new draft publishes as a version only when the merged commit’s author resolves, through an audited external identity link, to a person Principal — a service Principal or an unlinked identity withholds publication and the tree stays a draft. Requires expected_version and an acted_as Principal that owns and holds use_connection on that Connection, and accepts an Idempotency-Key.

Checkfu support posture: alpha; hosted. Required evidence journey: agent-definition. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST

agent-sources

{id}

sync

Sync an Agent Source

curl --request POST \
  --url https://api.checkfu.com/v1/agent-sources/{id}/sync \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "expected_version": 1,
  "acted_as": "<string>"
}
'

import requests

url = "https://api.checkfu.com/v1/agent-sources/{id}/sync"

payload = {
    "expected_version": 1,
    "acted_as": "<string>"
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({expected_version: 1, acted_as: '<string>'})
};

fetch('https://api.checkfu.com/v1/agent-sources/{id}/sync', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/agent-sources/{id}/sync",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expected_version' => 1,
    'acted_as' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/agent-sources/{id}/sync"

	payload := strings.NewReader("{\n  \"expected_version\": 1,\n  \"acted_as\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.checkfu.com/v1/agent-sources/{id}/sync")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expected_version\": 1,\n  \"acted_as\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/agent-sources/{id}/sync")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expected_version\": 1,\n  \"acted_as\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "workspace_id": "<string>",
  "name": "<string>",
  "project_id": "<string>",
  "description": "<string>",
  "root": "<string>",
  "status": "pending",
  "last_sync": {
    "project_revision": 1,
    "commit_sha": "<string>",
    "author_login": "<string>",
    "synced_at": "<string>",
    "draft": {
      "action": "created",
      "agent_id": "<string>",
      "draft_revision": 1,
      "agent_version": 1
    },
    "publication": {
      "action": "published",
      "version": 1,
      "attributed_to": "<string>"
    }
  },
  "last_sync_error_code": "<string>",
  "version": 1,
  "created_at": "<string>",
  "updated_at": "<string>"
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version

enum<string>

required

Available options:

2026-08-27

idempotency-key

string

Maximum string length: 255

Path Parameters

string

required

Pattern: ^agsrc_[0-9a-f]{32}$

Body

application/json

expected_version

integer

required

Required range: x > 0

acted_as

string

required

Pattern: ^prin_[0-9a-f]{32}$

Response

Success

string

required

Pattern: ^agsrc_[0-9a-f]{32}$

workspace_id

string

required

Pattern: ^wrkspc_[0-9a-f]{32}$

name

string

required

Pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$

project_id

string

required

Pattern: ^prj_[0-9a-f]{32}$

description

string | null

required

Maximum string length: 16384

root

string | null

required

Required string length: 1 - 1024

status

enum<string>

required

Available options:

pending,

healthy,

sync_failed

last_sync

object | null

required

Show child attributes

last_sync_error_code

string | null

required

Required string length: 1 - 8192

version

integer

required

Required range: x > 0

created_at

string

required

updated_at

string

required

Developer tools

Canonical tables

Author protocols

Generated HTTP API

Sync an Agent Source

Authorizations

Headers

Path Parameters

Body

Response