openapi: "3.0.4"
info:
title: ragithub
description: backend for ragithub
version: 0.4.0
paths:
/{user}/{repo}/index/:
get:
operationId: GetIndex
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
responses:
'200':
description: content of `index.json` file of the repository.
content:
application/json:
schema:
type: object
/{user}/{repo}/config/{config}:
get:
operationId: GetConfig
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: config
in: path
required: true
description: name of the config file (api, build or query)
schema:
type: string
responses:
'200':
description: content of the config file.
content:
application/json:
schema:
type: object
/{user}/{repo}/prompt/{prompt}:
get:
operationId: GetPrompt
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: prompt
in: path
required: true
description: name of the prompt file (a file in `.ragit/prompts`, without an extension)
schema:
type: string
responses:
'200':
description: content of the prompt file.
content:
text/plain:
schema:
type: string
/{user}/{repo}/uid:
get:
operationId: GetRepoUid
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
responses:
'200':
description: uid of the repository
content:
text/plain:
schema:
type: string
description: uid of the repository
/{user}/{repo}/chunk-count:
get:
operationId: GetChunkCount
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
responses:
'200':
description: number of chunks in the repository
content:
application/json:
schema:
type: integer
format: int64
/{user}/{repo}/chunk-list/{chunk-prefix}:
get:
operationId: GetChunkList
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: chunk-prefix
in: path
required: true
description: first 2 characters of the uid of the chunk
schema:
type: string
responses:
'200':
description: a list of chunk uids that start with the prefix
content:
application/json:
schema:
type: array
items:
type: string
/{user}/{repo}/chunk-list/:
get:
operationId: GetChunkListAll
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
responses:
'200':
description: a full list of chunk uids of the knowledge-base
content:
application/json:
schema:
type: array
items:
type: string
/{user}/{repo}/chunk/{chunk-uid}:
get:
operationId: GetChunk
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: chunk-uid
in: path
required: true
description: uid of the chunk
schema:
type: string
responses:
'200':
description: the chunk
content:
application/json:
schema:
$ref: '#/components/schemas/ChunkDetail'
/{user}/{repo}/image-list/{image-prefix}:
get:
operationId: GetImageList
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: image-prefix
in: path
required: true
description: first 2 characters of the uid of the image
schema:
type: string
responses:
'200':
description: a list of image uids that start with the prefix
content:
application/json:
schema:
type: array
items:
type: string
/{user}/{repo}/image/{image-uid}:
get:
operationId: GetImage
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: image-uid
in: path
required: true
description: uid of the image
schema:
type: string
responses:
'200':
description: the image
content:
image/png:
schema:
type: string
format: binary
/{user}/{repo}/image-desc/{image-uid}:
get:
operationId: GetImageDescription
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: image-uid
in: path
required: true
description: uid of the image
schema:
type: string
responses:
'200':
description: description of the image
content:
application/json:
schema:
type: object
properties:
extracted_text:
type: string
explanation:
type: string
/{user}/{repo}/file-content:
get:
description: get a content of a file or a directory
operationId: GetFileContent
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: path
in: query
description: path of a file or a directory
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
format: int32
default: 100
- name: offset
in: query
required: false
schema:
type: integer
format: int32
default: 0
responses:
'200':
description: ""
content:
application/json:
schema:
$ref: '#/components/schemas/FileDetail'
/{user}/{repo}/cat-file/{uid}:
get:
description: If you want to get a content of a file or a chunk, I recommend you use `/{user}/{repo}/content/{uid}` api instead of this. This api exists for historical reasons.
operationId: GetCatFile
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: uid
in: path
required: true
description: uid of a file or a chunk
schema:
type: string
responses:
'200':
description: It's exactly same as running `rag cat-file` with the uid.
content:
text/plain:
schema:
type: string
/{user}/{repo}/content/{uid}:
get:
description: It's useful when you want to render a content of a chunk or a file. It doesn't give you the content of the original file, but a version that LLMs actually see when they RAG.
operationId: GetContent
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: uid
in: path
required: true
description: uid of a file or a chunk
schema:
type: string
responses:
'200':
description: ""
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MultiModalContent'
/{user}/{repo}/archive-list:
get:
description: Ragit client uses this API to clone knowledge-bases.
/{user}/{repo}/archive/{archive-id}:
get:
description: Ragit client uses this API to clone knowledge-bases.
/{user}/{repo}/meta:
get:
operationId: GetMeta
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
responses:
'200':
description: meta.json
content:
application/json:
schema:
type: object
additionalProperties:
type: string
/{user}/{repo}/meta/{key}:
get:
operationId: GetMetaByKey
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: key
in: path
required: true
description: metadata key
schema:
type: string
responses:
'200':
description: metadata value
content:
application/json:
schema:
type: string
nullable: true
/{user}/{repo}/version:
get:
operationId: GetRepoVersion
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
responses:
'200':
description: version of the repository
content:
text/plain:
schema:
type: string
example: "0.4.0-dev"
/{user}/{repo}/build-search-index:
post:
description: "This is the same as running `rag ii-build` in a local repository. It is helpful when you want to search for chunks in the server."
operationId: PostBuildSearchIndex
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
responses:
'200':
description: "It doesn't return anything."
/{user}/{repo}/search:
get:
description: search for chunks in this repository. There's no `sort-by` or `sort-ord` option. If you provide `query` parameter, it sorts the result by tfidf-score. Otherwise, it uses `chunk.sortable_string()` methods which usually sorts the chunks by file name.
operationId: searchChunk
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: file
in: query
description: search for chunks that belong to this file or directory
schema:
type: string
- name: uid
in: query
description: search for chunks whose uid starts or equal to this parameter
schema:
type: string
- name: query
in: query
description: full-text search on chunks.
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
format: int32
default: 100
- name: offset
in: query
required: false
schema:
type: integer
format: int32
default: 0
responses:
'200':
description: ""
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChunkDetail'
/{user}/{repo}/begin-push:
post:
description: Ragit client uses this API to push knowledge-bases.
/{user}/{repo}/archive:
description: Ragit client uses this API to push knowledge-bases.
/{user}/{repo}/finalize-push:
description: Ragit client uses this API to push knowledge-bases.
/{user}/{repo}/traffic:
get:
description: It gives you numbers of push/clone of this repository.
operationId: GetTraffic
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
responses:
'200':
description: "The response has 15 keys: \"all\" and 14 dates. \"all\" has the number of push/clone for all time. Each date has the number of push/clone at that date. A date has format \"2025-06-01\". It gives 14 most recent days."
content:
application/json:
schema:
type: object
additionalProperties:
type: object
properties:
push:
type: integer
format: int64
clone:
type: integer
format: int64
/{user}/{repo}/chat/{chat-id}:
get:
operationId: getChat
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
- name: chat-id
in: path
required: true
description: chat-id
schema:
type: integer
format: int32
responses:
'200':
description: a chat with history
content:
application/json:
schema:
$ref: '#/components/schemas/ChatWithHistory'
post:
description: Ragithub's chat interface is WIP and we're not working on it anymore.
/{user}/{repo}/chat-list:
get:
description: Ragithub's chat interface is WIP and we're not working on it anymore.
post:
description: Ragithub's chat interface is WIP and we're not working on it anymore.
/health:
get:
operationId: GetHealth
responses:
'200':
description: ""
/version:
get:
operationId: GetServerVersion
responses:
'200':
description: version of the server
content:
text/plain:
schema:
type: string
example: "0.4.0-dev"
/user-list:
get:
operationId: GetUserList
parameters:
- name: limit
in: query
required: false
schema:
type: integer
format: int32
default: 50
- name: offset
in: query
required: false
schema:
type: integer
format: int32
default: 0
responses:
'200':
description: ""
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserSimple'
post:
description: It creates a new user. If it's the first user, the user becomes an admin.
operationId: CreateUser
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreation'
responses:
'200':
description: The response has no body.
/user-list/{user}:
get:
operationId: GetUser
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
format: int32
default: 50
- name: offset
in: query
required: false
schema:
type: integer
format: int32
default: 0
responses:
'200':
description: ""
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserDetail'
/user-list/{user}/ai-model-list:
get:
description: This was intended for chat interface, but the plan has changed and we're not developing chat interface for ragithub. Please use `GET /ai-model-list` API instead.
put:
description: This was intended for chat interface, but the plan has changed and we're not developing chat interface for ragithub. Please use `PUT /ai-model-list` API instead.
/user-list/{user}/api-key-list:
get:
operationId: GetApiKeyList
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
responses:
'200':
description: ""
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiKey'
post:
operationId: CreateApiKey
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyCreation'
responses:
'200':
description: ""
content:
text/plain:
schema:
type: string
description: created api key
/repo-list/{user}:
get:
operationId: GetRepoList
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
format: int32
default: 50
- name: offset
in: query
required: false
schema:
type: integer
format: int32
default: 0
responses:
'200':
description: ""
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Repository'
post:
operationId: CreateRepo
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RepoCreation'
responses:
'200':
description: ""
content:
application/json:
schema:
type: integer
format: int32
description: repo id
/repo-list/{user}/{repo}:
get:
operationId: GetRepo
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
responses:
'200':
description: ""
content:
application/json:
schema:
$ref: '$/components/schemas/Repository'
put:
operationId: UpdateRepo
parameters:
- name: user
in: path
required: true
description: user id
schema:
type: string
- name: repo
in: path
required: true
description: repository name
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RepoUpdate'
responses:
'200':
description: ""
/ai-model-list:
get:
description: It gets the list of ai models.
operationId: GetAiModelList
parameters:
- name: name
in: query
required: false
description: name of the ai model
schema:
type: string
- name: tags
in: query
required: false
description: comma-separated string of tags
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
format: int32
default: 50
- name: offset
in: query
required: false
schema:
type: integer
format: int32
default: 0
responses:
'200':
description: ""
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AiModel'
put:
description: It updates or inserts an ai model.
operationId: PutAiModelList
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AiModelCreation'
components:
schemas:
UserDetail:
type: object
properties:
id:
type: string
name:
type: string
nullable: true
email:
type: string
nullable: true
readme:
type: string
nullable: true
created_at:
type: string
format: date-time
last_login_at:
type: string
format: date-time
UserSimple:
type: object
properties:
id:
type: string
name:
type: string
nullable: true
email:
type: string
nullable: true
created_at:
type: string
format: date-time
last_login_at:
type: string
format: date-time
UserCreation:
type: object
properties:
id:
type: string
name:
type: string
nullable: true
email:
type: string
nullable: true
password:
type: string
public:
type: boolean
Repository:
type: object
properties:
id:
type: integer
format: int32
name:
type: string
owner:
type: string
description:
type: string
nullable: true
website:
type: string
nullable: true
stars:
type: integer
format: int32
repo_size:
type: integer
format: int64
description: sum of the sizes of its archives, in bytes
tags:
type: array
items:
type: string
created_at:
type: string
format: date-time
pushed_at:
type: string
format: date-time
nullable: true
updated_at:
type: string
format: date-time
RepoCreation:
type: object
properties:
name:
type: string
description:
type: string
nullable: true
website:
type: string
nullable: true
tags:
type: array
items:
type: string
public_read:
type: boolean
public_write:
type: boolean
public_clone:
type: boolean
public_push:
type: boolean
public_chat:
type: boolean
RepoUpdate:
type: object
properties:
description:
type: string
nullable: true
website:
type: string
nullable: true
tags:
type: array
items:
type: string
public_read:
type: boolean
public_write:
type: boolean
public_clone:
type: boolean
public_push:
type: boolean
public_chat:
type: boolean
ChunkDetail:
type: object
properties:
uid:
type: string
data:
type: array
items:
$ref: '#/components/schemas/MultiModalContent'
image_uids:
type: array
items:
type: string
description: uids of images
title:
type: string
summary:
type: string
file:
type: string
description: File path that the chunk belongs to. It's null if the chunk is not from a file.
nullable: true
file_index:
type: integer
description: It's null if and only if `file` is null. It's the index of the chunk in the file.
nullable: true
page_no:
type: integer
description: Some chunks (e.g. chunks from pdfs) have page numbers.
nullable: true
timestamp:
type: integer
model:
type: string
description: AI model that created the chunk.
ragit_version:
type: string
example: "0.4.0-dev"
MultiModalContent:
description: "Ragit is multimodal: a chunk consists of texts and images. Ragit uses this schema to represent a multimodal content in json."
type: object
properties:
type:
type: string
enum:
- Text
- Image
content:
type: string
description: content of `Text` variant
uid:
type: string
description: uid of `Image` variant
FileDetail:
type: object
properties:
type:
type: string
enum:
- File
- Directory
path:
type: string
content:
type: array
nullable: true
description: It's null if the path is a directory.
items:
$ref: '#/components/schemas/MultiModalContent'
uid:
type: string
nullable: true
description: It's null if the path is a directory.
chunks:
type: array
nullable: true
description: It's null if the path is a directory. It's uids of chunks that belong to this file.
items:
type: string
children:
type: array
nullable: true
description: It's null if the path is a file. It's files and directories that belong to this directory.
items:
$ref: '#/components/schemas/FileSimple'
FileSimple:
type: object
properties:
type:
type: string
enum:
- File
- Directory
path:
type: string
ChatWithHistory:
type: object
properties:
id:
type: integer
format: int32
repo_id:
type: integer
format: int32
title:
type: string
nullable: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
history:
type: array
items:
$ref: '#/components/schemas/ChatHistory'
ChatHistory:
type: object
properties:
query:
type: string
response:
type: string
user:
type: string
model:
type: string
chunk_uids:
type: array
items:
type: string
multi_turn_schema:
type: object
description: Ragit re-writes queries when there are multiple turns. It's the actual query that's used for RAG.
nullable: true
properties:
is_query:
type: boolean
in_context:
type: boolean
query:
type: string
created_at:
type: string
format: date-time
ApiKey:
type: object
properties:
api_key_preview:
type: string
description: first 9 characters of the api key
name:
type: string
expire:
type: string
format: date-time
ApiKeyCreation:
type: object
properties:
name:
type: string
expire_after:
type: integer
description: days
password:
type: string
description: user password in plain text
AiModel:
type: object
properties:
id:
type: string
description: "It's a unique identifier of the model. It's a hash value of `name` + `api_name` + `api_provider` + `api_url`."
name:
type: string
description: It's a name for humans.
api_name:
type: string
description: It's a name for apis.
api_provider:
type: string
description: openai | anthropic | cohere | google
api_url:
type: string
nullable: true
description: openai-compatible apis need this field. If it's not set, it uses the default url of each api provider.
can_read_images:
type: boolean
input_price:
type: number
format: double
description: dollars per 1 million input tokens
output_price:
type: number
format: double
description: dollars per 1 million output tokens
explanation:
type: string
nullable: true
api_env_var:
type: string
nullable: true
description: Ragit uses this environment variable for api key.
example: OPENAI_API_KEY
tags:
type: array
description: It helps users find models more easily in ragithub.
items:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
AiModelCreation:
type: object
properties:
name:
type: string
description: It's a name for humans.
api_name:
type: string
description: It's a name for apis.
api_provider:
type: string
description: openai | anthropic | cohere | google
api_url:
type: string
nullable: true
description: openai-compatible apis need this field. If it's not set, it uses the default url of each api provider.
can_read_images:
type: boolean
input_price:
type: number
format: double
description: dollars per 1 million input tokens
output_price:
type: number
format: double
description: dollars per 1 million output tokens
explanation:
type: string
nullable: true
api_env_var:
type: string
nullable: true
description: Ragit uses this environment variable for api key.
example: OPENAI_API_KEY
tags:
type: array
description: It helps users find models more easily in ragithub.
items:
type: string