Delete knowledge document

Permanently deletes a knowledge document. Its chunks and embeddings cascade-delete automatically, and if the document was PDF-sourced, the original file is removed from storage too.

There is no bulk variant for knowledge documents — send one request per document.

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


DELETE /v1/brands/{brand_id}/knowledge-documents/{document_id}

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

This endpoint takes no body.

Request

cURL


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

Python


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

JavaScript


const options = {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <api-key>',
    'Idempotency-Key': '5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa',
  },
};
 
fetch('https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/knowledge-documents/b4f7e2a1-9c3d-4e6f-8a1b-2c5d7e9f0a3b', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <api-key>",
    "Idempotency-Key: 5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa"
  ],
]);
 
$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"
    "io"
)
 
func main() {
 
    url := "https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/knowledge-documents/b4f7e2a1-9c3d-4e6f-8a1b-2c5d7e9f0a3b"
 
    req, _ := http.NewRequest("DELETE", url, nil)
 
    req.Header.Add("Authorization", "Bearer <api-key>")
    req.Header.Add("Idempotency-Key", "5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa")
 
    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")
 
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
 
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <api-key>'
request["Idempotency-Key"] = '5b0e77d2-13a9-4f6a-8ce1-9a3f5e21c0aa'
 
response = http.request(request)
puts response.read_body

Response

200


{
  "data": {
    "deleted_document_id": "b4f7e2a1-9c3d-4e6f-8a1b-2c5d7e9f0a3b"
  },
  "request_id": "req_f18b2a9c0e4d37f6a1b5"
}

401


{
  "error": {
    "code": "token_expired",
    "message": "This API key has expired. Roll it from the API tab on the Connections page to get a replacement.",
    "request_id": "req_8f21c0aa47b1490d2e63"
  }
}

403 plan


{
  "error": {
    "code": "plan_required",
    "message": "This workspace is not enabled for API writes. Contact support to have it turned on.",
    "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_31c9ba7f0e5d4a118cc2"
  }
}

Response fields

Field	Type	Description
`data.deleted_document_id`	`uuid`	required. The document that was removed
`request_id`	`string`	required. Also returned as the `x-request-id` header. Quote it when contacting support

Errors

Status	Code	When
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
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

Notes

This is not reversible. Chunks and embeddings cascade-delete with the row, and there is no trash or undo through the API.

Deletion is not gated on current Brand Knowledge plan access. Unlike every other write on this surface, this call skips the entitlement check — you can always remove a document, even from a workspace whose plan no longer includes Brand Knowledge.

No bulk variant exists. Send one request per document.

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