API docs by Redocly

search.buildscale.ai API (v1)

Download OpenAPI specification:

Quan Hua: quan@buildscale.ai URL: https://search.buildscale.ai

API for search.buildscale.ai, a specialized semantic search engine. Manages users, repositories, versioned documents composed of deduplicated chunks, tags, and provides semantic search capabilities with secure access to content via presigned URLs. Includes endpoints for user authentication and authorization using JWT.

Authentication

Operations related to user registration, login, and token management

Register a new user

Creates a new user account. Requires unique username and email. Passwords are hashed securely.

Request Body schema: application/json
required

User registration details

username
required
string [ 3 .. 50 ] characters ^[a-zA-Z0-9_]+$

Unique username for the account.

email
required
string <email>

Unique email address for the account.

password
required
string <password> >= 8 characters

User's password (will be hashed). Minimum length 8, requires uppercase, lowercase, number, symbol recommended.

Responses

Request samples

Content type
application/json
{
  • "username": "new_user",
  • "email": "new_user@example.com",
  • "password": "StrongP@ssword123"
}

Response samples

Content type
application/json
{
  • "user_id": "uuid-user-12345",
  • "username": "new_user",
  • "email": "new_user@example.com",
  • "created_at": "2025-05-01T09:38:00Z"
}

Login user and obtain tokens

Authenticates a user with email and password, returning JWT access and refresh tokens upon success.

Request Body schema: application/json
required

User login credentials

email
required
string <email>

User's registered email address.

password
required
string <password>

User's password.

Responses

Request samples

Content type
application/json
{
  • "email": "new_user@example.com",
  • "password": "StrongP@ssword123"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi...",
  • "user": {
    }
}

Refresh JWT access token

Uses a valid refresh token to obtain a new access token (and potentially a new refresh token).

Request Body schema: application/json
required

Refresh token to be validated

refresh_token
required
string

The refresh token obtained during login.

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi..."
}

Response samples

Content type
application/json
{
  • "access_token": "new-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "refresh_token": "possibly-new-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi..."
}

Repositories

Operations related to repositories

Create a new repository

Creates a new repository owned by the authenticated user. Requires Bearer token.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Repository details

name
required
string

Name for the new repository (unique per user).

description
string or null

Optional description for the repository.

is_public
boolean
Default: false

Whether the repository should be publicly accessible.

tags
Array of strings

Optional initial list of repository tags.

Responses

Request samples

Content type
application/json
{
  • "name": "my-research-project",
  • "description": "Repository for AI research papers.",
  • "is_public": false,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "repository_id": "b349ae61-b973-4c6c-a5e0-89183ba99ff3",
  • "owner_username": "string",
  • "repository_name": "string",
  • "description": "string",
  • "is_public": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "tags": [
    ]
}

List accessible repositories

Lists repositories accessible to the authenticated user (owned or shared), with pagination. Requires Bearer token.

Authorizations:
BearerAuth
query Parameters
page
integer <int32> >= 1
Default: 1

Page number to retrieve (starts at 1).

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0
}

Get repository details

Retrieves details for a specific repository if the user has access. Requires Bearer token for private repos. Public repos might not require auth depending on implementation.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

Responses

Response samples

Content type
application/json
{
  • "repository_id": "b349ae61-b973-4c6c-a5e0-89183ba99ff3",
  • "owner_username": "string",
  • "repository_name": "string",
  • "description": "string",
  • "is_public": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "tags": [
    ]
}

Update repository details

Updates mutable details of a repository (like description, public status). Requires ownership or specific permissions via Bearer token.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

Request Body schema: application/json
required

Fields to update

description
string or null

New description for the repository.

is_public
boolean

New visibility setting for the repository.

Responses

Request samples

Content type
application/json
{
  • "description": "Updated description.",
  • "is_public": true
}

Response samples

Content type
application/json
{
  • "repository_id": "b349ae61-b973-4c6c-a5e0-89183ba99ff3",
  • "owner_username": "string",
  • "repository_name": "string",
  • "description": "string",
  • "is_public": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "tags": [
    ]
}

Delete repository

Deletes a repository and all its associated documents and versions. Requires ownership via Bearer token. This operation is irreversible.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

Responses

Response samples

Content type
application/json
{
  • "error": "UNAUTHENTICATED",
  • "message": "Authentication token is required."
}

List documents in repository

Retrieves a paginated list of logical documents within a specific repository. Requires read access via Bearer token.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

query Parameters
page
integer <int32> >= 1
Default: 1

Page number to retrieve (starts at 1).

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0
}

Create document in repository

Creates a new logical document and its initial version based on provided content. Requires write access via Bearer token.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

Request Body schema: multipart/form-data
required

Initial document content and metadata

title
string

Initial title for the first version.

doc_tags
Array of strings

Optional initial document tags for the first version.

content_url
string <uri>

URL of the content to ingest (use instead of file).

content_file
string <binary>

File containing the content to ingest (use instead of URL).

Responses

