# API overview

> Discover BisQue's HTTP API, interactive reference, and contract conventions.

BisQue exposes a JSON HTTP API for resources, datasets, uploads, projects, annotations,
workflows, executions, exports, models, modules, and account operations.

## Interactive reference

On a deployment with documentation enabled, open:

* `/api/docs` for the interactive API explorer; or
* `/api/v1/openapi.json` for the machine-readable OpenAPI document.

The generated contract is the endpoint-level source of truth. It includes request and response
schemas, authentication requirements, operation identifiers, documented errors, and supported
query parameters.

## API conventions

* Canonical resource and workflow contracts are versioned below `/api/v1`.
* Binary image and blob delivery, plus operational health routes, use stable unversioned paths.
* Collection pagination uses opaque cursors. Treat a returned cursor as an indivisible value.
* Private responses use restrictive cache headers. Some resource and project reads support
  conditional requests with `ETag`, `If-None-Match`, or `If-Match`.
* Write retries are safe only where the endpoint documents idempotency or a precondition.
* Errors use a structured JSON contract and responses include a request correlation identifier.

## Find enabled capabilities

Request `GET /api/v1/client-configuration` to discover deployment-level capabilities and public
links. Clients should use this contract instead of probing optional endpoints.

For authentication choices, continue to [Authentication](/docs/developer/authentication/).