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

# Quickstart

> What you can safely do today with TattooAPI: public reads, internal beta reads, and private worker flows.

# Quickstart

TattooAPI is live as a governed control plane. The first decision is which access lane you are in.

## What You Can Do Today

| Lane                          | Who it is for                                       | What works now                                                    | Auth                                             |
| ----------------------------- | --------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------ |
| Public reads                  | External builders and docs readers                  | Health and studio discovery                                       | None                                             |
| Internal beta reads           | TattooAPI team, mapped owners, controlled SDK tests | Search, artists, portfolios, designs, owner creative reads        | Approved credential plus TattooAPI actor mapping |
| Private worker/operator flows | Approved private workers and operators              | Review context, portfolio intake staging, classification evidence | Partner machine key stored in a secret manager   |

Public writes are blocked. Private workers cannot publish public surfaces, mutate canonical records, or bypass human review.

## Base URL

Use the canonical public API base URL:

```bash theme={"dark"}
export TATTOO_API_BASE_URL=https://api.tattooapi.com/api/v1
```

For local development against this repo:

```bash theme={"dark"}
export TATTOO_API_BASE_URL=http://localhost:3001/api/v1
```

<Note>
  The canonical public API host is `api.tattooapi.com`. `api.tattoo.co` may remain as a marketplace/internal alias for tattoo.co-owned applications, but docs and SDKs should prefer `api.tattooapi.com`.
</Note>

## 1. Check Health

Use public liveness for basic availability:

```bash theme={"dark"}
curl "$TATTOO_API_BASE_URL/health/live"
```

Expected shape:

```json theme={"dark"}
{
  "status": "ok",
  "timestamp": "2026-04-20T12:00:00.000Z",
  "uptime": 1234.56,
  "service": "tattoo-api"
}
```

Use production readiness before relying on intake, private worker, or approved portfolio workflows:

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

Expected production posture today is `status: "ready"` with `publicWritesAllowed: false`.

## 2. Get Access

Public users do not need auth for health or studio discovery.

Authenticated internal beta access uses approved partner credentials. Team members use bearer tokens, and machine or private worker tools use partner API keys.

<Warning>
  The legacy `POST /auth/register` and `POST /auth/login` routes may still exist in the runtime, but they are not the default path for new internal beta access.
</Warning>

For internal beta reads, use the partner portal:

1. Sign in at `https://partners.tattoo.dev`.
2. Select your approved organization.
3. Create a docs playground key.
4. Confirm the key is mapped by TattooAPI.
5. Open the Mintlify playground on `https://docs.tattoo.dev` and run your first request.

For human sessions, send:

```bash theme={"dark"}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

For machine, server, SDK, and private worker calls, prefer:

```bash theme={"dark"}
X-API-Key: YOUR_PARTNER_API_KEY
```

Response semantics are intentionally simple:

* `401` means the credential is missing or invalid.
* `403` means the credential is valid but has no active TattooAPI actor mapping for it.
* `410` means a legacy local API-key route is retired.

## 3. Search the Dataset

`GET /search` currently requires authenticated internal beta access.

```bash theme={"dark"}
curl "$TATTOO_API_BASE_URL/search?q=traditional&type=studio&limit=5" \
  -H "X-API-Key: YOUR_WORKOS_API_KEY"
```

The response uses a success wrapper:

```json theme={"dark"}
{
  "success": true,
  "data": {
    "results": [],
    "total": 0,
    "pagination": {
      "page": 1,
      "limit": 5,
      "total_pages": 0,
      "has_next": false,
      "has_prev": false
    }
  }
}
```

## 4. List Studios

`GET /studios` is the current public discovery endpoint.

```bash theme={"dark"}
curl "$TATTOO_API_BASE_URL/studios?city=Los%20Angeles&limit=5"
```

Unlike `search`, the current studios endpoint still uses the legacy paginated wrapper:

```json theme={"dark"}
{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 0,
    "totalPages": 0,
    "hasNext": false,
    "hasPrev": false
  },
  "error": null
}
```

## 5. Understand Trust

Before you build on top of the current data, load the trust model:

* `recordState` tells you if a record is `raw`, `normalized`, `curated`, `verified`, or `deprecated`
* `verificationStatus` tells you how much trust has been established
* `licenseStatus` and `consentLevel` tell you what kinds of downstream use are allowed

For portfolio intake, identity evidence is not KYC. `unmatched`, `phone_matched`, `review_required`, and `verified_by_operator` describe review evidence only; they do not claim legal identity verification.

Next:

* [Authentication](/authentication)
* [Production Readiness And Control Plane](/guides/production-readiness-control-plane)
* [Portfolio Intake Workflow](/guides/portfolio-intake-workflow)
* [Trust Model](/trust-model)
* [Search](/search)
* [Studios](/studios)
* [Future Wave Gates](/guides/future-wave-gates)