Response samples

Content type
application/json
{
  • "document": {
    },
  • "initial_version": {
    }
}

List repository tags

Retrieves the list of tags associated with a specific repository. Requires read access.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Add tag to repository

Adds a tag to a specific repository. Requires write access. Idempotent (adding existing tag succeeds).

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

Request Body schema: application/json
required
tag_name
required
string

Responses

Request samples

Content type
application/json
{
  • "tag_name": "new-tag"
}

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Remove tag from repository

Removes a specific tag from a repository. Requires write access. Idempotent.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

tag_name
required
string

The name of the repository tag.

Responses

Response samples

Content type
application/json
{
  • "error": "UNAUTHENTICATED",
  • "message": "Authentication token is required."
}

Documents

Operations related to logical documents and their versions

List documents in repository

Retrieves a paginated list of logical documents within a specific repository. Requires read access via Bearer token.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

query Parameters
page
integer <int32> >= 1
Default: 1

Page number to retrieve (starts at 1).

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0
}

Create document in repository

Creates a new logical document and its initial version based on provided content. Requires write access via Bearer token.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

Request Body schema: multipart/form-data
required

Initial document content and metadata

title
string

Initial title for the first version.

doc_tags
Array of strings

Optional initial document tags for the first version.

content_url
string <uri>

URL of the content to ingest (use instead of file).

content_file
string <binary>

File containing the content to ingest (use instead of URL).

Responses

Response samples

Content type
application/json
{
  • "document": {
    },
  • "initial_version": {
    }
}

Get logical document info

Retrieves information about the logical document entity, including its current version ID. Requires read access via repository.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

The UUID identifier of the logical document.

Responses

Response samples

Content type
application/json
{
  • "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
  • "repository_id": "b349ae61-b973-4c6c-a5e0-89183ba99ff3",
  • "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  • "created_at": "2019-08-24T14:15:22Z",
  • "current_version": {
    }
}

Delete logical document

Deletes the logical document and all its associated versions and data. Irreversible. Requires ownership or specific permissions.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

The UUID identifier of the logical document.

Responses

Response samples

Content type
application/json
{
  • "error": "UNAUTHENTICATED",
  • "message": "Authentication token is required."
}

List document versions

Retrieves a paginated list of versions for a specific logical document, usually ordered newest first. Requires read access.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

The UUID identifier of the logical document.

query Parameters
page
integer <int32> >= 1
Default: 1

Page number to retrieve (starts at 1).

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0
}

Update document content (create new version)

Submits new content for a document, which triggers the creation of a new document version. Requires write access.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

The UUID identifier of the logical document.

Request Body schema: multipart/form-data
required

New content and optional version metadata

title
string

Optional title for the new version. If omitted, might inherit or be blank.

doc_tags
Array of strings

Optional document tags for the new version.

content_url
string <uri>

URL of the new content (use instead of file).

content_file
string <binary>

File containing the new content (use instead of URL).

Responses

Response samples

Content type
application/json
{
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  • "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
  • "document_content_hash": "string",
  • "s3_metadata_url_path": "string",
  • "title": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "creator_username": "string",
  • "doc_tags": [
    ]
}

Versions

Operations related to specific document versions and their content access

List document versions

Retrieves a paginated list of versions for a specific logical document, usually ordered newest first. Requires read access.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

The UUID identifier of the logical document.

query Parameters
page
integer <int32> >= 1
Default: 1

Page number to retrieve (starts at 1).

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items to return per page.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0
}

Update document content (create new version)

Submits new content for a document, which triggers the creation of a new document version. Requires write access.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

The UUID identifier of the logical document.

Request Body schema: multipart/form-data
required

New content and optional version metadata

title
string

Optional title for the new version. If omitted, might inherit or be blank.

doc_tags
Array of strings

Optional document tags for the new version.

content_url
string <uri>

URL of the new content (use instead of file).

content_file
string <binary>

File containing the new content (use instead of URL).

Responses

Response samples

Content type
application/json
{
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  • "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
  • "document_content_hash": "string",
  • "s3_metadata_url_path": "string",
  • "title": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "creator_username": "string",
  • "doc_tags": [
    ]
}

Get specific version metadata

Retrieves metadata specific to an immutable document version. Requires read access via repository.

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

The UUID identifier of the specific document version.

Responses

Response samples

Content type
application/json
{
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  • "document_id": "b792e8ae-2cb4-4209-85b9-32be4c2fcdd6",
  • "document_content_hash": "string",
  • "s3_metadata_url_path": "string",
  • "title": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "creator_username": "string",
  • "doc_tags": [
    ]
}

Get presigned URL for metadata.json

Performs an authorization check and returns a short-lived presigned URL to download the metadata.json manifest file for this version directly from S3/CDN.

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

The UUID identifier of the specific document version.

Responses

Response samples

Get presigned URL for a single chunk

Performs an authorization check (can user access this version?) and returns a short-lived presigned URL to download the raw text data for a specific chunk belonging to this version directly from S3/CDN.

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

