ASAPP Knowledge Base API
Submit and retrieve knowledge base articles for GenerativeAgent.
OpenAPI Specification
openapi: 3.0.1
info:
title: Knowledge Base API
description: >
This API allows for the programmatic addition and modification of articles
in the Knowledge Base. It is particularly useful when data sources are not
suitable for scraping or when manual article creation via the ASAPP
AI-Console UI is not preferred. The Submission API facilitates the creation
and updating of articles, with each submission representing a specific
change to an article.
All submissions require human review and approval through the ASAPP
AI-Console UI before they are published in the Knowledge Base.
To create a new article, submit the article details without an `articleId`.
Omitting the `articleId` signals the creation of a new article upon
submission approval.
To update an existing article, include the `articleId` of the article you
wish to modify along with the updates in your submission.
contact:
email: api-info@asapp.com
license:
name: ASAPP Software License
url: https://api.asapp.com/LICENSE
version: '1.0'
paths:
/knowledge-base/v1/submissions:
post:
summary: Create a submission
description: >-
Initiate a request to add a new article or update an existing one. The
provided title and content will be processed to create the final version
of the submission.
operationId: createSubmission
requestBody:
required: true
content:
application/json:
schema:
description: >-
A proposal for creating a new article or updating an existing
one in the Knowledge Base.
type: object
properties:
articleId:
type: string
description: The unique identifier for the article being updated.
example: 8f8dcc09-22d7-4aed-acae-fddd060c3a88
title:
type: string
description: >-
The proposed title of the article, which will be refined
automatically. This is required for new articles.
minLength: 1
maxLength: 256
example: 5G Data Plan
content:
type: string
description: >-
The article content in plain text, expected to be in English
and limited to 200,000 Unicode characters. This will be
refined during submission. Required for new articles.
minLength: 1
maxLength: 200000
example: >-
Our 5G data plans offer lightning-fast speeds and generous
data allowances. The Basic 5G plan includes 50GB of data per
month, while our Unlimited 5G plan offers truly unlimited
data with no speed caps. Both plans include unlimited calls
and texts within the country. International roaming can be
added for an additional fee.
url:
type: string
description: >-
A reference URL for the article, used for informational
purposes only.
example: https://example.com/5g-data-plans
metadata:
type: array
items:
description: >-
A key-value pair providing additional information about
the article.
type: object
required:
- key
- value
properties:
key:
type: string
minLength: 1
description: The key for the metadata entry.
example: department
value:
type: string
minLength: 1
description: The value for the metadata entry.
example: Customer experience
description: Additional key-value pairs related to the article.
example:
- key: department
value: Customer experience
queryExamples:
type: array
items:
type: string
description: >-
Examples of customer questions related to the article, such
as "Why is my bill so high?". Defaults to an empty list if
not provided.
example:
- What 5G plans do you offer?
- Is there an unlimited 5G plan?
additionalInstructions:
type: array
items:
description: Guidelines and responses to enhance the article.
type: object
properties:
clarificationInstruction:
type: string
description: A guideline to improve the article's content.
example: Emphasize that 5G coverage may vary by location
exampleResponse:
type: string
description: >-
A sample response applicable if the clarification
instruction is followed.
example: >-
Our 5G plans offer great speeds and data allowances,
but please note that 5G coverage may vary depending on
your location. You can check coverage in your area on
our website.
description: >-
Specific instructions to ensure responses are relevant and
address exceptions.
example:
- clarificationInstruction: Emphasize that 5G coverage may vary by location
exampleResponse: >-
Our 5G plans offer great speeds and data allowances, but
please note that 5G coverage may vary depending on your
location. You can check coverage in your area on our
website.
example:
title: 5G Data Plan
content: >-
Our 5G data plans offer lightning-fast speeds and generous
data allowances. The Basic 5G plan includes 50GB of data per
month, while our Unlimited 5G plan offers truly unlimited data
with no speed caps. Both plans include unlimited calls and
texts within the country. International roaming can be added
for an additional fee.
url: https://example.com/5g-data-plans
metadata:
- key: department
value: Customer experience
queryExamples:
- What 5G plans do you offer?
- Is there an unlimited 5G plan?
additionalInstructions:
- clarificationInstruction: Emphasize that 5G coverage may vary by location
exampleResponse: >-
Our 5G plans offer great speeds and data allowances, but
please note that 5G coverage may vary depending on your
location. You can check coverage in your area on our
website.
responses:
'201':
description: Submission successfully created
content:
application/json:
schema:
description: >-
Information about a successfully submitted proposal to update
an article in the Knowledge Base.
type: object
properties:
id:
type: string
description: The unique identifier for the submission.
example: fddd060c-22d7-4aed-acae-8f8dcc093a88
articleId:
type: string
description: >-
The unique identifier for the article related to the
submission.
example: 8f8dcc09-22d7-4aed-acae-fddd060c3a88
submittedAt:
type: string
format: date-time
description: The timestamp when the submission was created.
example: '2024-12-12T00:00:00Z'
title:
type: string
description: The article title, either original or refined.
example: 5G Data Plan
content:
type: string
description: The article content, either original or refined.
example: >-
Our 5G data plans offer lightning-fast speeds and generous
data allowances. The Basic 5G plan includes 50GB of data
per month, while our Unlimited 5G plan offers truly
unlimited data with no speed caps. Both plans include
unlimited calls and texts within the country.
International roaming can be added for an additional fee.
url:
type: string
description: >-
The reference URL of the article. Defaults to an empty
string if not provided.
example: https://example.com/5g-data-plans
metadata:
type: array
items:
description: >-
A key-value pair providing additional information about
the article.
type: object
required:
- key
- value
properties:
key:
type: string
minLength: 1
description: The key for the metadata entry.
example: department
value:
type: string
minLength: 1
description: The value for the metadata entry.
example: Customer experience
description: Additional key-value pairs related to the article.
example:
- key: department
value: Customer experience
queryExamples:
type: array
items:
type: string
description: >-
Examples of customer questions related to the article.
Defaults to an empty array if not provided.
example:
- What 5G plans do you offer?
- Is there an unlimited 5G plan?
additionalInstructions:
type: array
items:
description: Guidelines and responses to enhance the article.
type: object
properties:
clarificationInstruction:
type: string
description: A guideline to improve the article's content.
example: Emphasize that 5G coverage may vary by location
exampleResponse:
type: string
description: >-
A sample response applicable if the clarification
instruction is followed.
example: >-
Our 5G plans offer great speeds and data allowances,
but please note that 5G coverage may vary depending
on your location. You can check coverage in your
area on our website.
description: >-
Specific instructions to ensure responses are relevant and
address exceptions.
example:
- clarificationInstruction: Emphasize that 5G coverage may vary by location
exampleResponse: >-
Our 5G plans offer great speeds and data allowances,
but please note that 5G coverage may vary depending on
your location. You can check coverage in your area on
our website.
status:
description: The current status of the submission.
example: PENDING_REVIEW
type: string
enum:
- PENDING_REVIEW
- ACCEPTED
- REJECTED
example:
id: fddd060c-22d7-4aed-acae-8f8dcc093a88
articleId: 8f8dcc09-22d7-4aed-acae-fddd060c3a88
submittedAt: '2024-12-12T00:00:00'
title: 5G Data Plan
content: >-
Our 5G data plans offer lightning-fast speeds and generous
data allowances. The Basic 5G plan includes 50GB of data per
month, while our Unlimited 5G plan offers truly unlimited data
with no speed caps. Both plans include unlimited calls and
texts within the country. International roaming can be added
for an additional fee.
url: https://example.com/5g-data-plans
metadata:
- key: department
value: Customer experience
queryExamples:
- What 5G plans do you offer?
- Is there an unlimited 5G plan?
additionalInstructions:
- clarificationInstruction: Emphasize that 5G coverage may vary by location
exampleResponse: >-
Our 5G plans offer great speeds and data allowances, but
please note that 5G coverage may vary depending on your
location. You can check coverage in your area on our
website.
status: PENDING_REVIEW
'400':
description: 400 - Bad request
content:
application/json:
schema:
description: Bad request response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 400-01
message: Bad request
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'401':
description: 401 - Unauthorized
content:
application/json:
schema:
description: Unauthorized response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 401-01
message: Unauthorized
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'403':
description: 403 - Forbidden
content:
application/json:
schema:
description: Forbidden response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 403-01
message: Forbidden Response
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'404':
description: 404 - Not Found
content:
application/json:
schema:
description: Not Found response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 404-01
message: Not Found
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'413':
description: 413 - Request Entity Too Large
content:
application/json:
schema:
description: Request Entity Too Large response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 413-01
message: Request Entity Too Large
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'429':
description: 429 - Too Many Requests
content:
application/json:
schema:
description: Too Many Requests response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 429-01
message: Too Many Requests
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'503':
description: 503 - Service Unavailable
content:
application/json:
schema:
description: Service Unavailable response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 503-01
message: Service Unavailable
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
default:
description: 500 - Internal Server Error
content:
application/json:
schema:
description: Default error response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 500-01
message: Internal server error
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
/knowledge-base/v1/submissions/{id}:
get:
summary: Retrieve a submission
description: Obtain the details of a specific submission using its unique identifier.
operationId: getSubmission
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The unique identifier for the submission to be retrieved.
example: fddd060c-22d7-4aed-acae-8f8dcc093a88
responses:
'200':
description: Submission successfully retrieved
content:
application/json:
schema:
description: >-
Information about a successfully submitted proposal to update
an article in the Knowledge Base.
type: object
properties:
id:
type: string
description: The unique identifier for the submission.
example: fddd060c-22d7-4aed-acae-8f8dcc093a88
articleId:
type: string
description: >-
The unique identifier for the article related to the
submission.
example: 8f8dcc09-22d7-4aed-acae-fddd060c3a88
submittedAt:
type: string
format: date-time
description: The timestamp when the submission was created.
example: '2024-12-12T00:00:00Z'
title:
type: string
description: The article title, either original or refined.
example: 5G Data Plan
content:
type: string
description: The article content, either original or refined.
example: >-
Our 5G data plans offer lightning-fast speeds and generous
data allowances. The Basic 5G plan includes 50GB of data
per month, while our Unlimited 5G plan offers truly
unlimited data with no speed caps. Both plans include
unlimited calls and texts within the country.
International roaming can be added for an additional fee.
url:
type: string
description: >-
The reference URL of the article. Defaults to an empty
string if not provided.
example: https://example.com/5g-data-plans
metadata:
type: array
items:
description: >-
A key-value pair providing additional information about
the article.
type: object
required:
- key
- value
properties:
key:
type: string
minLength: 1
description: The key for the metadata entry.
example: department
value:
type: string
minLength: 1
description: The value for the metadata entry.
example: Customer experience
description: Additional key-value pairs related to the article.
example:
- key: department
value: Customer experience
queryExamples:
type: array
items:
type: string
description: >-
Examples of customer questions related to the article.
Defaults to an empty array if not provided.
example:
- What 5G plans do you offer?
- Is there an unlimited 5G plan?
additionalInstructions:
type: array
items:
description: Guidelines and responses to enhance the article.
type: object
properties:
clarificationInstruction:
type: string
description: A guideline to improve the article's content.
example: Emphasize that 5G coverage may vary by location
exampleResponse:
type: string
description: >-
A sample response applicable if the clarification
instruction is followed.
example: >-
Our 5G plans offer great speeds and data allowances,
but please note that 5G coverage may vary depending
on your location. You can check coverage in your
area on our website.
description: >-
Specific instructions to ensure responses are relevant and
address exceptions.
example:
- clarificationInstruction: Emphasize that 5G coverage may vary by location
exampleResponse: >-
Our 5G plans offer great speeds and data allowances,
but please note that 5G coverage may vary depending on
your location. You can check coverage in your area on
our website.
status:
description: The current status of the submission.
example: PENDING_REVIEW
type: string
enum:
- PENDING_REVIEW
- ACCEPTED
- REJECTED
'400':
description: 400 - Bad request
content:
application/json:
schema:
description: Bad request response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 400-01
message: Bad request
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'401':
description: 401 - Unauthorized
content:
application/json:
schema:
description: Unauthorized response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 401-01
message: Unauthorized
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'403':
description: 403 - Forbidden
content:
application/json:
schema:
description: Forbidden response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 403-01
message: Forbidden Response
description: Error details
type: object
properties:
requestId:
type: string
description: Unique ID of the failing request
message:
type: string
description: Error message
code:
type: string
description: Error code
required:
- requestId
- message
'404':
description: 404 - Not Found
content:
application/json:
schema:
description: Not Found response
type: object
properties:
error:
example:
requestId: 8e033668-9f1a-11ec-b909-0242ac120002
code: 404-01
# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/asapp/refs/heads/main/openapi/asapp-knowledge-base-openapi.yml