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 Duar for authorization in AuthZ mode. Every request carries two tokens:

curl http://localhost:8000/artifacts \
  -H "Authorization: Bearer <idp_token>" \
  -H "X-Authz-Token: <authz_token>"

The authentication flow:

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 for a short-lived Duar authorization token scoped to one workspace. Minting needs the service key, so it goes through a server-side route: the portal uses its own /api/auth/mint, and non-browser clients such as the CLI can POST /auth/mint on the API with {"idp_token": "...", "provider": "google", "workspace_id": "..."}.
3. The authorization token encodes the user's workspace_id, user_id, and workspace role.
4. Every API request sends the IdP token in Authorization and the authorization token in X-Authz-Token. The server validates both, checks that they belong to the same user, and extracts the auth context.

The RequestAuth object extracted from the tokens 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 two visibility levels:

Either way, the owner or a workspace admin can also share an artifact with specific users or groups.

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