openapi: 3.1.0
info:
title: Cody AI API
version: '1.0'
description: API for Cody AI
contact:
name: Cody AI
url: https://meetcody.ai
email: support@meetcody.ai
termsOfService: https://www.meetcody.ai/terms-conditions/
summary: API for Cody AI
servers:
- url: https://getcody.ai/api/v1
security:
- APIKey: []
paths:
/bots:
get:
summary: List Bots
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
x-stoplight:
id: dauy9655ownfd
type: array
items:
$ref: '#/components/schemas/Bot'
x-stoplight:
id: hg2hapcy1rflk
meta:
$ref: '#/components/schemas/Pagination'
x-stoplight:
id: 2l90y2wwhkgcg
operationId: list-bots
description: Get all bots
parameters:
- schema:
type: string
in: query
name: keyword
description: Keyword to filter the list of bots to only those that at least partially match the bot name.
/conversations:
get:
summary: List Conversations
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
x-stoplight:
id: bdkgjskqwf63l
items:
$ref: '#/components/schemas/Conversation'
x-stoplight:
id: kjse6zqpp6o5h
meta:
$ref: '#/components/schemas/Pagination'
x-stoplight:
id: ntcuy5u7rn0tz
operationId: list-conversations
description: Get all conversations
parameters:
- schema:
type: string
in: query
name: bot_id
description: Id of the bot to filter the list of conversations to only those that are using the selected bot.
- schema:
type: string
in: query
name: keyword
description: Keyword to filter the list of conversations to only those that at least partially match the conversation name.
- schema:
type: string
enum:
- document_ids
in: query
name: includes
description: Lists document ids the conversation is focused on.
post:
summary: Create Conversation
operationId: create-conversation
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Conversation'
x-stoplight:
id: pzaprkzjm0gv8
'422':
description: Request validation failure.
content:
application/json:
schema:
type: object
properties:
message:
type: string
errors:
type: object
properties:
bot_id:
type: array
items:
type: string
x-examples:
Example 1:
message: The selected bot id is invalid.
errors:
bot_id:
- The selected bot id is invalid.
examples:
Example 1:
value:
message: The selected bot id is invalid.
errors:
bot_id:
- The selected bot id is invalid.
description: Create new conversation
requestBody:
description: To use focus mode, add a list of document IDs to limit bot's knowledge base for this conversation.
content:
application/json:
schema:
type: object
required:
- name
- bot_id
properties:
name:
type: string
bot_id:
type: string
document_ids:
type: array
items:
type: string
maxItems: 1000
description: Only documents that exist in the folders the bot has access to are allowed. You can give bot access to all folders if you wish to limit documents from your whole knowledge base.
/conversations/{id}:
parameters:
- schema:
type: string
name: id
in: path
description: Id of the conversation
required: true
get:
summary: Get Conversation
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Conversation'
operationId: get-conversation
description: Fetch a conversation by its id.
parameters:
- schema:
type: string
enum:
- document_ids
in: query
name: includes
description: Lists document ids the conversation is focused on.
post:
summary: Update Conversation
operationId: update-conversation
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Conversation'
'422':
description: Request valiadtion failure.
content:
application/json:
schema:
type: object
properties:
message:
type: string
errors:
type: object
properties:
bot_id:
type: array
items:
type: string
x-examples:
Example 1:
message: The selected bot id is invalid.
errors:
bot_id:
- The selected bot id is invalid.
examples:
Example 1:
value:
message: The selected bot id is invalid.
errors:
bot_id:
- The selected bot id is invalid.
description: Update a conversation by its id.
requestBody:
description: To use focus mode, add a list of document IDs to limit bot's knowledge base for this conversation.
content:
application/json:
schema:
type: object
required:
- name
- bot_id
properties:
name:
type: string
bot_id:
type: string
document_ids:
type: array
items:
type: string
maxItems: 1000
description: Only documents that exist in the folders the bot has access to are allowed. You can give bot access to all folders if you wish to limit documents from your whole knowledge base.
delete:
summary: Delete Conversation
operationId: delete-conversation
responses:
'200':
description: OK
description: Delete a conversation by its id.
/documents:
get:
summary: List Documents
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Document'
meta:
$ref: '#/components/schemas/Pagination'
operationId: list-documents
description: Get all documents
parameters:
- schema:
type: string
in: query
name: folder_id
description: Id of the folder to list documents for.
- schema:
type: string
in: query
name: conversation_id
description: Id of the conversation to only list documents the conversation is focused on.
- schema:
type: string
in: query
name: keyword
description: Keyword to filter the list to documents that partially match the name.
post:
summary: Create Document
operationId: create-document
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Document'
'422':
description: Request validation failure.
content:
application/json:
schema:
type: object
properties:
message:
type: string
errors:
type: object
properties:
name:
type: array
items:
type: string
folder_id:
type: array
items:
type: string
content:
type: array
items:
type: string
description: |-
Create new document with text or html.
You can use a format like this with explicit start and end to get the best results:
```html
What do you call a bear with no teeth?
You'd call it a "gummy bear," just like those chewy, toothless candies that don't bite back.
Why did the math book look sad?
The math book seemed down in the dumps because it was overwhelmed by countless problems, equations, and algebraic mysteries.
What's orange and sounds like a parrot?
An item that's both orange and mimics a parrot's squawk is a "carrot," although you wouldn't expect vegetables to talk!
```
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
folder_id:
type: string
content:
type:
- string
- 'null'
description: Up to 768 KB of text or html only.
description: |-
> warn
> **You can send up to 768 KB of text or html in the `content` field, content larger than that needs to be uploaded as a file.**
/documents/file:
post:
summary: Create Document from File
operationId: create-document-from-file
responses:
'200':
description: Request is accepted and a document will be created after the file is converted into readable format, which can take from couple minutes to up to an hour.
'422':
description: Request validation errors.
content:
application/json:
schema:
type: object
properties:
message:
type: string
errors:
type: object
properties:
folder_id:
type: array
items:
type: string
key:
type: array
items:
type: string
file_size:
type: array
items:
type: string
file_name:
type: array
items:
type: string
content_type:
type: array
items:
type: string
'429':
description: Reached limit for pending file imports. Try again after old imports are finished, or they timeout after an hour due to file conversion failures.
content:
application/json:
schema:
type: object
properties:
message:
type: string
default: You have reached the limit of files that can be processed simultaneously. Please try again in few minutes.
description: |-
Create a document by uploading a file up to ==100 MB== in size.
> info
> Only these file types are allowed: `txt, md, rtf, pdf, ppt, pptx, pptm, doc, docx, docm`
requestBody:
content:
application/json:
schema:
type: object
properties:
folder_id:
type: string
key:
type: string
description: The key you receive after uploading a file. See [/uploads/signed-url](/operation/operation-get-uploads-signed-url)
description: ''
/documents/webpage:
post:
summary: Create Document from Webpage
operationId: create-document-from-webpage
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Document'
'400':
description: Webpage was in-accessible.
content:
application/json:
schema:
type: object
properties:
message:
type: string
'422':
description: Request validation errors.
content:
application/json:
schema:
type: object
properties:
message:
type: string
errors:
type: object
properties:
folder_id:
type: array
items:
type: string
key:
type: array
items:
type: string
file_size:
type: array
items:
type: string
file_name:
type: array
items:
type: string
content_type:
type: array
items:
type: string
description: |-
Create a document with a webpage URL.
> warn
> Webpage must be publicly accessible without a login. If request fails with 400 error code, check if your firewall is blocking requests.
requestBody:
content:
application/json:
schema:
type: object
properties:
folder_id:
type: string
url:
type: string
format: uri
description: Valid and publicly accessible webpage URL.
description: ''
parameters: []
/documents/{id}:
parameters:
- schema:
type: string
name: id
in: path
required: true
get:
summary: Get Document
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Document'
operationId: get-document
description: Get a document by its id.
delete:
summary: Delete Document
operationId: delete-document
responses:
'200':
description: OK
description: Delete document by id.
/folders:
get:
summary: List Folders
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Folder'
meta:
$ref: '#/components/schemas/Pagination'
operationId: list-folders
description: Get all folders
parameters:
- schema:
type: string
in: query
name: keyword
description: Keyword to filter the list to folders that partially match the name.
post:
summary: Create Folder
operationId: create-folder
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Folder'
'422':
description: Request validation failure.
content:
application/json:
schema:
type: object
properties:
message:
type: string
errors:
type: object
properties:
name:
type: array
items:
type: string
description: Create a folder
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
/folders/{id}:
parameters:
- schema:
type: string
name: id
in: path
required: true
get:
summary: Get Folder
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Folder'
operationId: get-folder
description: Get a folder by its id.
post:
summary: Update Folder
operationId: update-folder
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Folder'
description: Update a folder by its id.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
/messages:
get:
summary: List Messages
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
allOf:
- items:
allOf:
- $ref: '#/components/schemas/Message'
- type: object
description: |
Knowledge base sources used for this message generation. Present only when `includes=sources`.
properties:
sources:
type: object
properties:
data:
type: array
items:
anyOf:
- $ref: '#/components/schemas/SourceWritten'
- $ref: '#/components/schemas/SourceWebpage'
- $ref: '#/components/schemas/SourceFile'
usage:
$ref: '#/components/schemas/Usage'
meta:
$ref: '#/components/schemas/Pagination'
operationId: list-messages
description: ''
parameters:
- schema:
type: string
in: query
name: conversation_id
description: Id of the conversation to filter the list of messages to only that conversation.
- in: query
name: includes
description: Extra message attributes to include in the response.
schema:
type: string
enum:
- sources
- usage
example: sources,usage
post:
summary: Send Message
operationId: send-message
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Message'
'402':
description: When 30 days message limit of your subscription plan is reached.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example 1:
value:
message: You have reached the message limit for last 30 days, please wait till tomorrow or upgrade your plan.
'422':
description: Request validation failure.
content:
application/json:
schema:
type: object
properties:
message:
type: string
errors:
type: object
properties:
content:
type: array
items:
type: string
conversation_id:
type: array
items:
type: string
examples:
Example 1:
message: The content field is required. (and 1 more error)
errors:
content:
- The content field is required.
conversation_id:
- The selected conversation id is invalid.
'500':
description: Sometimes response generation fails due to service overload or network issues. You can fetch the list of messages for the conversation to get the generated error message, or you can use your own error message.
description: Send your message and receive the AI generated response.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
description: Content can be upto 2000 characters.
/messages/{id}:
parameters:
- schema:
type: string
name: id
in: path
required: true
get:
summary: Get Message
tags: []
operationId: get-message
description: Fetch a message by its id.
parameters:
- in: path
name: id
required: true
schema:
type: string
description: ID of the message.
- in: query
name: includes
description: Extra message attributes to include in the response.
schema:
type: string
enum:
- sources
- usage
example: sources,usage
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
allOf:
- $ref: '#/components/schemas/Message'
- type: object
properties:
sources:
type: object
properties:
data:
type: array
items:
anyOf:
- $ref: '#/components/schemas/SourceWritten'
- $ref: '#/components/schemas/SourceFile'
- $ref: '#/components/schemas/SourceWebpage'
usage:
$ref: '#/components/schemas/Usage'
/messages/stream:
post:
summary: Send Message for Stream
operationId: send-message-for-stream
responses:
'200':
description: When `redirect` is set to `false`
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
stream_url:
type: string
example: https://stream.aimcaiface.com/eyJpdiI6ImFyellpVWxScDBJdCtySGo0TzJtV3c9PSIsInZhbHVlIjoibW1VM1BDZkVZTGZ6T0ZrSG50dXhrQT09IiwibWFjIjoiZTA1NzYzMTgyMzUwOTU1MTUzMjYwZWY4NTI0MjcyODgxZjZkZDA1MTE3OWY2MjA5NmEzNTg3ZjdiZTM0NjAxNSIsInRhZyI6IiJ9
format: uri
'302':
description: When `redirect` is set to `true`.
headers:
Location:
schema:
type: string
description: URI to SSE stream.
'402':
description: When 30 days message limit of your subscription plan is reached.
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
Example 1:
value:
message: You have reached the message limit for last 30 days, please wait till tomorrow or upgrade your plan.
description: |
Send a message and get back a SSE (Server-Sent Events) stream for the AI response.
An example of how to handle SSE stream in Javascript.
```js
let message = ''
const evtSource = new EventSource('https://stream.aimcaiface.com/abc...123')
evtSource.onmessage = (event) => {
const data = event.data
if (data === '[END]') {
// Request is closed by our servers once `[END]` is sent,
// you must close the request otherwise the browser will keep retrying the URL.
evtSource.close()
} else if (data !== '[START]') {
message += JSON.parse(data).chunk
}
}
```
requestBody:
content:
application/json:
schema:
type: object
properties:
content:
type: string
description: Content can be upto 2000 characters.
conversation_id:
type: string
redirect:
type: boolean
default: true
description: By default, your request will be redirected to another url that will be a SSE stream. You can disable that and get the url in a json object instead.
writeOnly: true
/uploads/signed-url:
post:
summary: Get Upload URL
operationId: get-uploads-signed-url
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
url:
type: string
format: uri
description: AWS S3 signed upload URL, you can make a put request to upload the file.
key:
type: string
description: Key you can use for endpoints that require file uploads.
description: |-
Use this endpoint to get an AWS S3 signed upload url to upload your file to, store the returned key to use after file is uploaded successfully.
Javascript example of how to upload file to the URL you receive from this endpoint:
```js
try {
// Get the S3 URL to upload file to.
const authToken = ''
const response = await fetch('https://getcody.ai/api/v1/uploads/signed-url', {
method: 'POST',
headers: {
'Authorization': `Bearer ${authToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
content_type: 'text/plain',
file_name: 'knowledge.txt'
})
})
const { key, url } = (await response.json()).data
// Upload the File object to S3
await fetch(url, {
method: 'PUT',
headers: {
'Content-Type': 'text/plain',
},
body: file, // File object from Web API
})
// File is uploaded, now you can use the `key` you got from this endpoint.
} catch {
// Handle file upload failure.
}
```
requestBody:
content:
application/json:
schema:
type: object
properties:
file_name:
type: string
example: banana_shake.pdf
description: Original file name you want to upload, must contain the file extension.
content_type:
type: string
example: application/pdf
description: MIME content type of the file.
description: ''
components:
schemas:
Bot:
x-stoplight:
id: hg2hapcy1rflk
title: Bot
type: object
examples:
- id: yiu456ytyUjk
name: Factual Bot
created_at: 1672578000
properties:
id:
type: string
readOnly: true
name:
type: string
x-stoplight:
id: j0hktnnclu528
model:
type: string
enum:
- gpt-3.5-turbo
- gpt-4
description: LLM model used for all messages generated by this bot
readOnly: true
created_at:
type: integer
x-stoplight:
id: 17t92umtqgisz
format: int64
description: Unix timestamp in seconds
readOnly: true
Conversation:
title: Conversation
x-stoplight:
id: 2ehcekowg6tes
type: object
properties:
id:
type: string
x-stoplight:
id: wpuuqd2quv504
readOnly: true
name:
type: string
x-stoplight:
id: 7uwqxsu7ukajc
bot_id:
type: string
x-stoplight:
id: mzbrej94uek0w
created_at:
type: integer
x-stoplight:
id: wxoiv5grkzybv
format: int64
description: Unix timestamp in seconds
readOnly: true
required:
- name
- bot_id
Document:
title: Document
x-stoplight:
id: ahzebu3mklyxr
type: object
properties:
id:
type: string
readOnly: true
name:
type: string
status:
type: string
enum:
- syncing
- synced
- sync_failed
description: Learning status of the document, Synced means the document has been learned.
readOnly: true
content_url:
type: string
format: url
description: URL to download the content as html file.
readOnly: true
folder_id:
type: string
created_at:
type: integer
format: int64
readOnly: true
Folder:
title: Folder
x-stoplight:
id: d23lmlbq9pu0g
type: object
properties:
id:
type: string
readOnly: true
name:
type: string
created_at:
type: integer
format: int64
readOnly: true
Message:
title: Message
x-stoplight:
id: jt969pyqv4hs6
type: object
properties:
id:
type: string
readOnly: true
content:
type: string
conversation_id:
type: string
machine:
type: boolean
description: This is true for all LLM generated messages.
readOnly: true
failed_responding:
type: boolean
description: This will be true if the response generation for a message had failed.
readOnly: true
flagged:
type: boolean
description: This is true when message is in violation of OpenAI usage policy.
readOnly: true
created_at:
type: integer
format: int64
description: Unix timestamp in seconds
readOnly: true
required:
- content
- conversation_id
Pagination:
x-stoplight:
id: 2l90y2wwhkgcg
title: pagination
type: object
properties:
pagination:
type: object
x-stoplight:
id: jlidjic6qrz3a
properties:
count:
type: integer
x-stoplight:
id: mpck95r01brgj
total:
type: integer
x-stoplight:
id: yr28ehwbgnsr5
per_page:
type: integer
x-stoplight:
id: gu5mqmycjhgxg
total_pages:
type: integer
x-stoplight:
id: z7mkku4hwc4rp
next_page:
type:
- integer
- 'null'
x-stoplight:
id: ppfxl7ccx383i
previous_page:
type:
- integer
- 'null'
x-stoplight:
id: 0zwri5j20lehj
SourceWritten:
title: Source Written
x-stoplight:
id: carw2f2uml9it
type: object
properties:
type:
type: string
default: written
readOnly: true
document_id:
type: string
document_name:
type: string
document_url:
type: string
format: uri
created_at:
type: integer
format: int64
examples:
- type: written
document_id: Jw31Pv6PMmro
document_name: How to bake cake
document_url: https://getcody.ai/directories/1/documents/1
created_at: 1693013531
SourceWebpage:
title: Source Webpage
type: object
examples:
- type: webpage
document_id: Jw31Pv6PMmro
document_name: How to bake cake
document_url: https://getcody.ai/directories/1/documents/1
webpage_url: https://example.com/bakeacake
created_at: 1693013531
x-stoplight:
id: e364059c4a92e
properties:
type:
type: string
default: webpage
readOnly: true
document_id:
type: string
document_name:
type: string
document_url:
type: string
format: uri
webpage_url:
type: string
format: uri
created_at:
type: integer
format: int64
SourceFile:
title: Source File
type: object
examples:
- type: file
document_id: Jw31Pv6PMmro
document_name: How to bake cake
document_url: https://getcody.ai/directories/1/documents/1
file_name: bakeacake.pdf
created_at: 1693013531
x-stoplight:
id: 326c57628f61c
properties:
type:
type: string
default: file
readOnly: true
document_id:
type: string
document_name:
type: string
document_url:
type: string
format: uri
file_name:
type: string
created_at:
type: integer
format: int64
description: ''
Usage:
type: object
description: Token and credit usage information for the message.
properties:
tokens:
type: integer
format: int64
description: Token usage is calculated using a tiered step model. Usage is rounded up to the nearest 8,000 increment.
credits:
type: number
format: float
description: Cost of this message in credits.
example:
tokens: 8000
credits: 0.5
securitySchemes:
APIKey:
type: http
in: header
scheme: bearer
description: Keep this API key secret, do not use it directly on the client side, use a backend server as a proxy to our API.
x-stoplight:
id: ifw84jjq89dql
x-topics:
- title: Authentication
content: |
Cody AI API uses API keys for authentication. Visit your [API Keys](https://getcody.ai/settings/api) page to retrieve the API key you'll use in your requests.
**Your API key is a secret!** Do not share it with others or expose it in any client-side code (browsers, apps). Requests must be proxied through your own backend server where your API key can be securely stored.
All API requests should include your API key in an Authorization HTTP header as follows:
```
Authorization: Bearer API_KEY
```
- title: Rate Limiting
content: |
API Rate Limits are in place to protect Cody AI from API traffic spikes that could put our services at risk. We therefore measure the amount of requests sent to the API in order to throttle these when they surpass the amount allowed. We will respond with '429 Too Many Requests' and the following headers:
| Header | Explanation |
|-----------------------|-----------------------------------------------------------------------------------------------|
| x-ratelimit-limit | Maximum number of requests allowed per minute. |
| x-ratelimit-remaining | Number of requests left in the current time. |
| x-ratelimit-reset | Time when the number of requests will be reset to the maximum limit. Shown as UNIX timestamp. |
| retry-after | Number of seconds to wait before retrying your request. |
You can view your account rate limits on your account [API Keys](https://getcody.ai/settings/api) page.
- title: Focus Mode
content: |
In Focus Mode, Cody will focus entirely on the documents you've selected for generating responses, rather than pulling data from all documents in your bots' knowledge base. This allows for macro-adjustments to bots' knowledge base. The feature is especially useful for:
- Summarization
- Rephrasing
- Outlining
- Review
- And much more...
**To use Focus mode, you have to specify the document IDs when creating or updating a conversation.**