By area

Knowledge

Read from the API’s own reference file every hour.

Ask Vocatech's knowledge base one question about the service and get the answer a person at our front desk would give.

Ask the knowledge base

GET/v1/knowledge/answer

Answers one question about Vocatech's service from Vocatech's own knowledge base, in one to three sentences, the way a person at our front desk would say it. When the knowledge base does not cover it, found is false and answer is empty.

The answer uses Vocatech's published facts only. Nothing about your account is in it.

Built for an AI agent's answer-questions job, and for help desks and chat bots. note tells an agent how to use the answer.

Keys with the support or knowledge scope can call this route.

Request

curl -G https://api.vocatech.com/v1/knowledge/answer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "q=What are your support hours?"

const params = new URLSearchParams({
  q: "What are your support hours?",
});

const res = await fetch(`https://api.vocatech.com/v1/knowledge/answer?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

console.log(res.status, await res.json());

import requests

r = requests.get(
    "https://api.vocatech.com/v1/knowledge/answer",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "q": "What are your support hours?",
    },
    timeout=30,
)
print(r.status_code, r.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.vocatech.com',
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'http_errors' => false,
]);

$res = $client->get('/v1/knowledge/answer', [
    'query' => [
        'q' => 'What are your support hours?',
    ],
]);

echo $res->getStatusCode(), PHP_EOL, $res->getBody(), PHP_EOL;

Parameters

Name	In	Type	Description
`q` required	query	string	The question, in the caller's own words. 3 to 500 characters. From 3 to 500 characters. For example `What are your support hours?`.
`source`	query	string	Who is asking, for our logs. Cut to 80 characters. Up to 80 characters. For example `Front desk bot`.

Answers

200

The answer, or found: false.

Field	Type	Description
`question` required	string	Your question, with spaces tidied.
`found` required	boolean	False when the knowledge base does not cover it.
`answer` required	string	One to three sentences, ready to say aloud. Empty when `found` is false.
`section` required	string	The part of the knowledge base it came from. Empty when `found` is false.
`note` required	string	How an agent should use the answer.

Covered

{
  "question": "What are your support hours?",
  "found": true,
  "answer": "Our team answers Monday to Thursday from 9 AM to 5 PM Eastern, and Friday from 9 AM to noon.",
  "section": "Support",
  "note": "Answer the caller from this in your own words; state only what it says."
}

Not covered

{
  "question": "Can you repair my fax machine?",
  "found": false,
  "answer": "",
  "section": "",
  "note": "The knowledge base does not cover this. Say you do not have that information and offer support."
}

401

No key, or a key that is wrong or turned off.

403

Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).

422

No question, or one too short or too long.

Example bodies

Example

{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "q is required: the question, in the caller's own words."
  }
}

Example

{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "q may be at most 500 characters."
  }
}

429

The knowledge counter is full (30 a minute, 2,000 a day per key), or another request limit was reached. Wait Retry-After seconds.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

Example body

Example

{
  "error": "Rate limit exceeded",
  "period": "minute",
  "limit": 30,
  "counter": "knowledge",
  "retry_after": 42
}

502

The knowledge base could not answer right now. Try again in a minute.

Example body

Example

{
  "error": {
    "code": 502,
    "type": "ERROR",
    "message": "The knowledge base could not answer right now. Try again in a minute."
  }
}

503

The knowledge base is not available right now, or the key could not be checked.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

Example body

Example

{
  "error": {
    "code": 503,
    "type": "ERROR",
    "message": "The knowledge base is not available right now."
  }
}

Ask the knowledge base (POST)

POST/v1/knowledge/answer

The answer uses Vocatech's published facts only. Nothing about your account is in it.

Built for an AI agent's answer-questions job, and for help desks and chat bots. note tells an agent how to use the answer.

Keys with the support or knowledge scope can call this route.

The same as the GET form, with the question in a JSON body as q or question. A q in the query string wins over the body.

Request

curl -X POST https://api.vocatech.com/v1/knowledge/answer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "What are your support hours?",
    "source": "Front desk bot"
  }'

const res = await fetch("https://api.vocatech.com/v1/knowledge/answer", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "What are your support hours?",
    source: "Front desk bot",
  }),
});

console.log(res.status, await res.json());

import requests

r = requests.post(
    "https://api.vocatech.com/v1/knowledge/answer",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "q": "What are your support hours?",
        "source": "Front desk bot",
    },
    timeout=30,
)
print(r.status_code, r.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.vocatech.com',
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'http_errors' => false,
]);

$res = $client->post('/v1/knowledge/answer', [
    'json' => [
        'q' => 'What are your support hours?',
        'source' => 'Front desk bot',
    ],
]);

echo $res->getStatusCode(), PHP_EOL, $res->getBody(), PHP_EOL;

Body

Field	Type	Description
`q`	string	The question, in the caller's own words. 3 to 500 characters. From 3 to 500 characters.
`question`	string	Another name for `q`.
`source`	string	Who is asking, for our logs. Cut to 80 characters.

Example

{
  "q": "What are your support hours?",
  "source": "Front desk bot"
}

Answers

200

The answer, or found: false.

Field	Type	Description
`question` required	string	Your question, with spaces tidied.
`found` required	boolean	False when the knowledge base does not cover it.
`answer` required	string	One to three sentences, ready to say aloud. Empty when `found` is false.
`section` required	string	The part of the knowledge base it came from. Empty when `found` is false.
`note` required	string	How an agent should use the answer.

Covered

{
  "question": "What are your support hours?",
  "found": true,
  "answer": "Our team answers Monday to Thursday from 9 AM to 5 PM Eastern, and Friday from 9 AM to noon.",
  "section": "Support",
  "note": "Answer the caller from this in your own words; state only what it says."
}

Not covered

{
  "question": "Can you repair my fax machine?",
  "found": false,
  "answer": "",
  "section": "",
  "note": "The knowledge base does not cover this. Say you do not have that information and offer support."
}

401

No key, or a key that is wrong or turned off.

403

Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).

422

No question, or one too short or too long.

Example bodies

Example

{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "q is required: the question, in the caller's own words."
  }
}

Example

{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "q may be at most 500 characters."
  }
}

429

The knowledge counter is full (30 a minute, 2,000 a day per key), or another request limit was reached. Wait Retry-After seconds.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

Example body

Example

{
  "error": "Rate limit exceeded",
  "period": "minute",
  "limit": 30,
  "counter": "knowledge",
  "retry_after": 42
}

502

The knowledge base could not answer right now. Try again in a minute.

Example body

Example

{
  "error": {
    "code": 502,
    "type": "ERROR",
    "message": "The knowledge base could not answer right now. Try again in a minute."
  }
}

503

The knowledge base is not available right now, or the key could not be checked.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

Example body

Example

{
  "error": {
    "code": 503,
    "type": "ERROR",
    "message": "The knowledge base is not available right now."
  }
}

Before thisSupport Next Old paths