> ## 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. # Ask a source-cited question > Ask a question about a package, GitHub repository, or documentation site and receive a Markdown answer with links to its sources. Continue the conversation with follow-up questions in the same thread. Use this experimental endpoint when you want an explanation based on project documentation and code. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json post /v1/experimental/ask openapi: 3.1.0 info: description: >- Explore package metadata, security advisories, dependencies, documentation and source code with the GitHits API. ## Choose an operation | Task | Operations | | --- | --- | | Inspect a package | Release metadata, vulnerabilities and dependencies | | Review releases or upgrades | Changelog and batch upgrade reviews | | Read documentation | List package documentation, then read a page | | Navigate source code | List files, read a file or search text within a target | | Compare source trees | Compare files, line statistics and patches between package versions or repository refs | | Discover relevant content | Search across packages, repositories and documentation sites; retrieve a search's status and retained results | | Resolve a target name | Find ranked package, repository and documentation-site targets | | Ask a cited question | Generate an answer grounded in a package, repository or documentation site, or continue a conversation | | Generate an example | Generate and save a code example, then submit feedback | | Find a language identifier | Search supported programming languages | ## Authenticate and send requests The production API origin is `https://api.githits.dev`; development uses `https://api-dev.githits.dev`. Examples target production. Replace `` with your GitHits token. Send the token in `Authorization: Bearer `. JSON request bodies use `Content-Type: application/json`; public JSON field names use `snake_case`. Percent-encode a package name or opaque read target as one path segment, including any embedded slash. For query values, encode a literal plus sign as `%2B`; ordinary form decoding interprets `+` as a space. Each operation documents its accepted parameters and encoding rules. ## Select the data you need Where supported, `fields` is a comma-separated **query parameter**, including on POST requests. Omit it to use the operation's defaults. Supplying it replaces those defaults; required identity and information needed to interpret the result remain present. A **selector** names a supported **group** of response fields. Groups are atomic: their members are selected together. A **wildcard bundle**, such as `vulnerabilities.*`, selects only the groups listed for that bundle. A bare group does not automatically include nested groups. Arbitrary subfields and undeclared wildcards are not supported. Each operation lists its selectors, defaults, dependencies and the data they return. Selection can reduce transferred data without reducing the work needed to produce it; consult its parameter and response field documentation. Small fixed responses do not offer `fields`. ## Interpret responses and errors An omitted optional field can mean unselected or unavailable data, according to the operation's contract. Null has an operation-specific meaning: it can mark unavailable or inapplicable data, or an unselected search result. Empty arrays, zero and false are values, not substitutes for unavailable data. Always retain the result's completeness and freshness information when displaying or processing it. **Requested** identity records caller intent; **resolved** identity records what that intent resolved to; **served** identity identifies the artifact that produced the response. These can differ while indexing or refresh work continues. Use served identity when an exact follow-up read is required, preserving package-relative or repository-relative path scope. Errors normally use `application/problem+json`. Branch on the stable `code`, not the human-readable `detail`. Include `X-Request-ID` when reporting a problem; error `instance` matches that ID. Respect `Retry-After` when present. If request identity cannot be created, the response is an empty HTTP 500 without a request ID. Responses use `Cache-Control: no-store`. Timeouts do not guarantee that work stopped. Read the documented timeout responses, especially for Ask, generated examples and append-only feedback. Optional `X-GitHits-*` request headers attribute client, agent and session usage. The OpenAPI extension `x-githits-cost` is provisional operation metadata, not a price or a measure of computation. ## Contract status This API is pre-production. The external v1 contract is not yet frozen. license: name: Proprietary title: GitHits Public API version: 0.1.0 servers: - description: Production url: https://api.githits.dev security: [] tags: - description: >- Package metadata, release history, vulnerabilities, dependency graphs and upgrade comparisons. Each operation documents its registry, version and evidence scope. name: Packages - description: >- Discover existing documentation pages and read their content with exact source locators and availability information. name: Documentation - description: >- Enumerate files, read exact content and grep within a package or repository. Responses retain served identity, indexing state and completeness information. name: Code - description: >- Discover evidence across package, repository and documentation-site targets, then retrieve retained search results and progress. name: Search - description: >- Find supported programming-language names and aliases for example requests. name: Languages - description: >- Generate code examples for programming tasks, with source references and license attribution. name: Examples - description: Rate generated examples or sessions and provide written feedback. name: Feedback - description: >- Preview operations for target resolution, source comparison and cited questions. Routes use /v1/experimental and may later move to permanent v1 locations under a documented migration policy. name: Experimental paths: /v1/experimental/ask: post: tags: - Experimental summary: Ask a source-cited question description: > Ask a question about a package, GitHub repository, or documentation site and receive a Markdown answer with links to its sources. Continue the conversation with follow-up questions in the same thread. Use this experimental endpoint when you want an explanation based on project documentation and code. operationId: ask parameters: - description: >- Optional client attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Client-Name required: false schema: type: string - description: >- Optional client-version attribution: trimmed printable ASCII, at most 80 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Client-Version required: false schema: type: string - description: >- Optional agent attribution: trimmed printable ASCII, at most 160 bytes. Invalid optional values are dropped. in: header name: X-GitHits-Agent required: false schema: type: string - description: >- Optional session attribution: trimmed printable ASCII, at most 128 bytes. Invalid optional values are dropped; no session is created. in: header name: X-GitHits-Session-ID required: false schema: type: string requestBody: content: application/json: examples: follow_up: value: question: What about async handlers? thread_id: 01900000-0000-7000-8000-000000000002 package: value: question: How does error handling work? target: name: express registry: npm version: 5.1.0 schema: $ref: '#/components/schemas/AskRequest' required: true responses: '200': content: application/json: examples: default: summary: Package answer with ordered URL sources value: answer_markdown: >- Express forwards synchronous errors to error middleware. [Source 1] sources: - url: >- https://github.com/expressjs/express/blob/abc123/lib/router/index.js#L1-L20 thread_id: 01900000-0000-7000-8000-000000000002 tool_call_id: 01900000-0000-7000-8000-000000000001 follow_up: summary: Follow-up answer in the same thread value: answer_markdown: >- Async rejections require forwarding to next in older versions. [Source 1] sources: - url: https://expressjs.com/en/guide/error-handling.html thread_id: 01900000-0000-7000-8000-000000000002 tool_call_id: 01900000-0000-7000-8000-000000000003 schema: $ref: '#/components/schemas/AskResponse' description: >- Generated Markdown, ordered source URLs, and execution and thread identifiers headers: Cache-Control: schema: enum: - no-store type: string X-GitHits-Thread-Id: description: >- Thread identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-GitHits-Tool-Call-Id: description: >- Execution identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '400': content: application/problem+json: example: code: VALIDATION_ERROR detail: The request is invalid. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Validation error (VALIDATION_ERROR). headers: Cache-Control: schema: enum: - no-store type: string X-GitHits-Thread-Id: description: >- Thread identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-GitHits-Tool-Call-Id: description: >- Execution identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '401': content: application/problem+json: example: code: AUTHENTICATION_REQUIRED detail: A bearer credential is required. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 401 title: Authentication required type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Authentication required (AUTHENTICATION_REQUIRED, REAUTH_REQUIRED). headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: schema: type: string X-GitHits-Thread-Id: description: >- Thread identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-GitHits-Tool-Call-Id: description: >- Execution identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '403': content: application/problem+json: example: code: FORBIDDEN detail: The caller is not allowed to access this resource. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 403 title: Forbidden type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Forbidden (FORBIDDEN, TERMS_ACCEPTANCE_REQUIRED). headers: Cache-Control: schema: enum: - no-store type: string X-GitHits-Thread-Id: description: >- Thread identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-GitHits-Tool-Call-Id: description: >- Execution identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '404': content: application/problem+json: example: code: THREAD_NOT_FOUND detail: >- The requested answer thread was not found or is not accessible. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 404 title: Ask thread not found type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Ask thread not found (THREAD_NOT_FOUND). headers: Cache-Control: schema: enum: - no-store type: string X-GitHits-Thread-Id: description: >- Thread identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-GitHits-Tool-Call-Id: description: >- Execution identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '405': content: application/problem+json: example: code: METHOD_NOT_ALLOWED detail: The requested method is not supported for this route. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 405 title: Method not allowed type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: 'METHOD_NOT_ALLOWED: the route does not support this HTTP method.' headers: Allow: description: 'Supported methods: POST.' schema: type: string Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '409': content: application/problem+json: example: code: THREAD_CONFLICT detail: The answer thread cannot accept another turn. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 409 title: Ask thread conflict type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Ask thread conflict (THREAD_CONFLICT). headers: Cache-Control: schema: enum: - no-store type: string X-GitHits-Thread-Id: description: >- Thread identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-GitHits-Tool-Call-Id: description: >- Execution identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '429': content: application/problem+json: example: code: RATE_LIMITED detail: The request was rate limited. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 429 title: Rate limited type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Rate limited (RATE_LIMITED). headers: Cache-Control: schema: enum: - no-store type: string Retry-After: schema: type: string X-GitHits-Thread-Id: description: >- Thread identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-GitHits-Tool-Call-Id: description: >- Execution identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '500': description: >- Request identity could not be created. Empty body without X-Request-ID; no problem object is available. headers: Cache-Control: schema: enum: - no-store type: string x-githits-empty-identity-failure: true '502': content: application/problem+json: example: code: UPSTREAM_ERROR detail: The upstream service failed to provide a response. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 502 title: Upstream error type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Upstream error (UPSTREAM_ERROR). headers: Cache-Control: schema: enum: - no-store type: string X-GitHits-Thread-Id: description: >- Thread identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-GitHits-Tool-Call-Id: description: >- Execution identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '503': content: application/problem+json: example: code: UPSTREAM_UNAVAILABLE detail: The answer service is temporarily unavailable. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 503 title: Upstream unavailable type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: Upstream unavailable (UPSTREAM_UNAVAILABLE). headers: Cache-Control: schema: enum: - no-store type: string X-GitHits-Thread-Id: description: >- Thread identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-GitHits-Tool-Call-Id: description: >- Execution identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '504': content: application/problem+json: example: code: TIMEOUT detail: The upstream request did not complete in time. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 504 title: Upstream timeout type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: >- TIMEOUT: the answer exceeded its 210-second deadline. Set a longer client timeout. Generation may continue after a timeout; retrying can create another thread or turn. headers: Cache-Control: schema: enum: - no-store type: string X-GitHits-Thread-Id: description: >- Thread identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-GitHits-Tool-Call-Id: description: >- Execution identifier (UUIDv7). Present on success; available on failures when the service returns a valid identifier. schema: type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string security: - bearer_auth: [] components: schemas: AskRequest: description: Start a thread or ask a follow-up question. oneOf: - $ref: '#/components/schemas/AskTargetRequest' description: Start a thread from one structured target. - $ref: '#/components/schemas/AskThreadRequest' description: Continue a thread accessible to the caller. AskResponse: description: >- Generated answer, cited source URLs, and identifiers for diagnostics and follow-up questions. properties: answer_markdown: description: Generated Markdown; citations and source order are preserved. type: string sources: description: >- Source URLs in their original order. Citation numbers are not array indices; entries without URLs are omitted. items: $ref: '#/components/schemas/AskSource' type: array thread_id: description: Thread identifier (`UUIDv7`) to reuse for follow-up questions. format: uuid type: string tool_call_id: description: Execution identifier (`UUIDv7`) for diagnostics. format: uuid type: string required: - answer_markdown - sources - tool_call_id - thread_id type: object ProblemResponse: description: >- The stable problem document returned for an unsuccessful public API request. properties: acceptance_url: description: An optional acceptance URL supplied by the upstream allow-list. type: string code: description: The stable uppercase API error code. type: string detail: description: A stable, client-safe explanation of the failure. type: string instance: description: The active request trace ID. type: string status: description: The HTTP status returned with this problem. format: int32 minimum: 0 type: integer terms_url: description: An optional terms URL supplied by the upstream allow-list. type: string title: description: A short, stable title for the error. type: string type: description: The generic RFC 9457 problem type. type: string required: - type - title - status - detail - instance - code type: object AskTargetRequest: additionalProperties: false description: A question about one package, repository, or documentation site. properties: question: description: >- Nonblank question after trimming, at most 8192 Unicode scalar values. minLength: 1 type: string target: $ref: '#/components/schemas/AskTarget' description: Package, GitHub repository, or documentation site. required: - target - question type: object AskThreadRequest: additionalProperties: false description: A follow-up question in an existing thread. properties: question: description: >- Nonblank follow-up after trimming, at most 8192 Unicode scalar values. minLength: 1 type: string thread_id: description: Thread identifier (`UUIDv7`) returned by an earlier Ask request. format: uuid pattern: >- ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-7[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$ type: string required: - thread_id - question type: object AskSource: description: One source URL returned with the answer. properties: url: description: >- HTTP(S) source URL. It is not guaranteed to work as a code or documentation read target. format: uri type: string required: - url type: object AskTarget: description: Structured Ask target with exactly one addressing form. oneOf: - $ref: '#/components/schemas/AskPackageTarget' description: One package with optional explicit version text. - $ref: '#/components/schemas/AskRepositoryTarget' description: >- One GitHub repository root with optional branch, tag, or commit text. - $ref: '#/components/schemas/AskSiteTarget' description: >- One DNS-style documentation site, optionally with HTTP(S), site:, and a path prefix. AskPackageTarget: additionalProperties: false description: A package and optional version. properties: name: description: >- Package name, preserving spelling and whitespace; at most 255 UTF-8 bytes and no control characters. maxLength: 255 minLength: 1 type: string registry: description: >- Exact lowercase public registry spelling; whitespace and case variants are rejected. enum: - npm - pypi - hex - crates - vcpkg - zig - nuget - maven - packagist - rubygems - go - swift type: string version: description: >- Optional explicit version preserved without version normalization; null is invalid. type: string required: - registry - name type: object AskRepositoryTarget: additionalProperties: false description: A GitHub repository and optional branch, tag, or commit. properties: git_ref: description: >- Optional explicit ref preserved without normalization; null is invalid. type: string repo_url: description: Credential-free HTTP(S) github.com owner/repository root. minLength: 1 type: string required: - repo_url type: object AskSiteTarget: additionalProperties: false description: A documentation site and optional path. properties: site: description: >- Documentation host and optional path, with an optional HTTP(S) scheme or site: prefix. www and index.html remain significant. minLength: 1 type: string required: - site type: object securitySchemes: bearer_auth: scheme: bearer type: http ````