> ## 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.

# Current API Recipes

> Practical calls for the current public, internal-beta, and owner-beta TattooAPI surfaces.

# Current API Recipes

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

<Info>
  Canonical REST base URL: `https://api.tattooapi.com/api/v1`
</Info>

<Warning>
  Public writes, public legal advice, public GraphQL, and public SDK launch are not active yet.
</Warning>

## Public No-Auth Reads

Liveness is the simplest availability check:

```bash theme={"dark"}
curl "https://api.tattooapi.com/api/v1/health/live"
```

Studio discovery is the current promoted public data surface:

```bash theme={"dark"}
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.

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

```bash theme={"dark"}
curl "https://api.tattooapi.com/api/v1/artists?limit=20" \
  -H "X-API-Key: $TATTOO_PARTNER_API_KEY"
```

```bash theme={"dark"}
curl "https://api.tattooapi.com/api/v1/portfolios?limit=20" \
  -H "X-API-Key: $TATTOO_PARTNER_API_KEY"
```

```bash theme={"dark"}
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](/api-reference/portfolio-intake/resolve-artist) and [Create Portfolio Submission](/api-reference/portfolio-intake/create-submission).

Approval creates a private Sanity draft and marks the intake `promoted_to_sanity`; it does not make the asset public. `GET /portfolios` returns only separately promoted `published_public` Convex projections.

## Owner Beta Reads

Owner routes are scoped to the authenticated owner actor.

```bash theme={"dark"}
curl "https://api.tattooapi.com/api/v1/me/designs?limit=20" \
  -H "Authorization: Bearer $TATTOO_ACCESS_TOKEN"
```

```bash theme={"dark"}
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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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`.

## Internal Infrastructure Boundaries

These surfaces are not public product APIs:

* `/api/internal/mcp/*`
* `/api/internal/source-packs/staging`
* `/api/internal/runtime/*`
* private operator dashboards
* local private-network URLs

Use the public docs for builder-facing examples. Use internal PRDs and project-context docs for governed source-pack, private worker, and promotion work.