# peinture API

Image storage & processing. You upload photos; the service stores the originals privately, generates a set of sizes and formats, and serves them publicly. This is the developer reference.

## Shape of the API

Metadata and control is **JSON-RPC 2.0** over a single endpoint:

```
POST https://peinture.gumeniuk.com/rpc
Content-Type: application/json
```

Every request is an envelope:

```json
{ "jsonrpc": "2.0", "id": 1, "method": "image.list", "params": { "limit": 50 } }
```

A success returns `result`; a failure returns `error` (with an HTTP status of 200 either way — see [errors](/docs/errors)). Raw bytes — [upload](/docs/uploads), archive download, and image serving — are plain HTTP, not JSON-RPC.

Each method also has a REST-shaped alias at `POST /rpc/{method}` (e.g. `POST /rpc/image.list`) so OpenAPI tooling can address one method per path.

## Quickstart

1. **Log in** for an access token:

```bash
curl -s https://peinture.gumeniuk.com/rpc -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"auth.login","params":{"email":"you@example.com","password":"…"}}'
# → { "result": { "access_token": "…", "refresh_token": "…", "user": {…} } }
```

2. **Upload** an image (multipart, not JSON-RPC):

```bash
curl -s https://peinture.gumeniuk.com/api/v1/images -H "Authorization: Bearer $TOKEN" \
  -F 'file=@photo.jpg' -F 'meta={"title":"Photo"}'
```

3. **List** your images:

```bash
curl -s https://peinture.gumeniuk.com/rpc -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"image.list","params":{"limit":50}}'
```

## Next

- [Authentication](/docs/authentication) — access tokens, refresh, and personal access tokens
- [Methods](/docs/methods) — the full method reference
- [Errors](/docs/errors) — error codes and how to handle them
- Machine-readable: [OpenRPC](/openrpc.json) · [OpenAPI 3.1](/openapi.json) · [Postman](/docs/peinture.postman_collection.json)