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:

export TATTOO_API_BASE_URL=https://api.tattooapi.com/api/v1

For local development against this repo:

export TATTOO_API_BASE_URL=http://localhost:3001/api/v1

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.

1. Check Health

Use public liveness for basic availability:

curl "$TATTOO_API_BASE_URL/health/live"

Expected shape:

{
  "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:

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.

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.

For internal beta reads, use the partner portal:

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

For human sessions, send:

Authorization: Bearer YOUR_ACCESS_TOKEN

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

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.

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:

{
  "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.

curl "$TATTOO_API_BASE_URL/studios?city=Los%20Angeles&limit=5"

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

{
  "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:

Start Here

Research Archive

Platform Readiness

Quickstart

Quickstart

What You Can Do Today

Base URL

1. Check Health

2. Get Access

3. Search the Dataset

4. List Studios

5. Understand Trust

​Quickstart

​What You Can Do Today

​Base URL

​1. Check Health

​2. Get Access

​3. Search the Dataset

​4. List Studios

​5. Understand Trust

Quickstart

What You Can Do Today

Base URL

1. Check Health

2. Get Access

3. Search the Dataset

4. List Studios

5. Understand Trust