日本語 | English
API docs by Redocly

monoshiri.ai API (1.0.0)

Download OpenAPI specification:

The external API for monoshiri.ai. Upload internal documents and programmatically access AI-powered search and Q&A features.

Authentication Flow

Step 1: Obtain a token (password grant)

POST /v1/auth/token
Content-Type: application/json

{
  "grant_type": "password",
  "username": "admin@example.com",
  "password": "yourpassword",
  "team_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Use the access_token from the response in subsequent requests.

Step 2: Make authenticated requests

GET /v1/teams/{teamId}/folders
Authorization: Bearer <access_token>
X-Team-Id: <team_id>

Step 3: Refresh the token

When the access_token expires (after expires_in seconds), use the refresh_token to obtain a new pair:

POST /v1/auth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "<refresh_token>"
}

Document Upload Flow (3 Steps)

File uploads use S3 Presigned POST.

Step 1: Get upload URL

POST /v1/teams/{teamId}/folders/{folderId}/documents/upload-url
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "filename": "manual.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1048576,
  "sha256_hash": "e3b0c44298fc1c149afb...",
  "skip_if_duplicate": true
}

The response contains upload_url (S3 endpoint), upload_fields (form fields), and document_id. If duplicate: true is returned, steps 2 and 3 are not required.

Step 2: Upload directly to S3

POST <upload_url>
Content-Type: multipart/form-data

# Include all upload_fields as form fields, then append the file field last
key=<s3_key>&Content-Type=application/pdf&...&file=<binary>

Step 3: Confirm upload

POST /v1/teams/{teamId}/folders/{folderId}/documents/{docId}/confirm
Authorization: Bearer <access_token>

A successful confirm triggers the vectorization pipeline. Poll the GET endpoint until the status changes from processing to ready.

Roles and Permissions

Role Get Token List Folders Upload View Documents Delete Documents
admin Yes Yes Yes Yes Yes
manager Yes Yes Yes Yes Yes
member No (403) Yes No (403) Yes No (403)

Error Format

All error responses use the following format:

{
  "statusCode": 400,
  "message": "Bad Request",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Authentication errors (401) and permission errors (403) may include OAuth2.0-compatible error / error_description fields in the message field.

Rate Limiting

  • POST /v1/auth/token: 10 requests per 60 seconds (10 req/60s)
  • Authenticated general endpoints: 60 requests per minute (60 req/min)
  • Exceeding these limits returns 429 Too Many Requests.

Authentication

Obtain and refresh access tokens

Issue or refresh access token

OAuth2.0-compatible token issuance endpoint.

Password Grant (grant_type: password)

Issues a token using email and password.

Restrictions:

  • Only admin or manager roles are allowed (member returns 403)
  • MFA-enabled accounts are currently not supported (400 mfa_required)
  • Unverified email accounts return 401

Refresh Token Grant (grant_type: refresh_token)

After the access_token expires, use the refresh_token to obtain a new token pair. The refresh token itself is rotated; the old token becomes invalid.

Request Body schema: application/json
required
One of
grant_type
required
string
Value: "password"
username
required
string <email>

User's email address

password
required
string

User's password

team_id
required
string <uuid>

Team ID (required in multi-tenant environments)

Responses

Request samples

Content type
application/json
Example
{
  • "grant_type": "password",
  • "username": "admin@example.com",
  • "password": "string",
  • "team_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "refresh_token": "string"
}

Folders

Manage folders (knowledge units)

List folders

Returns the list of folders (knowledge units) for the specified team.

Available roles: admin, manager, member

Only folders accessible based on the user's folder access rights (read/edit) are returned.

Authorizations:
BearerAuth
path Parameters
teamId
required
string <uuid>
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Team ID (UUID format)

Responses

Response samples

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

Documents

Upload and manage documents

Get upload URL (Step 1)

Issues an S3 Presigned POST URL. This is Step 1 of the document upload flow.

Available roles: admin, manager

SHA-256 Duplicate Check

If sha256_hash and skip_if_duplicate: true are specified, the system checks whether a document with the same hash and ready status already exists in the folder. If a duplicate is detected, duplicate: true is returned, and Steps 2 (S3 upload) and 3 (confirm) are not needed.

Supported File Formats

Format MIME Type
PDF application/pdf
Plain Text text/plain
Markdown text/markdown
HTML text/html
Word (.doc) application/msword
Word (.docx) application/vnd.openxmlformats-officedocument.wordprocessingml.document
Excel (.xls) application/vnd.ms-excel
Excel (.xlsx) application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
PowerPoint (.ppt) application/vnd.ms-powerpoint
PowerPoint (.pptx) application/vnd.openxmlformats-officedocument.presentationml.presentation
CSV text/csv
JPEG Image image/jpeg
PNG Image image/png
Authorizations:
BearerAuth
path Parameters
teamId
required
string <uuid>
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Team ID (UUID format)

folderId
required
string <uuid>
Example: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy

Folder ID (UUID format)

Request Body schema: application/json
required
filename
required
string

Name of the file to upload

mime_type
required
string
Enum: "application/pdf" "text/plain" "text/markdown" "text/html" "application/msword" "application/vnd.openxmlformats-officedocument.wordprocessingml.document" "application/vnd.ms-excel" "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" "application/vnd.ms-powerpoint" "application/vnd.openxmlformats-officedocument.presentationml.presentation" "text/csv" "image/jpeg" "image/png"

MIME type of the file

size_bytes
integer

File size in bytes. Optional but recommended.

sha256_hash
string

SHA-256 hash of the file (hex string). Used for duplicate detection.

skip_if_duplicate
boolean
Default: false

Skip upload if a document with the same sha256_hash already exists

Responses

Request samples

Content type
application/json
{
  • "filename": "product-manual-v2.pdf",
  • "mime_type": "application/pdf",
  • "size_bytes": 1048576,
  • "sha256_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  • "skip_if_duplicate": true
}

Response samples

Content type
application/json
Example
{
  • "duplicate": false,
  • "document_id": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
  • "upload_url": "https://s3.amazonaws.com/monoshiri-uploads/",
  • "upload_fields": {
    },
  • "s3_key": "teams/xxx/folders/yyy/zzz/product-manual-v2.pdf"
}

Confirm upload completion (Step 3)

Notifies the API that the S3 file upload is complete and triggers the vectorization pipeline. This is Step 3 of the document upload flow.

Available roles: admin, manager

The S3 upload (Step 2) must be completed before calling this endpoint.

After a successful confirm, the document status changes from uploading to processing. Once vectorization is complete, the status becomes ready.

Processing time varies based on file size and content (typically a few seconds to a few minutes). Poll GET /v1/teams/{teamId}/folders/{folderId}/documents/{docId} to check status.

Authorizations:
BearerAuth
path Parameters
teamId
required
string <uuid>
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Team ID (UUID format)

folderId
required
string <uuid>
Example: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy

Folder ID (UUID format)

docId
required
string <uuid>
Example: zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz

Document ID (UUID format)

Responses

Response samples

Content type
application/json
{
  • "document_id": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
  • "status": "processing",
  • "message": "Upload confirmed. Vectorization pipeline started."
}

List documents in folder

Returns documents in the specified folder with cursor-based pagination.

Available roles: admin, manager, member

Pagination

If next_cursor is not null, there are more pages. Pass cursor=<next_cursor> in the next request.

Sorting

Use the sort parameter to specify the sort order (default: created_at_desc).

Authorizations:
BearerAuth
path Parameters
teamId
required
string <uuid>
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Team ID (UUID format)

folderId
required
string <uuid>
Example: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy

Folder ID (UUID format)

query Parameters
status
string
Enum: "uploading" "processing" "ready" "error"

Filter by document status

q
string
Example: q=manual

Partial match search on filename

cursor
string

Pagination cursor (pass next_cursor from the previous response)

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1-100, default 20)

