> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tattoo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Supported current runtime surface for TattooAPI.

This reference documents the endpoints that are real and supported today.

## Canonical Base URL

Use `https://api.tattooapi.com/api/v1` for public docs, SDK generation, and external integrations.

Other Tattoo Company hosts may proxy or alias internal traffic, but `https://api.tattooapi.com/api/v1` is the canonical developer-facing base URL.

## Supported Surface

* `GET /health/live` - public liveness read
* `GET /health/ready` - production readiness read
* `GET /studios` - public directory read
* `GET /artists` and `GET /artists/{id}` - authenticated artist read beta
* `GET /search` - authenticated discovery read beta
* `GET /portfolios` and `GET /designs` - authenticated creative read beta returning public projections
* `GET /me/portfolio-assets` and `GET /me/designs` - authenticated owner-scoped creative read beta

## Current Public Boundary

The public documentation surface is intentionally discovery-first while Wave D and Wave E close:

* Public no-auth reads are limited to health and studios.
* Authenticated beta routes require approved partner or owner access.
* Authenticated discovery reads can be used internally and in controlled SDK beta flows.
* Authenticated creative reads return projection-filtered portfolio/design data.
* Owner creative reads are scoped to the authenticated owner actor and keep draft/private records out of cross-studio visibility.
* Public write expansion remains blocked.
* Owner write methods are present only as gated contract responses.
* Public webhook and legacy auth ingress routes exist for compatibility, but they are not the promoted public API expansion path.
* Future owner-scoped writes and public intake flows will be split onto separate route families rather than broad public mutation endpoints.
* Local API key management routes are retired and return `410`.
* Internal worker and operator tooling does not add public API routes.
* Internal API beta access uses partner-issued credentials, but detailed team setup remains repo-internal.
* Wave F+ public read, SDK, free-tool, dataset, and intelligence surfaces remain gated until runtime truth, review lineage, rights, consent, privacy, and audit posture are proven.

## Important Constraint

The current runtime still has mixed legacy response envelopes. These docs describe the current behavior truthfully instead of pretending the runtime is already fully unified.

See [Project Status](/project-status) for the current Wave D/E cutover posture and the public-surface boundaries.

See [API Access Model](/guides/api-access-model) and [Future Wave Gates](/guides/future-wave-gates) for the current public/private split.

See [Current API Surface Map](/api-reference/surface-map) for the route-by-route public, beta, owner, internal, deprecated, and blocked posture.

## Source of Truth

* Domain model: the TattooAPI ontology
* Current endpoint metadata: the OpenAPI contract used by these docs
* API access posture: the published access model and surface map