Browse API | DocuStore

Endpoints for tag-based document exploration, category browsing, and tag autocomplete.

The browse API enables tag-based document exploration. NER-extracted entities (compounds, targets, diseases, genes) are organized into categories and folders, providing a structured browsing experience alongside free-text search.

Tag Autocomplete

GET /browse/tags/suggest?q=nad&limit=10

Returns tags matching a prefix query, suitable for autocomplete inputs. Searches both tag mentions and author mentions with case-insensitive matching.

Parameter	Type	Required	Description
`q`	string	Yes	Prefix query (1-100 characters)
`limit`	integer	No	Max suggestions (1-20, default 10)

Response:

[
  {"tag": "NadD", "entity_type": "target"},
  {"tag": "NadE", "entity_type": "target"},
  {"tag": "nadD", "entity_type": "gene"}
]

Popular Tags

GET /browse/tags/popular?entity_type=compound&limit=10

Returns the most frequently occurring tags, optionally filtered by entity type. Useful for showing trending or common tags on a dashboard.

Parameter	Type	Required	Description
`entity_type`	string	No	Filter by type (compound, target, disease, etc.)
`limit`	integer	No	Max results (1-50, default 10)

Browse Categories

GET /browse/categories?limit=5

Returns tag categories with artifact counts, powering the browse UI's top-level navigation. Categories correspond to entity types (compound, target, disease, gene, etc.).

Parameter	Type	Required	Description
`limit`	integer	No	Max categories (1-20, default 5)

The response includes sticky categories (configured via BROWSE_STICKY_CATEGORIES, default date,target) that always appear regardless of count.

Response:

{
  "categories": [
    {
      "entity_type": "target",
      "label": "Targets",
      "artifact_count": 42,
      "top_values": ["NadD", "InhA", "KasA"]
    },
    {
      "entity_type": "compound",
      "label": "Compounds",
      "artifact_count": 87,
      "top_values": ["SACC-111", "Rifampicin", "Ethionamide"]
    }
  ]
}

Category Folders

GET /browse/categories/{entity_type}/folders?parent=null&skip=0&limit=50

Lists distinct tag values (folders) within a category. Each folder represents a unique entity value with a count of associated artifacts.

Parameter	Type	Required	Description
`entity_type`	path	Yes	Category to browse (e.g., `target`, `compound`)
`parent`	string	No	Parent folder for hierarchical browsing
`skip`	integer	No	Pagination offset (default 0)
`limit`	integer	No	Max results (1-100, default 50)

Response:

{
  "entity_type": "target",
  "folders": [
    {"tag_value": "NadD", "artifact_count": 15},
    {"tag_value": "InhA", "artifact_count": 12},
    {"tag_value": "KasA", "artifact_count": 8}
  ],
  "total": 45
}

Folder Artifacts

GET /browse/categories/{entity_type}/folders/{tag_value}/artifacts?skip=0&limit=50

Lists artifacts within a specific folder. Returns documents tagged with the specified entity value.

Parameter	Type	Required	Description
`entity_type`	path	Yes	Category (e.g., `target`)
`tag_value`	path	Yes	Tag value (e.g., `NadD`)
`skip`	integer	No	Pagination offset (default 0)
`limit`	integer	No	Max results (1-100, default 50)

Response:

[
  {
    "artifact_id": "uuid",
    "title": "NadD Inhibitor Screening Results",
    "source_filename": "paper.pdf",
    "page_count": 12,
    "tags": ["NadD", "SACC-111", "tuberculosis"],
    "updated_at": "2026-03-29T12:00:00Z"
  }
]

Browse Configuration

Variable	Default	Description
`BROWSE_DEFAULT_CATEGORY_LIMIT`	`5`	Default number of categories shown
`BROWSE_STICKY_CATEGORIES`	`date,target`	Comma-separated categories that always appear

Typical Frontend Flow

Load categories via GET /browse/categories to render the top-level navigation.
When the user selects a category (e.g., "Targets"), load folders via GET /browse/categories/target/folders.
When the user selects a folder (e.g., "NadD"), load artifacts via GET /browse/categories/target/folders/NadD/artifacts.
Use GET /browse/tags/suggest?q=... for the tag filter autocomplete input.