Knowledge Files

Create or replace a knowledge file

Sends the file bytes directly as the request body. Do not wrap the content in JSON or multipart form data. The extension and Content-Type must describe the same supported file format. Send application/octet-stream to infer the type from the extension. The request body can contain at most 10 MiB (10,485,760 bytes).

A new path returns 201 Created; replacing an existing path returns 200 OK. Use If-Match with the current metadata ETag to prevent a concurrent update from being overwritten.

PUT

knowledge

files

{file_path}

Create or replace a knowledge file

curl --request PUT \
  --url https://api.traversal.com/v1/knowledge/files/{file_path} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: text/markdown' \
  --data '<string>'

import requests

url = "https://api.traversal.com/v1/knowledge/files/{file_path}"

payload = "<string>"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "text/markdown"
}

response = requests.put(url, data=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'text/markdown'},
  body: '<string>'
};

fetch('https://api.traversal.com/v1/knowledge/files/{file_path}', 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.traversal.com/v1/knowledge/files/{file_path}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "<string>",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: text/markdown"
  ],
]);

$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.traversal.com/v1/knowledge/files/{file_path}"

	payload := strings.NewReader("<string>")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "text/markdown")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.traversal.com/v1/knowledge/files/{file_path}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "text/markdown")
  .body("<string>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.traversal.com/v1/knowledge/files/{file_path}")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'text/markdown'
request.body = "<string>"

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

{
  "path": "user_generated/runbooks/checkout.md",
  "content_type": "text/markdown",
  "size_bytes": 1,
  "sha256": "<string>",
  "etag": "\"d50c991679d03c2a7392b123eb748b4f\"",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "created": true
}

{
  "path": "user_generated/runbooks/checkout.md",
  "content_type": "text/markdown",
  "size_bytes": 1,
  "sha256": "<string>",
  "etag": "\"d50c991679d03c2a7392b123eb748b4f\"",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "created": true
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

Authorizations

Authorization

string

header

required

Bearer token in the Authorization header — for example, Authorization: Bearer trv_ak_your_api_key_here. Each key is bound to a specific user and organization.

Headers

If-Match

string

Strong ETag from the current file metadata. The update returns 412 Precondition Failed if the validator is stale. Use * to require that the path already exists.

If-None-Match

string

Send * to create the file only when the path does not already exist. If the path exists or is created concurrently, the request returns 412 Precondition Failed.

Path Parameters

file_path

string

required

Slash-delimited path under user_generated/ or skills/. Maximum length is 900 UTF-8 bytes, with at most 255 bytes per path segment.

Body

Raw file bytes, limited to 10 MiB (10,485,760 bytes).

The body is of type file.

Response

Existing knowledge file replaced.

path

string

required

POSIX path under user_generated/ or skills/.

Example:

"user_generated/runbooks/checkout.md"

content_type

string

required

Stored media type.

Example:

"text/markdown"

size_bytes

integer

required

File size in bytes.

Required range: x >= 0

sha256

string

required

Hex SHA-256 digest of the file bytes.

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

etag

string

required

Opaque version token for conditional requests.

Example:

"\"d50c991679d03c2a7392b123eb748b4f\""

created_at

string<date-time>

required

updated_at

string<date-time>

required

created

boolean

required

True when this request created a new path.

⌘I

Create or replace a knowledge file

curl --request PUT \
  --url https://api.traversal.com/v1/knowledge/files/{file_path} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: text/markdown' \
  --data '<string>'

import requests

url = "https://api.traversal.com/v1/knowledge/files/{file_path}"

payload = "<string>"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "text/markdown"
}

response = requests.put(url, data=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'text/markdown'},
  body: '<string>'
};

fetch('https://api.traversal.com/v1/knowledge/files/{file_path}', 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.traversal.com/v1/knowledge/files/{file_path}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "<string>",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: text/markdown"
  ],
]);

$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.traversal.com/v1/knowledge/files/{file_path}"

	payload := strings.NewReader("<string>")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "text/markdown")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.traversal.com/v1/knowledge/files/{file_path}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "text/markdown")
  .body("<string>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.traversal.com/v1/knowledge/files/{file_path}")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'text/markdown'
request.body = "<string>"

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

{
  "path": "user_generated/runbooks/checkout.md",
  "content_type": "text/markdown",
  "size_bytes": 1,
  "sha256": "<string>",
  "etag": "\"d50c991679d03c2a7392b123eb748b4f\"",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "created": true
}

{
  "path": "user_generated/runbooks/checkout.md",
  "content_type": "text/markdown",
  "size_bytes": 1,
  "sha256": "<string>",
  "etag": "\"d50c991679d03c2a7392b123eb748b4f\"",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "created": true
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

{
  "error": {
    "code": "conflict",
    "message": "<string>",
    "retry_after": 123
  }
}

Get Started

Architecture

Set up

Using Traversal

API

Security & Trust

Changelog

Create or replace a knowledge file

Authorizations

Headers

Path Parameters

Body

Response