API Overview

The DocuStore API is a REST API built on FastAPI. All endpoints require authentication and are scoped to a workspace. The API serves JSON responses and accepts JSON request bodies unless otherwise noted (file uploads use multipart form data).

Base URL

http://localhost:8000

In production, the API is served behind a reverse proxy with TLS termination. The base URL is configurable via API_HOST and API_PORT.

Authentication

DocuStore uses Sentinel for authorization. Every request must include a valid JWT in the Authorization header:

curl -H "Authorization: Bearer <token>" http://localhost:8000/artifacts

The authentication flow works in AuthZ mode:

1. The client authenticates with an Identity Provider (IdP) directly (e.g., Google OAuth) and obtains an IdP token.
2. The client exchanges the IdP token with Sentinel for a DocuStore authorization JWT.
3. The authorization JWT encodes the user's workspace_id, user_id, and permissions.
4. Every API request includes this JWT. The server validates it and extracts the auth context.

The RequestAuth object extracted from the JWT provides:

Workspace Scoping

All data access is scoped to the authenticated user's workspace. List endpoints return only resources belonging to that workspace. Resource endpoints verify workspace membership before returning data.

Additionally, entity-level permissions control access to individual artifacts:

Artifacts support three visibility levels:

Error Handling

The API returns standard HTTP status codes:

Error responses include a JSON body with a detail field:

{
  "detail": "Artifact not found or does not belong to this workspace"
}

Request Timing

When enabled (ENABLE_REQUEST_TIMING=true), the API logs timing information for every request and flags slow requests exceeding SLOW_REQUEST_THRESHOLD_MS (default 1000ms).

API Sections