sort
string
Default: "created_at_desc"
Enum: "created_at_asc" "created_at_desc" "filename_asc" "filename_desc" "size_bytes_asc" "size_bytes_desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "eyJpZCI6Inp6enovv..."
}

Get document details

Returns detailed information about the specified document.

Available roles: admin, manager, member

Can also be used for polling while the status changes from processing to ready.

Authorizations:
BearerAuth
path Parameters
teamId
required
string <uuid>
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Team ID (UUID format)

folderId
required
string <uuid>
Example: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy

Folder ID (UUID format)

docId
required
string <uuid>
Example: zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz

Document ID (UUID format)

Responses

Response samples

Content type
application/json
{
  • "document_id": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
  • "folder_id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
  • "filename": "product-manual-v2.pdf",
  • "mime_type": "application/pdf",
  • "size_bytes": 1048576,
  • "status": "ready",
  • "s3_key": "teams/xxx/folders/yyy/zzz/product-manual-v2.pdf",
  • "chunk_count": 24,
  • "uploaded_by": "uuuuuuuu-uuuu-uuuu-uuuu-uuuuuuuuuuuu",
  • "created_at": "2024-01-01T00:00:00.000Z",
  • "updated_at": "2024-01-01T01:00:00.000Z"
}

Delete document

Deletes the specified document. The file on S3 and vector data in S3 Vectors are also deleted.

Available roles: admin, manager

This action cannot be undone. AI search results that referenced this document are updated immediately.

Authorizations:
BearerAuth
path Parameters
teamId
required
string <uuid>
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Team ID (UUID format)

folderId
required
string <uuid>
Example: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy

Folder ID (UUID format)

docId
required
string <uuid>
Example: zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz

Document ID (UUID format)

Responses

Response samples

Content type
application/json
{
  • "statusCode": 400,
  • "message": "Bad Request",
  • "timestamp": "2024-01-01T00:00:00.000Z"
}

List all team documents (cross-folder)

Returns all documents across the team with cursor-based pagination. This is a supplementary endpoint for cross-folder searches.

Available roles: admin, manager, member

For folder-specific document operations, use /v1/teams/{teamId}/folders/{folderId}/documents instead.

Pagination and Sorting

Uses the same parameters as /v1/teams/{teamId}/folders/{folderId}/documents.

Authorizations:
BearerAuth
path Parameters
teamId
required
string <uuid>
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Team ID (UUID format)

query Parameters
status
string
Enum: "uploading" "processing" "ready" "error"

Filter by document status

q
string
Example: q=manual

Partial match search on filename

cursor
string

Pagination cursor

limit
integer [ 1 .. 100 ]
Default: 20

Number of items per page (1-100, default 20)

sort
string
Default: "created_at_desc"
Enum: "created_at_asc" "created_at_desc" "filename_asc" "filename_desc" "size_bytes_asc" "size_bytes_desc"

Sort order

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "eyJpZCI6Inp6enovdi4uLiJ9"
}