Current API Recipes

These examples describe the API surface that is safe to build against today.

Canonical REST origin: https://api.tattooapi.com. Examples below use the /api/v1 compatibility paths.

Public writes, public legal advice, public GraphQL, and public SDK launch are not active yet.

Public No-Auth Reads

Liveness is the simplest availability check:

curl "https://api.tattooapi.com/api/v1/health/live"

Studio discovery is the current promoted public data surface:

curl "https://api.tattooapi.com/api/v1/studios?state=HI&limit=10"

Use this for public discovery experiments. Do not assume artist, portfolio, design, booking, payment, or law endpoints are public just because route files exist in the repo.

Internal Beta Reads

Internal beta routes require approved authentication and a mapped TattooAPI actor.

curl "https://api.tattooapi.com/api/v1/search?q=blackwork&type=artist&limit=5" \
  -H "X-API-Key: $TATTOO_PARTNER_API_KEY"

curl "https://api.tattooapi.com/api/v1/artists?limit=20" \
  -H "X-API-Key: $TATTOO_PARTNER_API_KEY"

curl "https://api.tattooapi.com/api/v1/portfolios?limit=20" \
  -H "X-API-Key: $TATTOO_PARTNER_API_KEY"

curl "https://api.tattooapi.com/api/v1/designs?search=dragon&limit=20" \
  -H "Authorization: Bearer $TATTOO_ACCESS_TOKEN"

Missing or invalid credentials return 401. Valid credentials without a mapped TattooAPI actor return 403.

Governed Portfolio Intake

Approved service integrations such as Permanent use the private portfolio-intake contract to resolve an artist, stage media, verify upload completion, and poll review status. A separate mapped human operator performs approval. Start with Resolve Artist Identity and Create Portfolio Submission. Approval creates an approved private draft and marks the intake promoted_to_sanity; it does not make the asset public. GET /portfolios returns only separately promoted published_public portfolio projections.

Owner Beta Reads

Owner routes are scoped to the authenticated owner actor.

curl "https://api.tattooapi.com/api/v1/me/designs?limit=20" \
  -H "Authorization: Bearer $TATTOO_ACCESS_TOKEN"

curl "https://api.tattooapi.com/api/v1/me/portfolio-assets?limit=20" \
  -H "Authorization: Bearer $TATTOO_ACCESS_TOKEN"

Owner routes can return draft, owner_private, and published_public creative records, but only for records mapped to the authenticated studio or artist.

Blocked Public Writes

Public mutation attempts must remain blocked:

curl -X POST "https://api.tattooapi.com/api/v1/studios" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Studio"}'

Expected posture: public_write_blocked.

Gated Owner Writes

Owner mutation attempts must remain gated until the approved write contract is live:

curl -X PATCH "https://api.tattooapi.com/api/v1/me/designs/design:example" \
  -H "Authorization: Bearer $TATTOO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"publish_state":"published_public"}'

Expected posture: owner_write_gated.

Access Limits

Use only documented endpoints and approved credentials. Public writes, public legal advice, public GraphQL, and public SDK launch are not active yet.

Start Here

Integration Guides

Current API Recipes

Current API Recipes

Public No-Auth Reads

Internal Beta Reads

Governed Portfolio Intake

Owner Beta Reads

Blocked Public Writes

Gated Owner Writes

Access Limits

​Current API Recipes

​Public No-Auth Reads

​Internal Beta Reads

​Governed Portfolio Intake

​Owner Beta Reads

​Blocked Public Writes

​Gated Owner Writes

​Access Limits

Current API Recipes

Public No-Auth Reads

Internal Beta Reads

Governed Portfolio Intake

Owner Beta Reads

Blocked Public Writes

Gated Owner Writes

Access Limits