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 containing the query, suitable for autocomplete inputs. Searches both tag mentions and author mentions with case-insensitive matching, most frequent first.

Parameter	Type	Required	Description
`q`	string	Yes	Search text (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_name"}
]

Popular Tags

GET /browse/tags/popular?entity_type=compound_name&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_name`, `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_name, target, disease, gene_name, etc.), plus author and date.

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",
      "display_name": "Target",
      "artifact_count": 42,
      "distinct_count": 18
    },
    {
      "entity_type": "compound_name",
      "display_name": "Compound",
      "artifact_count": 87,
      "distinct_count": 214
    }
  ],
  "total_artifacts": 120
}

Category Folders

GET /browse/categories/{entity_type}/folders?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. The date category is hierarchical: years have has_children: true, and passing a year as parent lists its months.

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

Response:

{
  "entity_type": "target",
  "parent": null,
  "folders": [
    {"tag_value": "nadd", "display_name": "NadD", "artifact_count": 15, "has_children": false},
    {"tag_value": "inha", "display_name": "InhA", "artifact_count": 12, "has_children": false},
    {"tag_value": "kasa", "display_name": "KasA", "artifact_count": 8, "has_children": false}
  ],
  "total_folders": 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	The folder's `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",
    "artifact_type": "RESEARCH_ARTICLE",
    "page_count": 12,
    "presentation_date": "2026-03-29",
    "author_names": ["J. Smith", "A. Lee"],
    "tag_page_sources": [{"page_id": "uuid", "page_index": 3}]
  }
]

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, using the folder's tag_value.
Use GET /browse/tags/suggest?q=... for the tag filter autocomplete input.