# Phototology API

> Persistent memory for visual intelligence. Send an image, get structured data back, then get it back free forever. A catalog of composable analysis lenses, each focused on one analysis dimension. Currently available: dating, people, location, atmosphere, entities, accessibility, photo-quality, text-content, composition, moderation, describe, condition, authenticity, color-palette, automobile, vehicle-condition (moderation is always-on and always free). Curated stacks bundle related lenses for specific domains and use-cases: full-analysis, quick-scan, automobile, claims, property, ecommerce, memorial, vehicle-condition. Combine individual lenses to build a custom stack, or augment a curated stack with extra lenses. Browse the live catalog at runtime via GET /v1/modules.

Last updated: 2026-05-30.

## Naming

The concept words are **lens** (a single analysis dimension) and **stack** (a curated or custom bundle of lenses). On the wire, the request body uses the field names `modules` and `preset` for backward compatibility with existing SDK callers. The MCP server exposes the same units as `lenses` and `stacks`. Both naming conventions refer to the same units.

## Pricing

Pricing: $0.01 per credit. Packs at $10/$100/$1,000 for 1,000/10,000/100,000 credits. New users start with 5,000 free credits via the signup ladder (1,000 for verifying an email, 4,000 for adding a card-on-file). The card is never charged automatically. Cache hits and lookup_photo are always free.

- 1 credit per billable lens per image. Moderation is always on and always free.
- Credit packs: Starter 1,000 / $10, Pro 10,000 / $100, Business 100,000 / $1,000. $0.01 per credit at every tier.
- First-purchase bonus: your first credit pack ships 2x the credits at the same price.
- No subscriptions. Credits never expire.

## Delta billing (Registry v2)

Phototology remembers every photo per API key, keyed by SHA-256 and pHash. The second call for the same photo bills zero credits for any lens already run. Only new lenses are sent to the LLM. Pass `refresh: true` on /v1/analyze or /v2/analyze to bypass the cache and force a fresh LLM run. A full cache hit returns `meta.cacheHit: true` and `usage.creditsCharged: 0`.

## Endpoints

- POST /v1/analyze: Analyze a photo with AI vision (supports `refresh: boolean`)
- POST /v2/analyze: Registry v2 analyze with bespoke extraction and delta billing
- POST /v2/lookup: Look up previously analyzed photos by URL or base64 (free, no credits)
- GET /v2/lookup?sha256=<hex>: Direct lookup by sha256 or pHash (free)
- POST /v2/enrich: Write cached lens output back into a photo's EXIF/IPTC/XMP metadata so intelligence travels with the file (5 credits per call)
- GET /v1/modules: List available lenses and curated stacks. Each lens entry includes `billable` (false for `moderation` and `vehicle-condition`), `defaultColumns` (default tabular projection: label, jsonPath, and optional format hint), and `internal: true` for lenses reachable only via a curated stack (e.g. `vehicle-condition`).
- GET /v1/usage: Read the authenticated user's dual-pool credit balance
- GET /v1/health: Health check
- GET /v1/openapi.json: OpenAPI 3.1 spec
- GET /v1/docs: Interactive API documentation
- GET /v1/llms.txt: This file

## Batch export (web)

Web users can download a batch's analyzed photos as a spreadsheet via GET /api/v1/batch/{batchId}/export?format=xlsx|csv|json on phototology.com. The export carries the user's chosen lens columns and identity columns persisted at submit time; legacy batches fall back to defaults derived from the lenses they ran. JSON exports use a default-deny allowlist (storage paths, internal identifiers, and moderation details are stripped). Workspace-scoped: cross-workspace requests surface as 404.

## Lookup response shape

/v2/lookup returns `results.<sha256>.photo` containing `lenses`, a map from lens name to { eventId, output, version, producedAt, coRunHash, provider }. Every lens ever run on the photo is present.

## Authentication

Bearer token: Authorization: Bearer pt_live_...

End users sign in to the phototology.com dashboard with email/password, GitHub OAuth, Google OAuth, or magic-link email. The web app exposes Better Auth at the catch-all route /api/auth/*, including POST /api/auth/sign-in/magic-link (send) and GET /api/auth/magic-link/verify (callback). The platform Bearer token above is separate; it is issued from the dashboard after sign-in and used to authenticate /v1 and /v2 requests against this API.

## Quick Start

npm install @phototology/sdk

## MCP Server

npx -y @phototology/mcp