Current API Surface Map

TattooAPI is in a conservative public-read phase. The runtime has more route files than the promoted public surface, but only a small set should be treated as supported product API today.

This page is generated by npm run generate:mintlify-current-api-surface. Do not hand-edit route posture here; update the source contracts and rerun the generator.

Canonical Hosts

Surface	URL	Notes
Public docs	`https://docs.tattoo.dev`	Mintlify-hosted developer docs.
REST API	`https://api.tattooapi.com/api/v1`	Canonical public/API docs base URL.
Docs MCP	`https://docs.tattoo.dev/mcp`	Read-only docs search/filesystem endpoint generated by Mintlify.
Marketplace/internal alias	`https://api.tattoo.co/api/v1`	Compatibility alias only; SDKs and docs should prefer `api.tattooapi.com`.

Public No-Auth Reads

These endpoints are the promoted public product surface today.

Route	Methods	Status	Notes
`/api/v1/health`	`GET`	Public	Operational health and runtime posture.
`/api/v1/studios`	`GET`	Public	Studio discovery projection.

Public studio writes are blocked.

Existing Public Ingress That Is Not New Product Surface

Some legacy or infrastructure routes are reachable without the authenticated beta flow. They should not be confused with the promoted public API roadmap.

Route	Methods	Status	Notes
`/api/v1/docs`	`GET`	Public metadata	Runtime-served API metadata.
`/api/v1/search/autocomplete`	`GET`	Public helper	Legacy/autocomplete helper, not the main internal-beta search endpoint.
`/api/v1/auth/login`	`POST`	Legacy auth ingress	Legacy compatibility route; partner credentials are the default path for internal beta.
`/api/v1/auth/register`	`POST`	Legacy auth ingress	Legacy compatibility route; not the current access-management direction.
`/api/v1/auth/refresh`	`POST`	Legacy auth ingress	Compatibility route.
`/api/v1/auth/forgot-password`	`POST`	Legacy auth ingress	Compatibility route.
`/api/v1/auth/reset-password`	`POST`	Legacy auth ingress	Compatibility route.
`/api/v1/webhooks/stripe`	`POST`	Provider webhook	Public webhook ingress, not a user-facing write API.

The current access model keeps these legacy paths from becoming the promoted team, owner, or private-worker auth model.

Authenticated Internal Beta Reads

These routes require approved credentials plus an active TattooAPI actor mapping.

Route	Methods	Status	Notes
`/api/v1/search`	`GET`	Internal beta	Unified discovery across studios, artists, and designs.
`/api/v1/artists`	`GET`	Internal beta	Runtime-backed artist catalog.
`/api/v1/artists/{id}`	`GET`	Internal beta	Runtime-backed artist detail.
`/api/v1/portfolios`	`GET`	Internal beta	Public creative projection only.
`/api/v1/portfolios/{id}`	`GET`	Internal beta	Public creative projection only.
`/api/v1/designs`	`GET`	Internal beta	Public design projection only.
`/api/v1/designs/{id}`	`GET`	Internal beta	Public design projection only.

These routes exist so internal SDKs, private tools, and early operator workflows can test real read envelopes without widening the public product surface.

Blocked-Write Runtime Read Families

Several noun families have useful runtime-backed reads while public writes stay blocked.

Route family	Read posture	Write posture
`/api/v1/artists*`	Authenticated runtime read beta	Public writes blocked.
`/api/v1/designs*`	Authenticated creative public projection	Public writes blocked.
`/api/v1/inventory*`	Runtime read surface	Public writes blocked.
`/api/v1/payments*`	Runtime read surface	Public writes blocked.
`/api/v1/portfolios*`	Authenticated creative public projection	Public writes blocked.
`/api/v1/studios*`	Public/runtime read projection	Public writes blocked.

Two booking route families still have mixed runtime-read and legacy-write posture. They are not promoted as public write APIs and should not be used as the pattern for new route families.

Owner-Scoped Creative Beta

These routes require approved credentials plus owner mapping to the relevant studio or artist scope.

Route	Methods	Status	Notes
`/api/v1/me/portfolio-assets`	`GET`	Owner beta	Owner-filtered portfolio assets across draft/private/public states.
`/api/v1/me/portfolio-assets/{id}`	`GET`	Owner beta	Owner-filtered portfolio asset detail.
`/api/v1/me/designs`	`GET`	Owner beta	Owner-filtered designs across private/public states.
`/api/v1/me/designs/{id}`	`GET`	Owner beta	Owner-filtered design detail.

Owner creative writes are contract-gated. POST, PUT, PATCH, and DELETE return owner-write-gated boundary responses until governed owner mutation contracts are promoted.

Internal-Only Infrastructure

These are not public API products.

Surface	Status	Notes
Private operator dashboard	Internal only	Local operator and review tooling surface.
Ontology guidance	Internal only	Read-first ontology guidance for acquisition tooling.
Source-pack staging upload	Internal only	Protected staging path for acquisition artifacts.
Runtime mutation routes	Internal only	Approval-gated operator workflows only.
Runtime admin dashboard	Internal only	Canonical runtime operations.

Blocked Or Deprecated

