# HTTP Interface

## Endpoints

The HTTP interface is composed of only two routes.

<table><thead><tr><th>path</th><th>description</th><th>input</th><th>output</th><th data-hidden>name</th></tr></thead><tbody><tr><td>/catalog</td><td>get schemas, tables, columns metadata</td><td></td><td>A JSON-formatted representation of the database catalog</td><td>catalog</td></tr><tr><td>/query</td><td>process SQL queries</td><td>An SQL query in the HTTP request's body</td><td>A JSON-formatted result set</td><td>query</td></tr></tbody></table>

## Caching

Various parameters of the query influence the caching behavior of the query endpoint. We try to stay as close to standard HTTP caching as possible and implement custom extensions only when needed. Cache-related parameters must be passed through the standard `Cache-Control` header (or `cache-control` query param).

| supported directive | semantic                                                 |
| ------------------- | -------------------------------------------------------- |
| `no-cache`          | Bypass query cache                                       |
| `no-store`          | Do not store the result of this query in the query cache |
| `max-age=N`         | The client can tolerate a result at most `N` seconds old |

We support some custom request headers related to the caching behavior of the HTTP interface.

| header                             |                                                                                                                                                                                                                                      |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-Agnostic-Cache-Refresh-Trigger` | <p>The value must be a float between 0 and 1.<br>On cache hit, we compute the ratio <code>Age / Max-Age</code> with this value and trigger an asynchronous cache refresh when the value is higher than the aforementioned ratio.</p> |

Some cache-related headers are set on the response.

| header             | meaning                                                                                                                                                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Agnostic-Cache` | will be set to `hit` if the resultset comes from the cache, `miss` otherwise                                                                                                                                                                          |
| `Cache-Control`    | `max-age`, `no-cache` and `no-store` directives will be set to ensure no intermediate (browser, proxy, ...) cache the response. This ensures we have complete control over caching so that features like asynchronous cache refresh work as expected. |
| `Age`              | this header is set on cache hit with the age (in seconds) of the served result                                                                                                                                                                        |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.agnostic.dev/fundamentals/http-interface.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.