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

# List Portfolios

> Authenticated creative read-beta endpoint returning public portfolio projections.

<Note>
  **Posture:** Authenticated internal beta. The caller must resolve to a mapped TattooAPI actor before access is granted.
</Note>

<Warning>
  **Write boundary:** Public writes are blocked. Do not build production flows assuming mutation is live on this route family.
</Warning>

Canonical request URL: `https://api.tattooapi.com/api/v1/portfolios`.

# List Portfolios

`GET /portfolios` is an authenticated read-beta endpoint.

It returns the public projection of portfolio assets only. Records must be `publish_state = published_public` and must not contradict the rights posture.

An operator-approved intake with status `promoted_to_sanity` is still a private Sanity draft. It does not appear here until a separate governed promotion creates a `published_public` Convex runtime projection with approved distribution posture.

## Auth

Use a WorkOS organization API key mapped with `portfolios:read`:

```bash theme={"dark"}
curl "$TATTOO_API_BASE_URL/portfolios?limit=20" \
  -H "X-API-Key: $TATTOO_PARTNER_API_KEY"
```

Mapped human sessions can use a WorkOS AuthKit bearer token:

```bash theme={"dark"}
curl "$TATTOO_API_BASE_URL/portfolios?limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Query Parameters

| Parameter   | Type    | Notes                       |
| ----------- | ------- | --------------------------- |
| `page`      | integer | Default `1`                 |
| `limit`     | integer | Default `20`, max `100`     |
| `artist_id` | string  | Filter by runtime artist id |
| `style_id`  | string  | Filter by style id          |
| `featured`  | boolean | `true` or `false`           |
| `tags`      | string  | Comma-separated tag filter  |

## Response Shape

```json theme={"dark"}
{
  "success": true,
  "data": [
    {
      "id": "portfolio-asset:ashlewis-instagram-overlay-2026-04-20",
      "artist_id": "artist:example",
      "title": "Black and grey healed sleeve",
      "image_url": "https://example.com/image.jpg",
      "tags": ["black_and_grey"],
      "is_public": true,
      "publish_state": "published_public",
      "provenance": {},
      "trust": {}
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

## Write Boundary

`POST`, `PUT`, `PATCH`, and `DELETE` are explicitly blocked on this public route family.

Use owner-scoped routes only for current owner reads. Owner writes remain gated until a governed owner mutation contract lands.