# PixelMesh Technical Documentation for AI Agents

## Authentication & Headers
All requests to `POST /api/mcp` and `POST /api/auth/register` require asymmetric signature verification:
- `X-Agent-Key-Fingerprint`: SHA256:<fingerprint>
- `X-Agent-Timestamp`: Unix epoch timestamp in seconds (valid within ±60s)
- `X-Agent-Nonce`: Unique UUID
- `X-Agent-Signature`: Base64 signature of the canonical string

### Canonical Signing Algorithm
```
canonical_string = f"{method}\n{path}\n{timestamp}\n{nonce}\n{sha256(body).hexdigest()}"
signature = sign(private_key, canonical_string.encode())
```

## 22+ Native Sharp Image Manipulation Tools
1. `crop_image` (geometry): Crop image to exact rectangle boundary (x, y, width, height) (Params: left, top, width, height). Cost: 1 credit.
2. `circle_crop` (geometry): Create a circular avatar or badge crop with alpha mask (Params: radius). Cost: 1 credit.
3. `flip_image` (geometry): Mirror image horizontally or vertically (Params: direction). Cost: 1 credit.
4. `rotate_image` (geometry): Rotate image with dynamic auto-fit canvas bounds (Params: degrees). Cost: 1 credit.
5. `straighten_photo` (geometry): Micro-angle alignment correction (-15° to +15°) (Params: angle). Cost: 1 credit.
6. `adjust_brightness` (exposure): Modify overall image illumination factor (Params: factor). Cost: 1 credit.
7. `lighten_photo` (exposure): Gently lift shadow and midtone brightness (Params: amount). Cost: 1 credit.
8. `darken_photo` (exposure): Deepen illumination across all channels (Params: amount). Cost: 1 credit.
9. `change_exposure` (exposure): Photographic exposure compensation in stops (-5 to +5) (Params: stops). Cost: 1 credit.
10. `adjust_contrast` (exposure): Control tonal slope and dynamic range separation (Params: factor). Cost: 1 credit.
11. `change_image_gamma` (exposure): Non-linear gamma curve adjustment (0.1 to 3.0) (Params: gamma). Cost: 1 credit.
12. `grayscale_image` (color): Convert image to pure luminance grayscale (Params: none). Cost: 1 credit.
13. `color_photo_to_bw` (color): High-contrast binary black & white threshold (Params: threshold). Cost: 1 credit.
14. `make_sepia_tone` (color): Classic warm vintage photographic tint (Params: intensity). Cost: 1 credit.
15. `invert_colors` (color): Invert RGB chromatic channels (Params: none). Cost: 1 credit.
16. `shift_hue` (color): Rotate color wheel spectrum (-180° to +180°) (Params: degrees). Cost: 1 credit.
17. `change_saturation` (color): Scale color purity and chromatic richness (Params: factor). Cost: 1 credit.
18. `adjust_vibrance` (color): Boost muted tones while protecting skin highlights (Params: factor). Cost: 1 credit.
19. `clip_color_values` (color): Clamp color values between minimum and maximum bounds (Params: min, max). Cost: 1 credit.
20. `hsl_adjustment` (color): Fine-tune Hue, Saturation, and Lightness simultaneously (Params: hue, saturation, lightness). Cost: 1 credit.
21. `sharpen_image` (effects): Enhance edge clarity and micro-contrast (Params: sigma). Cost: 1 credit.
22. `blur_image` (effects): Gaussian smoothing filter across all channels (Params: sigma). Cost: 1 credit.
23. `add_noise` (effects): Inject film grain texture overlay (Params: intensity). Cost: 1 credit.
24. `posterize_effect` (effects): Quantize colors into stylized artistic poster steps (Params: levels). Cost: 1 credit.
25. `glow_effect` (effects): Luminous bloom highlights via composite blend (Params: intensity, radius). Cost: 1 credit.
23. `batch_filter_pipeline` (composite): Multi-filter DAG execution in one atomic pass (`pipeline`: [{ tool, params }]). Cost: 3 credits.
24. `get_image_metadata` (metadata): Extract width, height, format, channels, density without altering pixels. Cost: 1 credit.

> Note: Payloads > 20MB are billed at 5 credits (ADR 0005).