---
title: "List/search documents (JSON)"
method: GET
path: "/docs.json"
tags: ["Documents"]
---

# List/search documents (JSON)

`GET /docs.json`

Returns document metadata structures. Query options (mutually combinable as in server code): - `q`: substring match against the document label (server may cap results) - `id`: request a specific document id - `random`: if present/truthy, returns a single random document (and disables caching) - `n`: limit number of results Supports conditional requests via corpus ETag / If-None-Match.

## Query parameters

- `q` string
- `id` string
- `random` boolean
- `n` integer

## Response `200`

Document list

- union — Usually an array of documents; some internal calls use map form, but `/docs.json` returns the list form in typical usage.
  - DocSummary[]
    - `id` string, required — Document identifier (label key used by server).
    - `label` string, required — Human-readable label for the document.
    - `metadata` Metadata, required — Arbitrary metadata fields from the corpus.
  - DocMap

## Other responses

- `304` — Not Modified (If-None-Match matched)

---

[API](https://skmtc.dev/inpho/apis/topic-explorer-server-api.md) · [All operations](https://skmtc.dev/inpho/apis/topic-explorer-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inpho/topic-explorer-server-api/revisions/04253424f5bb/schema)