# HTTP

> Six endpoints, and the reason there is no seventh.

Base URL: `https://api.formalogic.io`

Six endpoints. There is deliberately no `/check` that takes rules and
returns a verdict: using it would mean learning the rules, which would mean
publishing them, and the point of an oracle is that you never have to.

| | |
|---|---|
| [`GET /v1/oracles`](https://docs.formalogic.io/list-oracles) | What this key may ask. Free |
| [`POST /v1/oracles/{name}/ask`](https://docs.formalogic.io/ask) | Ask one. Costs the oracle's credits |
| [`GET /v1/me`](https://docs.formalogic.io/me) | Which organisation this key acts for. Free |
| [`POST /v1/figures/render`](https://docs.formalogic.io/figures) | Draw a `valid` answer as SVG or PNG. Free |
| [`GET /v1/news`](https://docs.formalogic.io/news-feedback) | What changed for callers, newest first. Free |
| [`POST /v1/feedback`](https://docs.formalogic.io/news-feedback#send-feedback) | Say what worked and what did not. Free |

Full parameters, types and responses are on those pages, generated from the
API's own definition.

## Conventions

**Authentication** is a bearer token on every call. See
[Authentication](https://docs.formalogic.io/authentication).

**Content type** is `application/json` on the request and the response.

**Timeouts**: allow 120 seconds for an ask. Listing is fast.

**No streaming, no polling, no callbacks.** A call returns when the verdict does.

**No pagination.** The catalogue is small enough to return whole, and there is no
list endpoint that grows without bound. If that changes, it changes with a
documented cursor rather than silently.

## Versioning

The path carries the version: `/v1`. Within a version we will add response
fields and add oracles; we will not remove a field, change a field's type or
narrow an enum you already receive. Anything that would is a `/v2`.

Write clients that ignore fields they do not recognise.

Note that the API version and the rules' `verified_by` hash are different
things and move independently — see [Citations](https://docs.formalogic.io/citations).

## Errors

Every failure carries a stable code. See [Errors](https://docs.formalogic.io/errors).

Note that a refused answer is **not** an error: it is `200` with
`"status": "invalid"`. See [Verdicts](https://docs.formalogic.io/verdicts).