Resync knowledge document

Re-runs the full ingest pipeline (extract if PDF, summarize, chunk, embed) for one document. Use it after a body edit through Update knowledge document set needs_reembed, or to retry a document stuck in status: "failed".

This call returns immediately once the resync is dispatched. Poll Get knowledge document until status flips to ready or failed.

Requires the write:knowledge_base scope, and the workspace must be enabled for API writes.


POST /v1/brands/{brand_id}/knowledge-documents/{document_id}/resync

Authorization

Header	Type	Required
`Authorization`	`Bearer asky_sk_…`	required
`Idempotency-Key`	`string`	required

Path parameters

Parameter	Type	Required	Description
`brand_id`	`uuid`	required	From List brands
`document_id`	`uuid`	required	From List knowledge documents

Body

application/json. This endpoint takes no fields — send {} or an empty body.

Any field you pass returns 400 invalid_request naming it.

Request

cURL


curl --request POST \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/knowledge-documents/b4f7e2a1-9c3d-4e6f-8a1b-2c5d7e9f0a3b/resync' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: 5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa' \
  --header 'Content-Type: application/json' \
  --data '{}'

Python


import requests
 
url = "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/knowledge-documents/b4f7e2a1-9c3d-4e6f-8a1b-2c5d7e9f0a3b/resync"
 
headers = {
    "Authorization": "Bearer <api-key>",
    "Idempotency-Key": "5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa",
    "Content-Type": "application/json",
}
 
response = requests.post(url, headers=headers, json={})
print(response.text)

JavaScript


const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api-key>',
    'Idempotency-Key': '5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/knowledge-documents/b4f7e2a1-9c3d-4e6f-8a1b-2c5d7e9f0a3b/resync', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

PHP


<?php
 
$curl = curl_init();
 
curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/knowledge-documents/b4f7e2a1-9c3d-4e6f-8a1b-2c5d7e9f0a3b/resync",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{}",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <api-key>",
    "Idempotency-Key: 5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa",
    "Content-Type: application/json"
  ],
]);
 
$response = curl_exec($curl);
$err = curl_error($curl);
 
curl_close($curl);
 
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Go


package main
 
import (
    "fmt"
    "net/http"
    "strings"
    "io"
)
 
func main() {
 
    url := "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/knowledge-documents/b4f7e2a1-9c3d-4e6f-8a1b-2c5d7e9f0a3b/resync"
 
    payload := strings.NewReader("{}")
 
    req, _ := http.NewRequest("POST", url, payload)
 
    req.Header.Add("Authorization", "Bearer <api-key>")
    req.Header.Add("Idempotency-Key", "5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa")
    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))
 
}

Ruby


require 'uri'
require 'net/http'
 
url = URI("https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/knowledge-documents/b4f7e2a1-9c3d-4e6f-8a1b-2c5d7e9f0a3b/resync")
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
 
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <api-key>'
request["Idempotency-Key"] = '5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa'
request["Content-Type"] = 'application/json'
request.body = "{}"
 
response = http.request(request)
puts response.read_body

Response

200


{
  "data": {
    "document_id": "b4f7e2a1-9c3d-4e6f-8a1b-2c5d7e9f0a3b",
    "status": "processing"
  },
  "request_id": "req_e4a9c1b8d0f37e5a2c69"
}

400


{
  "error": {
    "code": "invalid_request",
    "message": "Unknown field 'force'. Allowed: .",
    "request_id": "req_2d61f0ac48b34e59c7bd"
  }
}

403 plan


{
  "error": {
    "code": "plan_required",
    "message": "Brand Knowledge is not included in this workspace's current plan.",
    "request_id": "req_9d4a7c1e3b5f48d0ac2e"
  }
}

404


{
  "error": {
    "code": "not_found",
    "message": "Not found.",
    "request_id": "req_5b0e77d213a94f6a8ce1"
  }
}

429


{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 24 seconds.",
    "request_id": "req_9a3f5e21c0aa47b190d2"
  }
}

Response fields

Field	Type	Description
`data.document_id`	`uuid`	required. Echoes the `document_id` you resynced
`data.status`	`string`	required. Always `processing` — the resync has started, not finished
`request_id`	`string`	required. Also returned as the `x-request-id` header. Quote it when contacting support

Errors

Status	Code	When
400	`invalid_request`	Unknown field in the body
401	`invalid_token`	The key is missing, malformed, or does not exist
401	`token_expired`	The key passed its expiry date
401	`token_revoked`	The key was revoked
403	`insufficient_scope`	The key does not carry `write:knowledge_base`
403	`plan_required`	This workspace is not enabled for API writes
403	`plan_required`	Brand Knowledge is not included in this workspace’s plan
404	`not_found`	The brand does not exist, this key is not allowed to reach it, or `document_id` does not belong to this brand
429	`rate_limited`	Over 60 requests per minute

plan_required appears twice with different messages. The first means this workspace’s plan does not include API writes at all. The second means writes are enabled but Brand Knowledge specifically is not on the plan.

Notes

This always dispatches. Unlike Run alignment check, there is no daily dedup or already_running concept here — calling it twice in a row queues two ingest passes back to back.

A PDF document’s extracted text is discarded first, then re-extracted. raw_text and char_count reset to null and 0 immediately, before the new vision-extraction pass completes — so a caller reading the document mid-resync sees it briefly empty. A pasted document’s raw_text is left untouched; only its chunks and embeddings regenerate.

Poll for completion. Get knowledge document is the source of truth — watch status flip from processing to ready or failed.

This is the retry path for a failed document. Whatever caused the previous ingest to fail (a transient extraction or embedding error, for example) is retried from scratch on the next call.

Idempotency-Key is required. Reuse it when retrying an attempt and the original response is replayed rather than a second ingest pass being queued. See Idempotency.