Surface	Current posture
Public writes	Blocked.
Public legal advice	Blocked. Law data is citation-backed staging/review only.
Public SEO page generation	Blocked. SEO demand descriptors stay internal review inputs.
Public SDK launch	Wave F gated.
Public GraphQL endpoint	Wave F+ gated; current GraphQL work is PRD/schema planning.
Local TattooAPI API-key management	Retired; partner API keys are the credential authority.
Broad scraper-to-runtime import	Blocked. Scrapers produce source packs only.

Runtime Route Inventory

This inventory is not the same thing as the promoted public surface. It is included so documentation drift is visible.

Route	Methods	Runtime file
`/api/v1/analytics/artist/{id}`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/analytics/artist/[id].ts`
`/api/v1/analytics/dashboard`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/analytics/dashboard.ts`
`/api/v1/analytics/platform`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/analytics/platform.ts`
`/api/v1/analytics/revenue`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/analytics/revenue.ts`
`/api/v1/analytics/studio/{id}`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/analytics/studio/[id].ts`
`/api/v1/api-keys`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/api-keys/index.ts`
`/api/v1/api-keys/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/api-keys/[id].ts`
`/api/v1/artists`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/artists/index.ts`
`/api/v1/artists/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/artists/[id]/index.ts`
`/api/v1/artists/automation/inquiries`	`GET`, `POST`, `PUT`	`apps/tattoo-api/api-implementation/pages/api/v1/artists/automation/inquiries.ts`
`/api/v1/auth/forgot-password`	`POST`	`apps/tattoo-api/api-implementation/pages/api/v1/auth/forgot-password.ts`
`/api/v1/auth/login`	`POST`, `OPTIONS`	`apps/tattoo-api/api-implementation/pages/api/v1/auth/login.ts`
`/api/v1/auth/profile`	`GET`, `PUT`	`apps/tattoo-api/api-implementation/pages/api/v1/auth/profile.ts`
`/api/v1/auth/refresh`	`POST`, `OPTIONS`	`apps/tattoo-api/api-implementation/pages/api/v1/auth/refresh.ts`
`/api/v1/auth/register`	`POST`, `OPTIONS`	`apps/tattoo-api/api-implementation/pages/api/v1/auth/register.ts`
`/api/v1/auth/reset-password`	`POST`	`apps/tattoo-api/api-implementation/pages/api/v1/auth/reset-password.ts`
`/api/v1/bookings`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/bookings/index.ts`
`/api/v1/bookings/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/bookings/[id]/index.ts`
`/api/v1/bookings/create`	`POST`	`apps/tattoo-api/api-implementation/pages/api/v1/bookings/create.ts`
`/api/v1/brands`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/brands/index.ts`
`/api/v1/brands/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/brands/[id]/index.ts`
`/api/v1/brands/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/brands/[id].ts`
`/api/v1/brands/{id}/analytics`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/brands/[id]/analytics.ts`
`/api/v1/brands/{id}/studios`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/brands/[id]/studios.ts`
`/api/v1/clients`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/clients/index.ts`
`/api/v1/clients/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/clients/[id]/index.ts`
`/api/v1/clients/onboard`	`POST`	`apps/tattoo-api/api-implementation/pages/api/v1/clients/onboard.ts`
`/api/v1/communication/messages`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/communication/messages.ts`
`/api/v1/communication/notifications`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/communication/notifications.ts`
`/api/v1/compliance/consent`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/compliance/consent.ts`
`/api/v1/compliance/records`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/compliance/records.ts`
`/api/v1/compliance/requirements`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/compliance/requirements.ts`
`/api/v1/compliance/requirements/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/compliance/requirements/[id].ts`
`/api/v1/compliance/verify`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/compliance/verify.ts`
`/api/v1/designs`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/designs/index.ts`
`/api/v1/designs/{id}`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/designs/[id].ts`
`/api/v1/designs/{id}/favorite`	`POST`	`apps/tattoo-api/api-implementation/pages/api/v1/designs/[id]/favorite.ts`
`/api/v1/docs`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/docs.ts`
`/api/v1/health`	`GET`, `OPTIONS`	`apps/tattoo-api/api-implementation/pages/api/v1/health.ts`
`/api/v1/health/live`	`GET`, `OPTIONS`	`apps/tattoo-api/api-implementation/pages/api/v1/health/live.ts`
`/api/v1/health/ready`	`GET`, `OPTIONS`	`apps/tattoo-api/api-implementation/pages/api/v1/health/ready.ts`
`/api/v1/integrations/calendar`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/integrations/calendar.ts`
`/api/v1/integrations/social`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/integrations/social.ts`
`/api/v1/integrations/webhooks`	`GET`, `POST`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/integrations/webhooks.ts`
`/api/v1/inventory`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/inventory/index.ts`
`/api/v1/inventory/{id}`	`GET`, `PUT`, `PATCH`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/inventory/[id].ts`
`/api/v1/inventory/items`	`GET`, `POST`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/inventory/items.ts`
`/api/v1/inventory/low-stock`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/inventory/low-stock.ts`
`/api/v1/inventory/reports`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/inventory/reports.ts`
`/api/v1/inventory/suppliers`	`GET`, `POST`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/inventory/suppliers.ts`
`/api/v1/marketplace/categories`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/marketplace/categories.ts`
`/api/v1/marketplace/categories/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/marketplace/categories/[id].ts`
`/api/v1/marketplace/featured`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/marketplace/featured.ts`
`/api/v1/marketplace/featured/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/marketplace/featured/[id].ts`
`/api/v1/marketplace/purchase`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/marketplace/purchase.ts`
`/api/v1/me/designs`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/me/designs/index.ts`
`/api/v1/me/designs/{id}`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/me/designs/[id].ts`
`/api/v1/me/portfolio-assets`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/me/portfolio-assets/index.ts`
`/api/v1/me/portfolio-assets/{id}`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/me/portfolio-assets/[id].ts`
`/api/v1/micro-transactions/purchase`	`POST`	`apps/tattoo-api/api-implementation/pages/api/v1/micro-transactions/purchase.ts`
`/api/v1/mobile/config`	`GET`, `POST`, `PUT`	`apps/tattoo-api/api-implementation/pages/api/v1/mobile/config.ts`
`/api/v1/mobile/feedback`	`GET`, `POST`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/mobile/feedback.ts`
`/api/v1/mobile/push-tokens`	`GET`, `POST`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/mobile/push-tokens.ts`
`/api/v1/mobile/upload`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/mobile/upload.ts`
`/api/v1/notifications`	`GET`, `POST`, `PUT`	`apps/tattoo-api/api-implementation/pages/api/v1/notifications/index.ts`
`/api/v1/notifications/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/notifications/[id]/index.ts`
`/api/v1/payments`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/payments/index.ts`
`/api/v1/payments/{id}`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/payments/[id].ts`
`/api/v1/portfolios`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/portfolios/index.ts`
`/api/v1/portfolios/{id}`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/portfolios/[id].ts`
`/api/v1/reports/bookings`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/reports/bookings.ts`
`/api/v1/reports/custom`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/reports/custom.ts`
`/api/v1/reports/custom/{id}`	`GET`, `POST`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/reports/custom/[id].ts`
`/api/v1/reports/performance`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/reports/performance.ts`
`/api/v1/reports/revenue`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/reports/revenue.ts`
`/api/v1/reviews`	`GET`, `POST`	`apps/tattoo-api/api-implementation/pages/api/v1/reviews/index.ts`
`/api/v1/reviews/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/reviews/[id].ts`
`/api/v1/reviews/{id}/helpful`	`POST`	`apps/tattoo-api/api-implementation/pages/api/v1/reviews/[id]/helpful.ts`
`/api/v1/search`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/search/index.ts`
`/api/v1/search/autocomplete`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/search/autocomplete.ts`
`/api/v1/studios`	`GET`, `POST`, `OPTIONS`	`apps/tattoo-api/api-implementation/pages/api/v1/studios/index.ts`
`/api/v1/studios/{id}`	`GET`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/studios/[id]/index.ts`
`/api/v1/users`	`GET`	`apps/tattoo-api/api-implementation/pages/api/v1/users/index.ts`
`/api/v1/users/{id}/delete`	`DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/users/[id]/delete.ts`
`/api/v1/users/preferences`	`GET`, `POST`, `PUT`, `DELETE`	`apps/tattoo-api/api-implementation/pages/api/v1/users/preferences.ts`
`/api/v1/webhooks/stripe`	`POST`	`apps/tattoo-api/api-implementation/pages/api/v1/webhooks/stripe.ts`

