> ## Documentation Index > Fetch the complete documentation index at: https://docs.githits.com/llms.txt > Use this file to discover all available pages before exploring further. # Requests and responses > Choose response information with fields, encode parameters and read documentation or source code through the unified GitHits API. GitHits endpoints use common request conventions. Each endpoint's reference describes the parameters it accepts and the information it returns. ## Choose what the response includes The `fields` parameter lets you request the information your application or agent needs. For example, package inspection returns basic package and release information by default. You can also ask for download counts, vulnerability information or release notes. Add `fields` to the URL as a query parameter. Separate multiple choices with commas. For package inspection: | Request | Information returned | | - | - | | Omit `fields` | Default package and selected-release information | | `fields=security` | Vulnerability counts and whether the selected release is affected | | `fields=security.*` | The security information above, plus up to five recent advisories affecting the selected release | | `fields=package,selected_version,security.*` | The default information plus the security information and recent advisories | **When you supply `fields`, your choices replace the defaults.** Include the default groups explicitly if you want to keep them. Some information, such as the package name and resolved version in package inspection, is always returned so you can identify the result. This request keeps the default package and release information and adds security information for Express `4.18.2`: ```bash theme={null} curl --silent --show-error \ --header "Authorization: Bearer $GITHITS_API_TOKEN" \ 'https://api.githits.dev/v1/packages/npm/express?version=4.18.2&fields=package,selected_version,security.*' ``` This example expects your API token in `GITHITS_API_TOKEN`, as explained in the [quickstart](/api/quickstart). The quotes around the URL ensure your shell passes the whole URL, including `&`, to `curl`. ### Check the choices for your endpoint Each endpoint defines its own allowed `fields` values. Use the names listed in its reference; a property appearing in a JSON response does not automatically make it an accepted `fields` value. For example, package inspection accepts `security.*` as a name for security counts and recent advisories. That does not mean `*` works with every name or endpoint. Likewise, requesting `package` does not include the separately listed `package.downloads` information. `fields` stays in the URL for both GET and POST requests. For a POST, put the other inputs in the JSON body as shown in the endpoint reference. Send one `fields` parameter containing your comma-separated choices, rather than repeating the parameter. Not every endpoint accepts `fields`. If the reference does not list it, use that endpoint's normal response. Unsupported choices return `400 VALIDATION_ERROR`. Selecting less information can reduce the response size. It does not always reduce the work needed to produce the result; each endpoint explains when a choice changes the work performed. ## Pass request parameters * Put URL parameters after `?` and separate them with `&`, as in the example above. * For JSON request bodies, send `Content-Type: application/json`. Use the exact property names shown in the reference, such as `current_version`. * Encode special characters in URL values. A scoped npm package such as `@scope/package` becomes `%40scope%2Fpackage` in the package-name part of the path. * When a version contains a literal `+`, write `%2B` in the URL. An unencoded `+` in a query value is read as a space. * For `GET /v1/read`, pass `target` as a query parameter. Encode a literal `+` as `%2B` and a documentation fragment marker (`#`) as `%23`. With `curl`, use `--get` and `--data-urlencode` as shown below. ## Read documentation or source code [Read documentation or source code](/api-reference/v1/read/read-documentation-or-source-code) uses one endpoint: `GET /v1/read`. Follow returned read actions with their `target` and non-null `path` unchanged; omit a null path. | Read | Inputs | | - | - | | Documentation page or section | A returned read action's `target` and non-null `path`, or a search result's `docs_read_target` as `target` without `path`. | | Source file | `target`: a package target such as `npm:express@4.18.2`, or a supported public repository URL with an optional `@ref`. `path`: the exact target-relative file path. | ### Read a documentation page [List documentation paths](/api-reference/v1/list/list-files-and-documentation-paths) with an explicit `site:` target and follow an entry's `read` action. Alternatively, [search documentation](/api-reference/v1/search/search-documentation-code-and-symbols) and pass the returned `docs_read_target` unchanged, including any fragment. Replace `` below with that search value; the command encodes it as a query value. ```bash theme={null} curl --silent --show-error --get \ --header "Authorization: Bearer $GITHITS_API_TOKEN" \ --data-urlencode 'target=' \ 'https://api.githits.dev/v1/read' ``` ### Read a source file Find an exact path with [file listing](/api-reference/v1/list/list-files-and-documentation-paths), [source text search](/api-reference/v1/grep/find-regex-or-literal-matches-across-source-and-documentation), or a code search result. Follow the returned read action's target and path; display paths can differ from read paths. Preserve the served version or commit for an exact follow-up. This example reads from Express `4.18.2`. Replace `` with a path discovered for that release. ```bash theme={null} curl --silent --show-error --get \ --header "Authorization: Bearer $GITHITS_API_TOKEN" \ --data-urlencode 'target=npm:express@4.18.2' \ --data-urlencode 'path=' \ 'https://api.githits.dev/v1/read' ``` Repository targets use `@` to introduce a ref, for example `https://github.com/expressjs/express@4.18.2`. A literal `#` is not supported in code targets. ### Handle the read response Branch on the required `kind` field: | `kind` | Identity and source information | | - | - | | `documentation` | `id`, reusable `docs_read_target`, and `source` with the crawled page URL or exact repository locator. | | `code` | `path`, `repository_file_path`, `is_binary`, `target_resolution`, `code_index_state`, and `indexing_ref`. Use `target_resolution.served` to identify the artifact that supplied the content. | Both branches return `metadata` and `content` by default. `fields=metadata` omits the body; `fields=content` omits descriptive metadata. Identity and source information remain present. Read text from `content.body` when selected; binary code has null body and range values. `start_line` and `end_line` are positive, 1-based inclusive bounds. Without bounds, the complete page or file is returned, or a documentation URL's fragment selects an indexed section. Either explicit bound overrides the fragment and requires `content` in `fields`. An end beyond the last line is clamped. Empty documentation has null bounds; an empty text file has bounds `0`–`0`. For code preparation, `wait_timeout_ms` defaults to `20000` and accepts `0`–`60000`. With `0`, code that is still being prepared returns `503 PACKAGE_INDEXING` immediately. Documentation reads do not use this indexing wait budget. See the [read reference](/api-reference/v1/read/read-documentation-or-source-code) for target validation and endpoint-specific errors. ### Migrate separate read requests The separate documentation and code read endpoints have been removed from the current v1 contract. Send both kinds of request to `GET /v1/read`. Follow returned read actions with their `target` and non-null `path`, or pass a documentation locator as `target` alone. Update response handling to branch on `kind` and use the corresponding identity and content fields above. ## Interpret the result Keep the returned package version or commit and source references with the information your workflow uses. When discovery returns a target for a later source or documentation read, follow the endpoint's instructions for using that target. Check whether a response reports incomplete information or when its data was last updated. HTTP `200` means the request succeeded; some endpoints can still report missing or incomplete data. An omitted property, `null`, an empty list and zero can mean different things. The reference explains those meanings for each response. For failed requests, use the HTTP status and the response's `code` to decide what to do next. See [API errors](/api/errors) for troubleshooting and retry guidance. ## Research a question with cited sources [Research](/api-reference/v1/experimental/research-a-question-with-cited-sources) generates a Markdown answer with source URLs through `POST /v1/experimental/research`. Answer generation can take up to **210 seconds**; configure your client timeout to exceed that deadline. Start with a question and one structured `target`: a package, GitHub repository, or documentation site. This example uses the token setup from the [quickstart](/api/quickstart) and allows 240 seconds for the response: ```bash theme={null} curl --silent --show-error --max-time 240 \ --header "Authorization: Bearer $GITHITS_API_TOKEN" \ --header 'Content-Type: application/json' \ --data '{"target":{"registry":"npm","name":"express","version":"5.1.0"},"question":"How does error handling work?"}' \ 'https://api.githits.dev/v1/experimental/research' ``` The response contains `answer_markdown`, ordered `sources` with URLs, a `tool_call_id` for diagnostics, and a `thread_id` for follow-ups. Source URLs are not guaranteed to be valid `read` targets. For a follow-up, reuse the returned `thread_id` instead of sending `target`. Replace `` below with that value: ```bash theme={null} curl --silent --show-error --max-time 240 \ --header "Authorization: Bearer $GITHITS_API_TOKEN" \ --header 'Content-Type: application/json' \ --data '{"thread_id":"","question":"What about async handlers?"}' \ 'https://api.githits.dev/v1/experimental/research' ``` Send exactly one of `target` or `thread_id` together with `question`; the public API does not accept a question alone. Research saves answers and follow-up turns. After a timeout, consult the [retry guidance](/api/errors) before repeating a request. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.