Skip to content

chore(docs): Add more descriptive parameter descriptions to fai APIs. #533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 20, 2025
Merged

chore(docs): Add more descriptive parameter descriptions to fai APIs. #533

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 30 additions & 16 deletions fern/apis/fai/definition/document.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,28 +22,32 @@ service:
properties:
document:
type: string
docs: The content of the document that will be returned in the tool response
docs: The content of the document that will be returned to Ask Fern during document retrieval.
chunk:
type: optional<string>
docs: The chunk of the document that will be indexed as a vector. If not provided, the document will be indexed.
docs: The textual content that should be vectorized when indexing the document. If not provided, the full document will be vectorized.
title:
type: optional<string>
docs: The title of the document
docs: The title of the document. This will be used with the `url` when Ask Fern cites this document.
url:
type: optional<string>
docs: The url of the document
docs: The url of the document. This will be used as the source of the document when Ask Fern cites it.
version:
type: optional<string>
docs: The version of the document
docs: |
The version of the document. This will be compared against when running Ask Fern with version filters.
If null, the document will be retrievable by all versions.
product:
type: optional<string>
docs: The product of the document
docs: |
The product of the document. This will be used to filter documents when running Ask Fern with product filters.
If null, the document will be retrievable by all products.
keywords:
type: optional<list<string>>
docs: The keywords of the document
docs: The keywords of the document. Adding keywords can improve document matching.
authed:
type: optional<boolean>
docs: Whether the document is authed
docs: Whether the document is authed. If true, the document will be retrievable by all users.
response: DocumentIdResponse
errors:
- commons.BadRequestError
Expand All @@ -64,28 +68,38 @@ service:
properties:
document:
type: optional<string>
docs: The content of the document that will be returned in the tool response.
docs: |
The updated content of the document that will be returned to Ask Fern during document retrieval.
If not provided, this field will remain unchanged.
chunk:
type: optional<string>
docs: The chunk of the document that will be indexed as a vector.
docs: |
The updated textual content that should be vectorized when indexing the document.
If not provided, this field will remain unchanged.
title:
type: optional<string>
docs: The title of the document
docs: |
The updated title of the document. If not provided, this field will remain unchanged.
url:
type: optional<string>
docs: The url of the document
docs: |
The updated url of the document. If not provided, this field will remain unchanged.
version:
type: optional<string>
docs: The version of the document
docs: |
The updated version of the document. If not provided, this field will remain unchanged.
product:
type: optional<string>
docs: The product of the document
docs: |
The updated product of the document. If not provided, this field will remain unchanged.
keywords:
type: optional<list<string>>
docs: The keywords of the document
docs: |
The updated keywords of the document. If not provided, this field will remain unchanged.
authed:
type: optional<boolean>
docs: Whether the document is authed
docs: |
The updated authed status of the document. If not provided, this field will remain unchanged.
response: Document
errors:
- commons.BadRequestError
Expand Down
21 changes: 13 additions & 8 deletions fern/apis/fai/definition/guidance.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,7 @@ service:
base-path: /guidance
endpoints:
createGuidance:
docs: |
Create a guidance for a given domain. Guidance can be used to provide additional context to Ask Fern and improve its accuracy.
docs: Index a guidance document for a given domain
path: /{domain}/create
method: POST
audiences:
Expand All @@ -22,10 +21,12 @@ service:
properties:
context:
type: list<string>
docs: The context of the guidance document, as a list of strings, that will be indexed.
docs: |
The context of the guidance document, as a list of strings, that will be indexed.
Each string will be vectorized separately to generate a separate record.
document:
type: string
docs: The content of the guidance document that will be returned in the tool response
docs: The content of the guidance document that will be returned to Ask Fern during Ask Fern retrieval.
response: GuidanceIdResponse
errors:
- commons.BadRequestError
Expand All @@ -45,11 +46,15 @@ service:
body:
properties:
context:
type: list<string>
docs: The context of the document, as a list of strings, that will be indexed.
type: optional<list<string>>
docs: |
The updated context of the guidance document, as a list of strings, that will be indexed.
If not provided, this field will remain unchanged.
document:
type: string
docs: The content of the document that will be returned in the tool response. If not provided, the document will be removed from the index.
type: optional<string>
docs: |
The updated content of the guidance document that will be returned to Ask Fern during Ask Fern retrieval.
If not provided, this field will remain unchanged.
response: Guidance
errors:
- commons.BadRequestError
Expand Down