The UUID identifier of the specific document version.

chunk_hash
required
string <sha256-hex>

The SHA-256 hash identifier of the chunk.

Responses

Response samples

Batch get presigned URLs for chunks

Performs one authorization check for the version and returns multiple short-lived presigned URLs for a requested list of chunk hashes belonging to this version. Efficiently retrieves access URLs needed for document reconstruction.

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

The UUID identifier of the specific document version.

Request Body schema: application/json
required

List of chunk hashes to get URLs for.

chunk_hashes
required
Array of strings <sha256-hex> [ items <sha256-hex > ]

Responses

Request samples

Content type
application/json
{
  • "chunk_hashes": [
    ]
}

Response samples

Content type
application/json
{}

List version tags

Retrieves the list of document tags associated with a specific version. Requires read access.

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

The UUID identifier of the specific document version.

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Add tag to version

Adds a document tag to a specific version. Requires write access to the parent document/repo. Idempotent.

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

The UUID identifier of the specific document version.

Request Body schema: application/json
required
tag_name
required
string

Responses

Request samples

Content type
application/json
{
  • "tag_name": "reviewed"
}

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Remove tag from version

Removes a specific document tag from a version. Requires write access. Idempotent.

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

The UUID identifier of the specific document version.

tag_name
required
string

The name of the document tag.

Responses

Response samples

Content type
application/json
{
  • "error": "UNAUTHENTICATED",
  • "message": "Authentication token is required."
}

Search

Semantic search operations

Perform semantic search

Executes a semantic search query against chunks within accessible repositories, based on provided text query and filters. Returns relevant chunks with context and presigned URLs for immediate snippet access. Results are paginated.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Search query and filters

query
required
string

The natural language query for semantic search.

object
limit
integer <int32> [ 1 .. 100 ]
Default: 10

Maximum number of results (chunks) to return.

page
integer <int32> >= 1
Default: 1

Page number for search results pagination.

pageSize
integer <int32> [ 1 .. 100 ]
Default: 10

Number of results per page.

Responses

Request samples

Content type
application/json
{
  • "query": "How does content defined chunking improve deduplication?",
  • "filters": {
    },
  • "limit": 10,
  • "page": 1,
  • "pageSize": 10
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "pageSize": 0
}

Tags

Operations related to repository and document tags

List repository tags

Retrieves the list of tags associated with a specific repository. Requires read access.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Add tag to repository

Adds a tag to a specific repository. Requires write access. Idempotent (adding existing tag succeeds).

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

Request Body schema: application/json
required
tag_name
required
string

Responses

Request samples

Content type
application/json
{
  • "tag_name": "new-tag"
}

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Remove tag from repository

Removes a specific tag from a repository. Requires write access. Idempotent.

Authorizations:
BearerAuth
path Parameters
repository_id
required
string <uuid>

The UUID identifier of the repository.

tag_name
required
string

The name of the repository tag.

Responses

Response samples

Content type
application/json
{
  • "error": "UNAUTHENTICATED",
  • "message": "Authentication token is required."
}

List version tags

Retrieves the list of document tags associated with a specific version. Requires read access.

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

The UUID identifier of the specific document version.

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Add tag to version

Adds a document tag to a specific version. Requires write access to the parent document/repo. Idempotent.

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

The UUID identifier of the specific document version.

Request Body schema: application/json
required
tag_name
required
string

Responses

Request samples

Content type
application/json
{
  • "tag_name": "reviewed"
}

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Remove tag from version

Removes a specific document tag from a version. Requires write access. Idempotent.

Authorizations:
BearerAuth
path Parameters
version_id
required
string <uuid>

The UUID identifier of the specific document version.

tag_name
required
string

The name of the document tag.

Responses

Response samples

Content type
application/json
{
  • "error": "UNAUTHENTICATED",
  • "message": "Authentication token is required."
}

List all used repository tags

Retrieves a paginated list of unique repository tag names used across all accessible repositories. Supports optional query filter.

Authorizations:
BearerAuth
query Parameters
page
integer <int32> >= 1
Default: 1

Page number to retrieve (starts at 1).

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items to return per page.

query
string

Filter tags containing this substring.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 150,
  • "page": 1,
  • "pageSize": 20
}

List all used document tags

Retrieves a paginated list of unique document tag names used across all accessible document versions. Supports optional query filter.

Authorizations:
BearerAuth
query Parameters
page
integer <int32> >= 1
Default: 1

Page number to retrieve (starts at 1).

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items to return per page.

query
string

Filter tags containing this substring.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 320,
  • "page": 1,
  • "pageSize": 20
}

Users

Operations related to user information

Get current user info

Retrieves profile information for the currently authenticated user. Requires Bearer token.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "username": "string",
  • "email": "user@example.com"
}

Get public user info

Retrieves publicly available information for a specific user. No token required.

path Parameters
username
required
string

Username of the user to retrieve.

Responses

Response samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "username": "string"
}