# HTTP API Reference

This page lists every HTTP endpoint of go-image-server, the response format of each, and their shared behavior.

## Endpoints

| Method | Path | Handler | Details |
|---|---|---|---|
| `GET` | `/c/img/*path` | `handlers.GetFromPath` | [Image Parameters](/api-reference-image) |
| `POST` | `/upload/*path` | `handlers.PostToPath` | [Upload API](/api-reference-upload) |
| `DELETE` | `/del/*path` | `handlers.DeleteFromPath` | [Delete API](/api-reference-delete) |
| `GET` | `/check/state` | `handleHealthCheck` | Returns `200 ok` |
| Any | Other paths | `routes.Set404` | Returns `404 Not Found` |

`*path` is a Gin wildcard parameter and may contain multiple `/` segments; handlers trim leading and trailing `/`.

## Response Formats

| Endpoint | Success | Failure |
|---|---|---|
| `GET /c/img/*path` | Image or PDF bytes (chunked) | 404 placeholder SVG (`Cache-Control: no-cache`) |
| `POST /upload/*path` | `201` JSON | Plain-text error message |
| `DELETE /del/*path` | `200` JSON | Plain-text error message |

Upload and delete errors go through `utils.HandleError`, which responds with plain text and logs two `[ERROR]` lines; read errors go through `utils.HandleGetError`, which returns the placeholder.

## Timeouts

All three handlers work in a goroutine and wait on it with `context.WithTimeout(30s)`. Past 30 seconds they return `408` with `timed out`. Nginx additionally sets `proxy_read_timeout` / `proxy_send_timeout` to 120 seconds for `/c/img/`.

## Access Control

The Go service performs no authentication. The Nginx `/upload/` and `/del/` blocks ship with commented-out `allow` / `deny` lines; enable an IP allowlist, or expose these two paths only on an internal network, before going live (see [Nginx](/deployment-nginx)).