How To Build Against This

Use public no-auth reads for public studio discovery and uptime checks.
Use authenticated internal beta routes for team and SDK experiments.
Use owner routes only when the caller maps to the owning studio or artist.
Treat source-pack, private worker, and runtime admin surfaces as internal infrastructure.
Do not build product UX that assumes public writes, public compliance claims, public GraphQL, or public SEO pages are live.

See API Access Model for projection and ownership rules.

Overview

Discovery

Creative

Portfolio Intake

Current API Surface Map

Current API Surface Map

Canonical Hosts

Public No-Auth Reads

Existing Public Ingress That Is Not New Product Surface

Authenticated Internal Beta Reads

Blocked-Write Runtime Read Families

Owner-Scoped Creative Beta

Internal-Only Infrastructure

Blocked Or Deprecated

Runtime Route Inventory

How To Build Against This

​Current API Surface Map

​Canonical Hosts

​Public No-Auth Reads

​Existing Public Ingress That Is Not New Product Surface

​Authenticated Internal Beta Reads

​Blocked-Write Runtime Read Families

​Owner-Scoped Creative Beta

​Internal-Only Infrastructure

​Blocked Or Deprecated

​Runtime Route Inventory

​How To Build Against This

Current API Surface Map

Canonical Hosts

Public No-Auth Reads

Existing Public Ingress That Is Not New Product Surface

Authenticated Internal Beta Reads

Blocked-Write Runtime Read Families

Owner-Scoped Creative Beta

Internal-Only Infrastructure

Blocked Or Deprecated

Runtime Route Inventory

How To Build Against This