---
title: "Create an explicit share link"
method: POST
path: "/api/shares"
---

# Create an explicit share link

`POST /api/shares`

## Request

- Base URL: `https://api.peelaway.io`
- URL: `https://api.peelaway.io/api/shares`
- Auth: one of:
  - none
  - HTTP bearer
  - API key in cookie `better-auth.session_token`

Public styles, publications, profiles, palettes and allowlisted resources can be shared anonymously. Sharing owned completed job IDs requires a signed-in session or API key. Image sets are unlisted (anyone holding the token can view); original inputs are excluded unless includeBefore is explicitly true. Use a UUID flowId for idempotent retries. Never share API keys or signed output URLs.

## Request body

- object
  - `flowId` string, uuid, required
  - `surface` string, required
  - `placement` string, required
  - `target` union, required
    - object
      - `kind` 'image' | 'collection', required
      - `jobIds` string[], required
      - `includeBefore` boolean
      - `voting` boolean
      - `captions` string[]
    - object
      - `kind` 'publication' | 'style', required
      - `id` string, uuid, required
    - object
      - `kind` 'profile', required
      - `username` string, required
    - object
      - `kind` 'tool' | 'content', required
      - `path` string, required: Allowlisted canonical public path without query or fragment
    - object
      - `kind` 'palette', required
      - `colors` string[], required

## Response `200`

id, token, path (/username/id), and visibility

## Other responses

- `400`: Invalid target
- `403`: Owned images require authentication
- `404`: Target is private, unfinished, or unavailable
- `409`: Idempotency conflict or revoked link
- `429`: Rate limited

---

[API](https://skmtc.dev/peelaway/apis/peelaway-image-api.md) · [All operations](https://skmtc.dev/peelaway/apis/peelaway-image-api/llms.txt) · [OpenAPI document](https://skmtc.dev/peelaway/apis/peelaway-image-api/revisions/8ce45533c9d0?raw)