# Knowledge

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**

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

**Node**

```javascript
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());
```

**Python**

```python
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**

```php
<?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 | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | yes | 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 | Required | Description |
| --- | --- | --- | --- |
| `question` | string | yes | Your question, with spaces tidied. |
| `found` | boolean | yes | False when the knowledge base does not cover it. |
| `answer` | string | yes | One to three sentences, ready to say aloud. Empty when `found` is false. |
| `section` | string | yes | The part of the knowledge base it came from. Empty when `found` is false. |
| `note` | string | yes | How an agent should use the answer. |

**Covered**

```json
{
  "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**

```json
{
  "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**

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

**Example**

```json
{
  "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.

**Example**

```json
{
  "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**

```json
{
  "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.

**Example**

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

## Ask the knowledge base (POST)

`POST /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.

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**

```bash
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"
  }'
```

**Node**

```javascript
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());
```

**Python**

```python
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**

```php
<?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 | Required | 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**

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

### Answers

#### 200

The answer, or `found: false`.

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

**Covered**

```json
{
  "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**

```json
{
  "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**

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

**Example**

```json
{
  "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.

**Example**

```json
{
  "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**

```json
{
  "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.

**Example**

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