PunkMaker API reference
63 operations. This reference and the OpenAPI 3.1 document are generated from the same Zod schemas.
Download OpenAPI JSONGenerate a 24 × 24 head
Call from your server with an integration key. The response contains a PNG data URL in image, its dimensions and model provenance. Use variant: "naked" for a 32 × 32 body.
curl https://punks.art/api/nakedpunks/generate \
--max-time 280 \
-H "Content-Type: application/json" \
-H "x-api-key: $PUNKMAKER_API_KEY" \
-d '{"punkId":8348,"variant":"head","prompt":"blue sunglasses","engine":"gpt25"}'For a conversation, send the returned image as imageDataUrl with the next prompt and the same variant. Supply exactly one image source per request. The endpoint is stateless.
Generation validates requests and responses with Zod. Existing legacy routes retain their own parsers; their schemas document the supported contract. Provider proxies retain upstream payloads. Authentication and error formats are described per operation.
Rendering
GET/api/derivatives/{derivative}/{punkId}/imageDownload a canonical derivative PNG
Fixed canonical composition and nearest-neighbor scale 10: MeePunks 240×240 with blue background; NakedPunks 320×320 with transparent background, including the ID 2113 variant. No custom rendering options. Available before an edition is deployed. Cached publicly for one hour with a one-minute stale window.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| derivative * | path | derivative parameter |
| punkId * | path | punkId parameter |
Request and response schemas
{
"operationId": "renderCanonicalDerivative",
"summary": "Download a canonical derivative PNG",
"description": "Fixed canonical composition and nearest-neighbor scale 10: MeePunks 240×240 with blue background; NakedPunks 320×320 with transparent background, including the ID 2113 variant. No custom rendering options. Available before an edition is deployed. Cached publicly for one hour with a one-minute stale window.",
"tags": [
"Rendering"
],
"security": [],
"parameters": [
{
"name": "derivative",
"in": "path",
"required": true,
"description": "derivative parameter",
"schema": {
"type": "string",
"enum": [
"meepunks",
"nakedpunks"
]
}
},
{
"name": "punkId",
"in": "path",
"required": true,
"description": "punkId parameter",
"schema": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,3})$"
}
}
],
"responses": {
"200": {
"description": "Canonical artwork PNG with an inline filename.",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/punksSearch canonical punks
Search the 10,000 canonical IDs. All requested traits must match. traitCount includes the base type. Pagination defaults to 100; an unknown trait returns an empty list.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| limit | query | limit parameter |
| offset | query | offset parameter |
| includeTraits | query | includeTraits parameter |
| type | query | type parameter |
| traits | query | Comma-separated trait slugs or IDs. |
| traitCount | query | traitCount parameter |
Request and response schemas
{
"operationId": "listPunks",
"summary": "Search canonical punks",
"description": "Search the 10,000 canonical IDs. All requested traits must match. traitCount includes the base type. Pagination defaults to 100; an unknown trait returns an empty list.",
"tags": [
"Rendering"
],
"security": [],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"description": "limit parameter",
"schema": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "offset parameter",
"schema": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "includeTraits",
"in": "query",
"required": false,
"description": "includeTraits parameter",
"schema": {
"default": "true",
"type": "string",
"enum": [
"true",
"false"
]
}
},
{
"name": "type",
"in": "query",
"required": false,
"description": "type parameter",
"schema": {
"type": "string"
}
},
{
"name": "traits",
"in": "query",
"required": false,
"description": "Comma-separated trait slugs or IDs.",
"schema": {
"description": "Comma-separated trait slugs or IDs.",
"type": "string"
}
},
{
"name": "traitCount",
"in": "query",
"required": false,
"description": "traitCount parameter",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tokenId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"id": {
"type": "string"
},
"traits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"gender": {
"type": "string"
}
},
"required": [
"id",
"slug",
"name",
"category"
],
"additionalProperties": {}
}
},
"traitCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"tokenId",
"id"
],
"additionalProperties": false
}
},
"total": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"offset": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"limit": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"hasMore": {
"type": "boolean"
},
"filters": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"traits": {
"type": "array",
"items": {
"type": "string"
}
},
"traitCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"additionalProperties": false
}
},
"required": [
"success",
"data",
"total",
"offset",
"limit"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/punks/{id}Render a canonical punk
Select a canonical ID, then head or naked body with naked. JSON includes traits, palette and pixels; format=pixels omits metadata. The original head grid is 24x24. Body extensions can exceed the base 32x32 bounds.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| id * | path | id parameter |
| format | query | format parameter |
| naked | query | yes, true or 1 renders a full body (32x32 minimum); otherwise a 24x24 head. |
| dingdong | query | yes/true/1 enables the body accessory; canonical punk rendering also accepts tripod, in-a-sock and tripod-in-a-sock. |
| size | query | Rendered image size. Defaults to the native grid size (24 or 32). |
| background | query | Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer. |
| ribbon | query | Ribbon color or preset. |
| ansiSize | query | ANSI output height. |
| socks | query | yes/true/1 or a sock color. |
| nips | query | clown enables clown nips. |
Request and response schemas
{
"operationId": "renderPunk",
"summary": "Render a canonical punk",
"description": "Select a canonical ID, then head or naked body with naked. JSON includes traits, palette and pixels; format=pixels omits metadata. The original head grid is 24x24. Body extensions can exceed the base 32x32 bounds.",
"tags": [
"Rendering"
],
"security": [],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id parameter",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
{
"name": "format",
"in": "query",
"required": false,
"description": "format parameter",
"schema": {
"default": "json",
"type": "string",
"enum": [
"json",
"pixels",
"svg",
"png",
"ascii",
"ansi"
]
}
},
{
"name": "naked",
"in": "query",
"required": false,
"description": "yes, true or 1 renders a full body (32x32 minimum); otherwise a 24x24 head.",
"schema": {
"description": "yes, true or 1 renders a full body (32x32 minimum); otherwise a 24x24 head.",
"type": "string"
}
},
{
"name": "dingdong",
"in": "query",
"required": false,
"description": "yes/true/1 enables the body accessory; canonical punk rendering also accepts tripod, in-a-sock and tripod-in-a-sock.",
"schema": {
"description": "yes/true/1 enables the body accessory; canonical punk rendering also accepts tripod, in-a-sock and tripod-in-a-sock.",
"type": "string"
}
},
{
"name": "size",
"in": "query",
"required": false,
"description": "Rendered image size. Defaults to the native grid size (24 or 32).",
"schema": {
"description": "Rendered image size. Defaults to the native grid size (24 or 32).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "background",
"in": "query",
"required": false,
"description": "Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer.",
"schema": {
"description": "Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer.",
"type": "string"
}
},
{
"name": "ribbon",
"in": "query",
"required": false,
"description": "Ribbon color or preset.",
"schema": {
"description": "Ribbon color or preset.",
"type": "string"
}
},
{
"name": "ansiSize",
"in": "query",
"required": false,
"description": "ANSI output height.",
"schema": {
"description": "ANSI output height.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "socks",
"in": "query",
"required": false,
"description": "yes/true/1 or a sock color.",
"schema": {
"description": "yes/true/1 or a sock color.",
"type": "string"
}
},
{
"name": "nips",
"in": "query",
"required": false,
"description": "clown enables clown nips.",
"schema": {
"description": "clown enables clown nips.",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Format selected by the format query parameter. PNG and SVG are scaled; JSON pixels use native coordinates.",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/svg+xml": {
"schema": {
"type": "string"
}
},
"text/plain": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"pixels": {
"type": "array",
"items": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"hex": {
"type": "string"
}
},
"required": [
"x",
"y",
"hex"
],
"additionalProperties": {}
}
},
"tokenId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"traits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"gender": {
"type": "string"
}
},
"required": [
"id",
"slug",
"name",
"category"
],
"additionalProperties": {}
}
},
"pixelCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"colors": {
"type": "array",
"items": {
"type": "string"
}
},
"urls": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"id",
"pixels",
"tokenId",
"traits",
"pixelCount",
"colors",
"urls"
],
"additionalProperties": false
}
},
"required": [
"success",
"data"
],
"additionalProperties": {}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"pixels": {
"type": "array",
"items": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"hex": {
"type": "string"
}
},
"required": [
"x",
"y",
"hex"
],
"additionalProperties": {}
}
},
"tokenId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
"required": [
"id",
"pixels",
"tokenId"
],
"additionalProperties": false
}
},
"required": [
"success",
"data"
],
"additionalProperties": {}
}
]
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/traitsList and search traits
Canonical trait IDs and slugs with rarity counts. extended=true includes additional traits. Grouped responses ignore pagination; otherwise limit=0 returns all matches.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| category | query | category parameter |
| gender | query | gender parameter |
| search | query | search parameter |
| limit | query | limit parameter |
| offset | query | offset parameter |
| groupByCategory | query | groupByCategory parameter |
| extended | query | extended parameter |
Request and response schemas
{
"operationId": "listTraits",
"summary": "List and search traits",
"description": "Canonical trait IDs and slugs with rarity counts. extended=true includes additional traits. Grouped responses ignore pagination; otherwise limit=0 returns all matches.",
"tags": [
"Rendering"
],
"security": [],
"parameters": [
{
"name": "category",
"in": "query",
"required": false,
"description": "category parameter",
"schema": {
"type": "string"
}
},
{
"name": "gender",
"in": "query",
"required": false,
"description": "gender parameter",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "search parameter",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "limit parameter",
"schema": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "offset parameter",
"schema": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "groupByCategory",
"in": "query",
"required": false,
"description": "groupByCategory parameter",
"schema": {
"default": "false",
"type": "string",
"enum": [
"true",
"false"
]
}
},
{
"name": "extended",
"in": "query",
"required": false,
"description": "extended parameter",
"schema": {
"default": "false",
"type": "string",
"enum": [
"true",
"false"
]
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"gender": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"punkCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"id",
"slug",
"name",
"category",
"punkCount"
],
"additionalProperties": {}
}
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"gender": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"punkCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"id",
"slug",
"name",
"category",
"punkCount"
],
"additionalProperties": {}
}
}
}
]
},
"total": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"categories": {
"type": "array",
"items": {
"type": "string"
}
},
"offset": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"limit": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"success",
"data",
"total",
"categories"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/traits/{slug}Compose a punk from arbitrary traits
A single trait slug/ID or hyphen-separated combination. Works for heads and naked bodies. Exact slugs are resolved before splitting. Combinations retain known traits and ignore unknown members; no resolved traits produces 404. JSON adds matching canonical punk IDs; pixels format returns only the composition.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| slug * | path | For example male2-mohawk-regularshades, or canonical trait IDs joined by hyphens. |
| format | query | format parameter |
| naked | query | yes, true or 1 renders a full body (32x32 minimum); otherwise a 24x24 head. |
| dingdong | query | yes/true/1 enables the body accessory; canonical punk rendering also accepts tripod, in-a-sock and tripod-in-a-sock. |
| size | query | Rendered image size. Defaults to the native grid size (24 or 32). |
| background | query | Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer. |
| ribbon | query | Ribbon color or preset. |
| ansiSize | query | ANSI output height. |
| includePunkIds | query | includePunkIds parameter |
Request and response schemas
{
"operationId": "renderTraits",
"summary": "Compose a punk from arbitrary traits",
"description": "A single trait slug/ID or hyphen-separated combination. Works for heads and naked bodies. Exact slugs are resolved before splitting. Combinations retain known traits and ignore unknown members; no resolved traits produces 404. JSON adds matching canonical punk IDs; pixels format returns only the composition.",
"tags": [
"Rendering"
],
"security": [],
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "For example male2-mohawk-regularshades, or canonical trait IDs joined by hyphens.",
"schema": {
"description": "For example male2-mohawk-regularshades, or canonical trait IDs joined by hyphens.",
"type": "string",
"minLength": 1
}
},
{
"name": "format",
"in": "query",
"required": false,
"description": "format parameter",
"schema": {
"default": "json",
"type": "string",
"enum": [
"json",
"pixels",
"svg",
"png",
"ascii",
"ansi"
]
}
},
{
"name": "naked",
"in": "query",
"required": false,
"description": "yes, true or 1 renders a full body (32x32 minimum); otherwise a 24x24 head.",
"schema": {
"description": "yes, true or 1 renders a full body (32x32 minimum); otherwise a 24x24 head.",
"type": "string"
}
},
{
"name": "dingdong",
"in": "query",
"required": false,
"description": "yes/true/1 enables the body accessory; canonical punk rendering also accepts tripod, in-a-sock and tripod-in-a-sock.",
"schema": {
"description": "yes/true/1 enables the body accessory; canonical punk rendering also accepts tripod, in-a-sock and tripod-in-a-sock.",
"type": "string"
}
},
{
"name": "size",
"in": "query",
"required": false,
"description": "Rendered image size. Defaults to the native grid size (24 or 32).",
"schema": {
"description": "Rendered image size. Defaults to the native grid size (24 or 32).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "background",
"in": "query",
"required": false,
"description": "Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer.",
"schema": {
"description": "Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer.",
"type": "string"
}
},
{
"name": "ribbon",
"in": "query",
"required": false,
"description": "Ribbon color or preset.",
"schema": {
"description": "Ribbon color or preset.",
"type": "string"
}
},
{
"name": "ansiSize",
"in": "query",
"required": false,
"description": "ANSI output height.",
"schema": {
"description": "ANSI output height.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "includePunkIds",
"in": "query",
"required": false,
"description": "includePunkIds parameter",
"schema": {
"default": "true",
"type": "string",
"enum": [
"true",
"false"
]
}
}
],
"responses": {
"200": {
"description": "Format selected by the format query parameter. PNG and SVG are scaled; JSON pixels use native coordinates.",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/svg+xml": {
"schema": {
"type": "string"
}
},
"text/plain": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"pixels": {
"type": "array",
"items": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"hex": {
"type": "string"
}
},
"required": [
"x",
"y",
"hex"
],
"additionalProperties": {}
}
},
"slug": {
"type": "string"
},
"traits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"gender": {
"type": "string"
}
},
"required": [
"id",
"slug",
"name",
"category"
],
"additionalProperties": {}
}
},
"pixelCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"colors": {
"type": "array",
"items": {
"type": "string"
}
},
"urls": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"punkCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"punkIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"gender": {
"type": "string"
},
"file": {
"type": "string"
},
"aka": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"pixels",
"slug",
"traits",
"pixelCount",
"colors",
"urls",
"punkCount"
],
"additionalProperties": {}
}
},
"required": [
"success",
"data"
],
"additionalProperties": {}
},
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"pixels": {
"type": "array",
"items": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"hex": {
"type": "string"
}
},
"required": [
"x",
"y",
"hex"
],
"additionalProperties": {}
}
},
"slug": {
"type": "string"
},
"traits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"gender": {
"type": "string"
}
},
"required": [
"id",
"slug",
"name",
"category"
],
"additionalProperties": {}
}
}
},
"required": [
"id",
"pixels",
"slug",
"traits"
],
"additionalProperties": false
}
},
"required": [
"success",
"data"
],
"additionalProperties": {}
}
]
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/punks/gridRender a grid of heads
Up to 100 valid canonical IDs. Invalid IDs are filtered. PNG is not supported by this grid route.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| format | query | format parameter |
| cols | query | 0 selects up to five columns automatically. |
| size | query | SVG cell size in pixels. |
| background | query | Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer. |
| labels | query | labels parameter |
| ids * | query | Comma-separated canonical IDs. |
| ansiSize | query | ANSI output height. |
Request and response schemas
{
"operationId": "renderPunkGrid",
"summary": "Render a grid of heads",
"description": "Up to 100 valid canonical IDs. Invalid IDs are filtered. PNG is not supported by this grid route.",
"tags": [
"Rendering"
],
"security": [],
"parameters": [
{
"name": "format",
"in": "query",
"required": false,
"description": "format parameter",
"schema": {
"default": "ansi",
"type": "string",
"enum": [
"ansi",
"ascii",
"svg",
"json"
]
}
},
{
"name": "cols",
"in": "query",
"required": false,
"description": "0 selects up to five columns automatically.",
"schema": {
"description": "0 selects up to five columns automatically.",
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "size",
"in": "query",
"required": false,
"description": "SVG cell size in pixels.",
"schema": {
"description": "SVG cell size in pixels.",
"default": 24,
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "background",
"in": "query",
"required": false,
"description": "Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer.",
"schema": {
"description": "Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer.",
"type": "string"
}
},
{
"name": "labels",
"in": "query",
"required": false,
"description": "labels parameter",
"schema": {
"default": "true",
"type": "string",
"enum": [
"true",
"false"
]
}
},
{
"name": "ids",
"in": "query",
"required": true,
"description": "Comma-separated canonical IDs.",
"schema": {
"description": "Comma-separated canonical IDs.",
"type": "string",
"minLength": 1
}
},
{
"name": "ansiSize",
"in": "query",
"required": false,
"description": "ANSI output height.",
"schema": {
"description": "ANSI output height.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "SVG, ASCII or ANSI grid.",
"content": {
"image/svg+xml": {
"schema": {
"type": "string"
}
},
"text/plain": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"cols": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"rows": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"urls": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"punks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tokenId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"id": {
"type": "string"
},
"traits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"gender": {
"type": "string"
}
},
"required": [
"id",
"slug",
"name",
"category"
],
"additionalProperties": {}
}
},
"traitCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"tokenId",
"id"
],
"additionalProperties": false
}
}
},
"required": [
"count",
"cols",
"rows",
"urls",
"punks"
],
"additionalProperties": false
}
},
"required": [
"success",
"data"
],
"additionalProperties": {}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/traits/gridRender a trait contact sheet
Provide slugs or category; explicit slugs take precedence. Up to 50 traits. Optional body supplies a base type. Unknown slugs return 400.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| format | query | format parameter |
| cols | query | 0 selects up to five columns automatically. |
| size | query | SVG cell size in pixels. |
| background | query | Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer. |
| labels | query | labels parameter |
| slugs | query | Comma-separated trait slugs or IDs; required unless category is supplied. |
| category | query | category parameter |
| body | query | body parameter |
Request and response schemas
{
"operationId": "renderTraitGrid",
"summary": "Render a trait contact sheet",
"description": "Provide slugs or category; explicit slugs take precedence. Up to 50 traits. Optional body supplies a base type. Unknown slugs return 400.",
"tags": [
"Rendering"
],
"security": [],
"parameters": [
{
"name": "format",
"in": "query",
"required": false,
"description": "format parameter",
"schema": {
"default": "ansi",
"type": "string",
"enum": [
"ansi",
"ascii",
"svg",
"json"
]
}
},
{
"name": "cols",
"in": "query",
"required": false,
"description": "0 selects up to five columns automatically.",
"schema": {
"description": "0 selects up to five columns automatically.",
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "size",
"in": "query",
"required": false,
"description": "SVG cell size in pixels.",
"schema": {
"description": "SVG cell size in pixels.",
"default": 24,
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "background",
"in": "query",
"required": false,
"description": "Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer.",
"schema": {
"description": "Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer.",
"type": "string"
}
},
{
"name": "labels",
"in": "query",
"required": false,
"description": "labels parameter",
"schema": {
"default": "true",
"type": "string",
"enum": [
"true",
"false"
]
}
},
{
"name": "slugs",
"in": "query",
"required": false,
"description": "Comma-separated trait slugs or IDs; required unless category is supplied.",
"schema": {
"description": "Comma-separated trait slugs or IDs; required unless category is supplied.",
"type": "string"
}
},
{
"name": "category",
"in": "query",
"required": false,
"description": "category parameter",
"schema": {
"type": "string"
}
},
{
"name": "body",
"in": "query",
"required": false,
"description": "body parameter",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "SVG, ASCII or ANSI grid.",
"content": {
"image/svg+xml": {
"schema": {
"type": "string"
}
},
"text/plain": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"cols": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"rows": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"urls": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"traits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"id": {
"type": "string"
}
},
"required": [
"slug",
"name",
"id"
],
"additionalProperties": false
}
}
},
"required": [
"count",
"cols",
"rows",
"urls",
"traits"
],
"additionalProperties": false
}
},
"required": [
"success",
"data"
],
"additionalProperties": {}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/punks/matchRank canonical punks by trait overlap
Matches are ranked by the number of requested traits present, then canonical ID. Unknown traits are reported in query.unresolved.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| traits * | query | Comma-separated trait slugs, names or IDs. |
| limit | query | limit parameter |
Request and response schemas
{
"operationId": "matchPunkTraits",
"summary": "Rank canonical punks by trait overlap",
"description": "Matches are ranked by the number of requested traits present, then canonical ID. Unknown traits are reported in query.unresolved.",
"tags": [
"Rendering"
],
"security": [],
"parameters": [
{
"name": "traits",
"in": "query",
"required": true,
"description": "Comma-separated trait slugs, names or IDs.",
"schema": {
"description": "Comma-separated trait slugs, names or IDs.",
"type": "string",
"minLength": 1
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "limit parameter",
"schema": {
"default": 20,
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"query": {
"type": "object",
"properties": {
"traits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"slug",
"name",
"category"
],
"additionalProperties": {}
}
},
"unresolved": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"traits"
],
"additionalProperties": false
},
"matches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tokenId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"matchCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"totalRequested": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"matchRatio": {
"type": "number"
},
"matchedTraits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"additionalProperties": {}
}
},
"missedTraits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"additionalProperties": {}
}
},
"traits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"slug",
"name",
"category"
],
"additionalProperties": {}
}
}
},
"required": [
"tokenId",
"matchCount",
"totalRequested",
"matchRatio",
"matchedTraits",
"missedTraits",
"traits"
],
"additionalProperties": false
}
},
"count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"urls": {
"type": "object",
"properties": {
"grid": {
"type": "string"
}
},
"additionalProperties": false
}
},
"required": [
"query",
"matches",
"count",
"urls"
],
"additionalProperties": false
}
},
"required": [
"success",
"data"
],
"additionalProperties": {}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/punks/randomRedirect to random canonical punks
307 redirects to a single renderer or a grid. count is clamped to 1..100. Remaining query parameters are forwarded; multiple punks default to ANSI.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| format | query | format parameter |
| naked | query | yes, true or 1 renders a full body (32x32 minimum); otherwise a 24x24 head. |
| dingdong | query | yes/true/1 enables the body accessory; canonical punk rendering also accepts tripod, in-a-sock and tripod-in-a-sock. |
| size | query | Rendered image size. Defaults to the native grid size (24 or 32). |
| background | query | Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer. |
| ribbon | query | Ribbon color or preset. |
| ansiSize | query | ANSI output height. |
| count | query | count parameter |
Request and response schemas
{
"operationId": "randomPunks",
"summary": "Redirect to random canonical punks",
"description": "307 redirects to a single renderer or a grid. count is clamped to 1..100. Remaining query parameters are forwarded; multiple punks default to ANSI.",
"tags": [
"Rendering"
],
"security": [],
"parameters": [
{
"name": "format",
"in": "query",
"required": false,
"description": "format parameter",
"schema": {
"default": "json",
"type": "string",
"enum": [
"json",
"pixels",
"svg",
"png",
"ascii",
"ansi"
]
}
},
{
"name": "naked",
"in": "query",
"required": false,
"description": "yes, true or 1 renders a full body (32x32 minimum); otherwise a 24x24 head.",
"schema": {
"description": "yes, true or 1 renders a full body (32x32 minimum); otherwise a 24x24 head.",
"type": "string"
}
},
{
"name": "dingdong",
"in": "query",
"required": false,
"description": "yes/true/1 enables the body accessory; canonical punk rendering also accepts tripod, in-a-sock and tripod-in-a-sock.",
"schema": {
"description": "yes/true/1 enables the body accessory; canonical punk rendering also accepts tripod, in-a-sock and tripod-in-a-sock.",
"type": "string"
}
},
{
"name": "size",
"in": "query",
"required": false,
"description": "Rendered image size. Defaults to the native grid size (24 or 32).",
"schema": {
"description": "Rendered image size. Defaults to the native grid size (24 or 32).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "background",
"in": "query",
"required": false,
"description": "Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer.",
"schema": {
"description": "Transparent when omitted; a hex color, a named punk background, gradient or image accepted by the renderer.",
"type": "string"
}
},
{
"name": "ribbon",
"in": "query",
"required": false,
"description": "Ribbon color or preset.",
"schema": {
"description": "Ribbon color or preset.",
"type": "string"
}
},
{
"name": "ansiSize",
"in": "query",
"required": false,
"description": "ANSI output height.",
"schema": {
"description": "ANSI output height.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "count",
"in": "query",
"required": false,
"description": "count parameter",
"schema": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 100
}
}
],
"responses": {
"307": {
"description": "Follow Location to retrieve the selected renderer response.",
"headers": {
"Location": {
"description": "Absolute renderer URL.",
"schema": {
"type": "string",
"format": "uri"
}
}
}
}
},
"x-runtime-validation": "legacy"
}Market
POST/api/derivatives/{derivative}/rpcRead or simulate against the explicitly bound mint edition
Single read-only JSON-RPC call. The server selects the configured RPC by the catalogue edition chain. No writes, batch, state overrides or arbitrary contract calls. eth_call and eth_getCode target only the edition address; simulations are capped at 15 million gas. Requests are limited to 24k characters, responses to 4M, with a 10-second upstream timeout and no automatic retry. Upstream errors preserve revert bytes but redact provider messages. Browser requests must be same-origin. No-store. An absent edition returns 409.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| derivative * | path | derivative parameter |
Request and response schemas
{
"operationId": "readDerivativeMintRpc",
"summary": "Read or simulate against the explicitly bound mint edition",
"description": "Single read-only JSON-RPC call. The server selects the configured RPC by the catalogue edition chain. No writes, batch, state overrides or arbitrary contract calls. eth_call and eth_getCode target only the edition address; simulations are capped at 15 million gas. Requests are limited to 24k characters, responses to 4M, with a 10-second upstream timeout and no automatic retry. Upstream errors preserve revert bytes but redact provider messages. Browser requests must be same-origin. No-store. An absent edition returns 409.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "derivative",
"in": "path",
"required": true,
"description": "derivative parameter",
"schema": {
"type": "string",
"enum": [
"meepunks",
"nakedpunks"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"jsonrpc": {
"type": "string",
"const": "2.0"
},
"id": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"method": {
"type": "string",
"enum": [
"eth_chainId",
"eth_blockNumber",
"eth_getBlockByNumber",
"eth_getBlockByHash",
"eth_getTransactionReceipt",
"eth_getTransactionByHash",
"eth_getCode",
"eth_call"
]
},
"params": {
"default": [],
"maxItems": 2,
"type": "array",
"items": {}
}
},
"required": [
"jsonrpc",
"id",
"method"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"jsonrpc": {
"type": "string",
"const": "2.0"
},
"id": {
"type": "number"
},
"result": {}
},
"required": [
"jsonrpc",
"id",
"result"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"jsonrpc": {
"type": "string",
"const": "2.0"
},
"id": {
"type": "number"
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "number"
},
"message": {
"type": "string"
},
"data": {
"type": "string",
"pattern": "^0x(?:[0-9a-fA-F]{2})*$"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
}
},
"required": [
"jsonrpc",
"id",
"error"
],
"additionalProperties": false
}
]
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Access denied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Request failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Service not configured",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/derivatives/{derivative}/projectionRead confirmed derivative ownership, tickets and activity
Edition-specific durable event projection. Each request advances at most four 1000-block chunks; indexing marks incomplete results. A saved block/hash checkpoint is checked and replayed on a reorg. Only Transfer events create ownership; assigned tickets remain separate. Activity is bounded to the most recent 1000 events. No deployed edition returns not-deployed without an RPC or database request. No-store HTTP response; the service coalesces refreshes and caches successful reads for 15 seconds. Provider/storage errors return 503, never an empty ownership list.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| derivative * | path | derivative parameter |
Request and response schemas
{
"operationId": "readDerivativeProjection",
"summary": "Read confirmed derivative ownership, tickets and activity",
"description": "Edition-specific durable event projection. Each request advances at most four 1000-block chunks; indexing marks incomplete results. A saved block/hash checkpoint is checked and replayed on a reorg. Only Transfer events create ownership; assigned tickets remain separate. Activity is bounded to the most recent 1000 events. No deployed edition returns not-deployed without an RPC or database request. No-store HTTP response; the service coalesces refreshes and caches successful reads for 15 seconds. Provider/storage errors return 503, never an empty ownership list.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "derivative",
"in": "path",
"required": true,
"description": "derivative parameter",
"schema": {
"type": "string",
"enum": [
"meepunks",
"nakedpunks"
]
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "not-deployed"
}
},
"required": [
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ready",
"indexing"
]
},
"edition": {},
"projection": {
"type": "object",
"properties": {
"manifest": {
"type": "string"
},
"checkpoint": {
"anyOf": [
{
"type": "object",
"properties": {
"number": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"hash": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
}
},
"required": [
"number",
"hash"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"owners": {
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,3})$"
},
"additionalProperties": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
}
},
"tickets": {
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,3})$"
},
"additionalProperties": {
"anyOf": [
{
"type": "object",
"properties": {
"payer": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"beneficiary": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"price": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"status": {
"type": "string",
"const": "pending"
}
},
"required": [
"payer",
"beneficiary",
"price",
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"payer": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"beneficiary": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"price": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"status": {
"type": "string",
"const": "assigned"
},
"punkId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
"required": [
"payer",
"beneficiary",
"price",
"status",
"punkId"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"payer": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"beneficiary": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"price": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"status": {
"type": "string",
"const": "delivered"
},
"punkId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"recipient": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
}
},
"required": [
"payer",
"beneficiary",
"price",
"status",
"punkId",
"recipient"
],
"additionalProperties": false
}
]
}
},
"recentActivity": {
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"blockNumber": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"blockHash": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"transactionHash": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
},
"logIndex": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"event": {
"type": "string",
"enum": [
"Transfer",
"HolderClaimed",
"ChosenMinted",
"RandomPurchased",
"RandomAssigned",
"RandomDelivered"
]
},
"args": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"blockNumber",
"blockHash",
"transactionHash",
"logIndex",
"event",
"args"
],
"additionalProperties": false
}
},
"activityTruncated": {
"type": "boolean"
}
},
"required": [
"manifest",
"checkpoint",
"owners",
"tickets",
"recentActivity",
"activityTruncated"
],
"additionalProperties": false
},
"targetBlock": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"confirmations": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"replayed": {
"type": "boolean"
},
"observedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"status",
"edition",
"projection",
"targetBlock",
"confirmations",
"replayed",
"observedAt"
],
"additionalProperties": false
}
]
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Service not configured",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/derivatives/{derivative}/{punkId}/stateVerify current token state directly against the edition contract
Checks chain, protocol, runtime code hash and art identity through the SDK. Reads a single token at one latest block and rechecks the block hash. Available, assigned beneficiary and minted owner are distinct states. This recent block is not a confirmation receipt. Missing edition returns not-deployed; RPC or identity failure returns 503. No-store.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| derivative * | path | derivative parameter |
| punkId * | path | punkId parameter |
Request and response schemas
{
"operationId": "readDerivativeTokenState",
"summary": "Verify current token state directly against the edition contract",
"description": "Checks chain, protocol, runtime code hash and art identity through the SDK. Reads a single token at one latest block and rechecks the block hash. Available, assigned beneficiary and minted owner are distinct states. This recent block is not a confirmation receipt. Missing edition returns not-deployed; RPC or identity failure returns 503. No-store.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "derivative",
"in": "path",
"required": true,
"description": "derivative parameter",
"schema": {
"type": "string",
"enum": [
"meepunks",
"nakedpunks"
]
}
},
{
"name": "punkId",
"in": "path",
"required": true,
"description": "punkId parameter",
"schema": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,3})$"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "not-deployed"
}
},
"required": [
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "ready"
},
"edition": {},
"punkId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"token": {
"anyOf": [
{
"type": "object",
"properties": {
"state": {
"type": "string",
"const": "available"
}
},
"required": [
"state"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"state": {
"type": "string",
"const": "assigned"
},
"beneficiary": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
}
},
"required": [
"state",
"beneficiary"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"state": {
"type": "string",
"const": "minted"
},
"owner": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
}
},
"required": [
"state",
"owner"
],
"additionalProperties": false
}
]
},
"block": {
"type": "object",
"properties": {
"number": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"hash": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{64}$"
}
},
"required": [
"number",
"hash"
],
"additionalProperties": false
},
"observedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"status",
"edition",
"punkId",
"token",
"block",
"observedAt"
],
"additionalProperties": false
}
]
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Service not configured",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/derivatives/{derivative}/marketRead one page from the explicitly bound derivative market
No provider or absent edition returns none. Unindexed collections return pending-indexing. OpenSea collection/chain/contract are checked before serving orders. A token best-order query checks NFT indexing before interpreting a missing order as empty. Integer-string amounts include the payment token, chain and decimals; currencies are never ranked together. Up to 200 listings or 50 events per page, 8-second HTTP timeout per upstream call, 30-second successful-result cache. Errors return 503. No-store HTTP response.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| derivative * | path | derivative parameter |
| kind | query | kind parameter |
| tokenId | query | tokenId parameter |
| account | query | account parameter |
| next | query | next parameter |
| types | query | types parameter |
Request and response schemas
{
"operationId": "readDerivativeMarket",
"summary": "Read one page from the explicitly bound derivative market",
"description": "No provider or absent edition returns none. Unindexed collections return pending-indexing. OpenSea collection/chain/contract are checked before serving orders. A token best-order query checks NFT indexing before interpreting a missing order as empty. Integer-string amounts include the payment token, chain and decimals; currencies are never ranked together. Up to 200 listings or 50 events per page, 8-second HTTP timeout per upstream call, 30-second successful-result cache. Errors return 503. No-store HTTP response.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "derivative",
"in": "path",
"required": true,
"description": "derivative parameter",
"schema": {
"type": "string",
"enum": [
"meepunks",
"nakedpunks"
]
}
},
{
"name": "kind",
"in": "query",
"required": false,
"description": "kind parameter",
"schema": {
"default": "listings",
"type": "string",
"enum": [
"listings",
"token",
"events",
"account-events"
]
}
},
{
"name": "tokenId",
"in": "query",
"required": false,
"description": "tokenId parameter",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
{
"name": "account",
"in": "query",
"required": false,
"description": "account parameter",
"schema": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
}
},
{
"name": "next",
"in": "query",
"required": false,
"description": "next parameter",
"schema": {
"type": "string",
"maxLength": 2048
}
},
{
"name": "types",
"in": "query",
"required": false,
"description": "types parameter",
"schema": {
"maxItems": 7,
"type": "array",
"items": {
"type": "string",
"enum": [
"sale",
"transfer",
"mint",
"listing",
"offer",
"trait_offer",
"collection_offer"
]
}
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "none"
}
},
"required": [
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "pending-indexing"
}
},
"required": [
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ready",
"ready-empty"
]
},
"sourceKey": {
"type": "string"
},
"orders": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tokenId": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"kind": {
"type": "string",
"enum": [
"listing",
"offer"
]
},
"payment": {
"type": "object",
"properties": {
"raw": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"token": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"symbol": {
"type": "string",
"minLength": 1,
"maxLength": 32
},
"decimals": {
"type": "integer",
"minimum": 0,
"maximum": 255
},
"chainId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"raw",
"token",
"symbol",
"decimals",
"chainId"
],
"additionalProperties": false
},
"maker": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"orderHash": {
"type": "string"
},
"expiresAt": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"url": {
"type": "string",
"format": "uri"
}
},
"required": [
"tokenId",
"kind",
"payment",
"maker",
"orderHash",
"url"
],
"additionalProperties": false
}
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"tokenId": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"timestamp": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"payment": {
"type": "object",
"properties": {
"raw": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
},
"token": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"symbol": {
"type": "string",
"minLength": 1,
"maxLength": 32
},
"decimals": {
"type": "integer",
"minimum": 0,
"maximum": 255
},
"chainId": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"raw",
"token",
"symbol",
"decimals",
"chainId"
],
"additionalProperties": false
},
"from": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"to": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"transactionHash": {
"type": "string"
}
},
"required": [
"id",
"type",
"timestamp"
],
"additionalProperties": false
}
},
"next": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"observedAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"unsupportedOrders": {
"type": "array",
"items": {
"type": "string",
"enum": [
"listing",
"offer"
]
}
}
},
"required": [
"status",
"sourceKey",
"orders",
"events",
"next",
"observedAt"
],
"additionalProperties": false
}
]
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Service not configured",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/listings/{collection}Fetch collection listings
One bounded page for explicitly mapped collections; unknown addresses/slugs return404. Native CryptoPunks reads at most500 IDs per page, OpenSea at most200 listings. Follow next until null; a page is not a complete inventory. Missing provider configuration and failed batches return503. prices contains only native ETH display values; listing.payment retains exact raw amounts, token address, chain and decimals. No cross-currency ranking. refresh is a legacy hint; successful provider pages remain cached for30seconds.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| collection * | path | Collection slug, alias or contract address. |
| refresh | query | refresh parameter |
| next | query | next parameter |
| chainId | query | chainId parameter |
Request and response schemas
{
"operationId": "listMarketListings",
"summary": "Fetch collection listings",
"description": "One bounded page for explicitly mapped collections; unknown addresses/slugs return404. Native CryptoPunks reads at most500 IDs per page, OpenSea at most200 listings. Follow next until null; a page is not a complete inventory. Missing provider configuration and failed batches return503. prices contains only native ETH display values; listing.payment retains exact raw amounts, token address, chain and decimals. No cross-currency ranking. refresh is a legacy hint; successful provider pages remain cached for30seconds.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "collection",
"in": "path",
"required": true,
"description": "Collection slug, alias or contract address.",
"schema": {
"description": "Collection slug, alias or contract address.",
"type": "string",
"minLength": 1
}
},
{
"name": "refresh",
"in": "query",
"required": false,
"description": "refresh parameter",
"schema": {
"default": "false",
"type": "string",
"enum": [
"true",
"false"
]
}
},
{
"name": "next",
"in": "query",
"required": false,
"description": "next parameter",
"schema": {
"type": "string",
"maxLength": 2048
}
},
{
"name": "chainId",
"in": "query",
"required": false,
"description": "chainId parameter",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"collection": {
"type": "string"
},
"count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"totalListings": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"updatedAt": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"none",
"pending-indexing",
"ready",
"ready-empty"
]
},
"sourceKey": {
"type": "string"
},
"next": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"prices": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"listings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tokenId": {
"type": "string"
},
"price": {
"description": "Display value in currency units; exact canonical value is payment.raw when provided.",
"type": "number"
},
"payment": {
"type": "object",
"properties": {
"raw": {
"type": "string"
},
"token": {
"type": "string"
},
"symbol": {
"type": "string"
},
"decimals": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"raw",
"token",
"symbol",
"decimals",
"chainId"
],
"additionalProperties": false
},
"currency": {
"type": "string"
},
"maker": {
"type": "string"
},
"expirationTime": {
"type": "number"
}
},
"required": [
"tokenId",
"price",
"currency",
"maker"
],
"additionalProperties": false
}
}
},
"required": [
"collection",
"count",
"totalListings",
"status",
"next",
"prices",
"listings"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Service not configured",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/listings/cryptopunks/streamStream native listing progress
SSE: each data line is a JSON ListingEvent followed by two newlines. A cached event ends the stream immediately; otherwise progress events precede complete. Missing provider configuration is an error event within HTTP 200. Individual failed RPC batches are skipped, so a complete result can be partial.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "streamPunkListings",
"summary": "Stream native listing progress",
"description": "SSE: each data line is a JSON ListingEvent followed by two newlines. A cached event ends the stream immediately; otherwise progress events precede complete. Missing provider configuration is an error event within HTTP 200. Individual failed RPC batches are skipped, so a complete result can be partial.",
"tags": [
"Market"
],
"security": [],
"responses": {
"200": {
"description": "Server-sent events; the schema describes one decoded data payload, not the wire framing.",
"content": {
"text/event-stream": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"cached",
"complete"
]
},
"listings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tokenId": {
"type": "string"
},
"price": {
"description": "Display value in currency units; exact canonical value is payment.raw when provided.",
"type": "number"
},
"payment": {
"type": "object",
"properties": {
"raw": {
"type": "string"
},
"token": {
"type": "string"
},
"symbol": {
"type": "string"
},
"decimals": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"raw",
"token",
"symbol",
"decimals",
"chainId"
],
"additionalProperties": false
},
"currency": {
"type": "string"
},
"maker": {
"type": "string"
},
"expirationTime": {
"type": "number"
}
},
"required": [
"tokenId",
"price",
"currency",
"maker"
],
"additionalProperties": false
}
},
"count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"type",
"listings",
"count"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "progress"
},
"percent": {
"type": "number"
},
"batchesCompleted": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"totalBatches": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"listingsFound": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"type",
"percent",
"batchesCompleted",
"totalBatches",
"listingsFound"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/punks/ownersRead canonical punk ownership
Five-minute cache of contract ownership. With address, returns that wallet's IDs; otherwise returns the token-to-owner map. Failed RPC batches are skipped.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| address | query | address parameter |
| refresh | query | refresh parameter |
Request and response schemas
{
"operationId": "listPunkOwners",
"summary": "Read canonical punk ownership",
"description": "Five-minute cache of contract ownership. With address, returns that wallet's IDs; otherwise returns the token-to-owner map. Failed RPC batches are skipped.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "address",
"in": "query",
"required": false,
"description": "address parameter",
"schema": {
"type": "string"
}
},
{
"name": "refresh",
"in": "query",
"required": false,
"description": "refresh parameter",
"schema": {
"default": "false",
"type": "string",
"enum": [
"true",
"false"
]
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"totalPunks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"owners": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"updatedAt": {
"type": "string"
}
},
"required": [
"totalPunks",
"owners",
"updatedAt"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"address": {
"type": "string"
},
"count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"punkIds": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
"updatedAt": {
"type": "string"
}
},
"required": [
"address",
"count",
"punkIds",
"updatedAt"
],
"additionalProperties": false
}
]
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/ownersRank owners by token count
Canonical CryptoPunks retains the historical array response. Derivative slugs, or a verified edition address with explicit chainId, return confirmed ownership with checkpoint and indexing state. Assigned tickets are not owners. Missing editions return not-deployed; derivative data failures return 503.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| collection * | query | Derivative slug, verified derivative edition address, or canonical CryptoPunks address. |
| chainId | query | chainId parameter |
Request and response schemas
{
"operationId": "rankPunkOwners",
"summary": "Rank owners by token count",
"description": "Canonical CryptoPunks retains the historical array response. Derivative slugs, or a verified edition address with explicit chainId, return confirmed ownership with checkpoint and indexing state. Assigned tickets are not owners. Missing editions return not-deployed; derivative data failures return 503.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "collection",
"in": "query",
"required": true,
"description": "Derivative slug, verified derivative edition address, or canonical CryptoPunks address.",
"schema": {
"description": "Derivative slug, verified derivative edition address, or canonical CryptoPunks address.",
"type": "string"
}
},
{
"name": "chainId",
"in": "query",
"required": false,
"description": "chainId parameter",
"schema": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"type": "string"
},
"tokenCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"address",
"tokenCount"
],
"additionalProperties": false
}
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "not-deployed"
}
},
"required": [
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ready",
"indexing"
]
},
"owners": {
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"type": "string"
},
"tokenCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"address",
"tokenCount"
],
"additionalProperties": false
}
},
"checkpoint": {
"anyOf": [
{
"type": "object",
"properties": {
"number": {
"type": "string"
},
"hash": {
"type": "string"
}
},
"required": [
"number",
"hash"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"targetBlock": {
"type": "string"
},
"confirmations": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"observedAt": {
"type": "string"
}
},
"required": [
"status",
"owners",
"checkpoint",
"targetBlock",
"confirmations",
"observedAt"
],
"additionalProperties": false
}
]
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Service not configured",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}POST/api/ensResolve verified ENS names
Normalizes, deduplicates and filters addresses. At most 10,000 valid addresses per request. No valid address returns an empty results array; a missing/non-array addresses field returns 400. Reverse names are normalized and accepted only when their forward resolution matches the requested address. Unresolved or mismatched names have ens=null. A forward verification provider failure returns 503 so clients can retry.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "resolveEns",
"summary": "Resolve verified ENS names",
"description": "Normalizes, deduplicates and filters addresses. At most 10,000 valid addresses per request. No valid address returns an empty results array; a missing/non-array addresses field returns 400. Reverse names are normalized and accepted only when their forward resolution matches the requested address. Unresolved or mismatched names have ens=null. A forward verification provider failure returns 503 so clients can retry.",
"tags": [
"Market"
],
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"addresses": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"addresses"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"type": "string"
},
"ens": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"address",
"ens"
],
"additionalProperties": false
}
}
},
"required": [
"results"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Request or image too large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Service not configured",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/ethusdFetch daily ETH/USD closes
Coinbase Exchange daily candles, deduplicated and sorted. start is Unix seconds encoded as a string; close is a decimal string. granularity is currently ignored: the implementation always requests daily candles. Upstream errors retain their status and text body.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| start * | query | ISO date/time. |
| end * | query | ISO date/time. |
| granularity | query | Legacy parameter; currently ignored. |
Request and response schemas
{
"operationId": "getEthUsdCandles",
"summary": "Fetch daily ETH/USD closes",
"description": "Coinbase Exchange daily candles, deduplicated and sorted. start is Unix seconds encoded as a string; close is a decimal string. granularity is currently ignored: the implementation always requests daily candles. Upstream errors retain their status and text body.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "start",
"in": "query",
"required": true,
"description": "ISO date/time.",
"schema": {
"description": "ISO date/time.",
"type": "string"
}
},
{
"name": "end",
"in": "query",
"required": true,
"description": "ISO date/time.",
"schema": {
"description": "ISO date/time.",
"type": "string"
}
},
{
"name": "granularity",
"in": "query",
"required": false,
"description": "Legacy parameter; currently ignored.",
"schema": {
"description": "Legacy parameter; currently ignored.",
"default": "ONE_DAY",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"candles": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "string"
},
"close": {
"type": "string"
}
},
"required": [
"start",
"close"
],
"additionalProperties": false
}
}
},
"required": [
"candles"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"default": {
"description": "Upstream Coinbase error, status preserved.",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/alchemy/nftProxy supported Alchemy NFT queries
Provider-owned responses from the configured Ethereum mainnet Alchemy SDK. contract is required for contract/metadata/owner/floor actions; tokenId is also required for getNftMetadata/getOwnersForNft; owner is required for getNftsForOwner. getNftSales filters are optional. See https://www.alchemy.com/docs/reference/nft-api-quickstart for upstream response contracts.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| action * | query | action parameter |
| contract | query | contract parameter |
| tokenId | query | tokenId parameter |
| owner | query | owner parameter |
| contractAddresses | query | Repeat the query key for multiple contracts. |
| buyer | query | buyer parameter |
| seller | query | seller parameter |
| pageKey | query | pageKey parameter |
| pageSize | query | pageSize parameter |
| limit | query | limit parameter |
Request and response schemas
{
"operationId": "queryAlchemyNfts",
"summary": "Proxy supported Alchemy NFT queries",
"description": "Provider-owned responses from the configured Ethereum mainnet Alchemy SDK. contract is required for contract/metadata/owner/floor actions; tokenId is also required for getNftMetadata/getOwnersForNft; owner is required for getNftsForOwner. getNftSales filters are optional. See https://www.alchemy.com/docs/reference/nft-api-quickstart for upstream response contracts.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "action",
"in": "query",
"required": true,
"description": "action parameter",
"schema": {
"type": "string",
"enum": [
"getOwnersForContract",
"getNftMetadata",
"getOwnersForNft",
"getNftsForOwner",
"getNftSales",
"getContractMetadata",
"getNftsForContract",
"getFloorPrice"
]
}
},
{
"name": "contract",
"in": "query",
"required": false,
"description": "contract parameter",
"schema": {
"type": "string"
}
},
{
"name": "tokenId",
"in": "query",
"required": false,
"description": "tokenId parameter",
"schema": {
"type": "string"
}
},
{
"name": "owner",
"in": "query",
"required": false,
"description": "owner parameter",
"schema": {
"type": "string"
}
},
{
"name": "contractAddresses",
"in": "query",
"required": false,
"description": "Repeat the query key for multiple contracts.",
"schema": {
"description": "Repeat the query key for multiple contracts.",
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true
},
{
"name": "buyer",
"in": "query",
"required": false,
"description": "buyer parameter",
"schema": {
"type": "string"
}
},
{
"name": "seller",
"in": "query",
"required": false,
"description": "seller parameter",
"schema": {
"type": "string"
}
},
{
"name": "pageKey",
"in": "query",
"required": false,
"description": "pageKey parameter",
"schema": {
"type": "string"
}
},
{
"name": "pageSize",
"in": "query",
"required": false,
"description": "pageSize parameter",
"schema": {
"default": 100,
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "limit parameter",
"schema": {
"default": 100,
"type": "integer",
"minimum": 1,
"maximum": 1000
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"description": "Provider-owned JSON payload, forwarded without reshaping. Consult the upstream API for its action-specific schema.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/opensea/{slug}Read through the OpenSea proxy
Legacy catch-all proxy to https://api.opensea.io. slug includes the full upstream path (for example api/v2/collections/cryptopunks). All query keys, the POST body, upstream status and content type are forwarded. The server supplies its OpenSea credential. Request/response fields belong to the upstream API: https://docs.opensea.io/reference/api-overview. OpenAPI path parameters cannot express catch-all routing; preserve literal slashes in slug.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| slug * | path | slug parameter |
Request and response schemas
{
"operationId": "queryOpenSea",
"summary": "Read through the OpenSea proxy",
"description": "Legacy catch-all proxy to https://api.opensea.io. slug includes the full upstream path (for example api/v2/collections/cryptopunks). All query keys, the POST body, upstream status and content type are forwarded. The server supplies its OpenSea credential. Request/response fields belong to the upstream API: https://docs.opensea.io/reference/api-overview. OpenAPI path parameters cannot express catch-all routing; preserve literal slashes in slug.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "slug parameter",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"description": "Provider-owned JSON payload, forwarded without reshaping. Consult the upstream API for its action-specific schema.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"default": {
"description": "Upstream response, HTTP status and content type preserved.",
"content": {
"application/json": {
"schema": {
"description": "Provider-owned JSON payload, forwarded without reshaping. Consult the upstream API for its action-specific schema.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
},
"x-runtime-validation": "legacy"
}POST/api/opensea/{slug}Post through the OpenSea proxy
Legacy catch-all proxy to https://api.opensea.io. slug includes the full upstream path (for example api/v2/collections/cryptopunks). All query keys, the POST body, upstream status and content type are forwarded. The server supplies its OpenSea credential. Request/response fields belong to the upstream API: https://docs.opensea.io/reference/api-overview. OpenAPI path parameters cannot express catch-all routing; preserve literal slashes in slug.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| slug * | path | slug parameter |
Request and response schemas
{
"operationId": "postOpenSea",
"summary": "Post through the OpenSea proxy",
"description": "Legacy catch-all proxy to https://api.opensea.io. slug includes the full upstream path (for example api/v2/collections/cryptopunks). All query keys, the POST body, upstream status and content type are forwarded. The server supplies its OpenSea credential. Request/response fields belong to the upstream API: https://docs.opensea.io/reference/api-overview. OpenAPI path parameters cannot express catch-all routing; preserve literal slashes in slug.",
"tags": [
"Market"
],
"security": [],
"parameters": [
{
"name": "slug",
"in": "path",
"required": true,
"description": "slug parameter",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Provider-owned JSON payload, forwarded without reshaping. Consult the upstream API for its action-specific schema.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"description": "Provider-owned JSON payload, forwarded without reshaping. Consult the upstream API for its action-specific schema.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"default": {
"description": "Upstream response, HTTP status and content type preserved.",
"content": {
"application/json": {
"schema": {
"description": "Provider-owned JSON payload, forwarded without reshaping. Consult the upstream API for its action-specific schema.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
},
"x-runtime-validation": "legacy"
}PunkGen community
PUT/api/punkgen/generations/{shortId}/voteSet or remove your upvote
One upvote per authenticated browser creator or full-access operator key identity. Agent connections limited to punkgen:create cannot vote (403 insufficient_scope). PUT upvoted=true adds it; false removes it. Idempotent, including retries. Only completed, approved, currently public creations can be voted on. Private or unavailable targets return 404; blocked voters return 403. 120 requests per creator/minute; honor Retry-After. Anonymous browsers bootstrap /session first. No paid generation call.
Access: PunkGenSession or PunkGenKey
| Parameter | Location | Description |
|---|---|---|
| shortId * | path | shortId parameter |
Request and response schemas
{
"operationId": "setPunkGenUpvote",
"summary": "Set or remove your upvote",
"description": "One upvote per authenticated browser creator or full-access operator key identity. Agent connections limited to punkgen:create cannot vote (403 insufficient_scope). PUT upvoted=true adds it; false removes it. Idempotent, including retries. Only completed, approved, currently public creations can be voted on. Private or unavailable targets return 404; blocked voters return 403. 120 requests per creator/minute; honor Retry-After. Anonymous browsers bootstrap /session first. No paid generation call.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenSession": []
},
{
"PunkGenKey": []
}
],
"parameters": [
{
"name": "shortId",
"in": "path",
"required": true,
"description": "shortId parameter",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"upvoted": {
"type": "boolean"
}
},
"required": [
"upvoted"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"upvotes": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"upvoted": {
"type": "boolean"
}
},
"required": [
"upvotes",
"upvoted"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}GET/api/punkgen/maintenanceDispatch pending jobs and schedule maintenance
Operator-only Vercel Cron endpoint. Requires the CRON_SECRET Bearer token, never a creator key or browser session. Runs each minute in production. Disabled rollout returns enabled=false; enabled rollout enqueues durable maintenance and delivers the outbox.
Access: PunkGenCron
Request and response schemas
{
"operationId": "maintainPunkGen",
"summary": "Dispatch pending jobs and schedule maintenance",
"description": "Operator-only Vercel Cron endpoint. Requires the CRON_SECRET Bearer token, never a creator key or browser session. Runs each minute in production. Disabled rollout returns enabled=false; enabled rollout enqueues durable maintenance and delivers the outbox.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenCron": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"const": false
}
},
"required": [
"enabled"
],
"additionalProperties": false
}
}
}
},
"202": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"accepted": {
"type": "boolean",
"const": true
}
},
"required": [
"accepted"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}POST/api/punkgen/sessionCreate or renew an anonymous browser identity
Same-origin browser bootstrap. Resolves Better Auth session first, otherwise signs in anonymously; returns a stable random creator profile and HttpOnly session cookie. No paid call. This wrapper is the only anonymous sign-in surface; Better Auth's other HTTP endpoints are not exposed.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "bootstrapPunkGenSession",
"summary": "Create or renew an anonymous browser identity",
"description": "Same-origin browser bootstrap. Resolves Better Auth session first, otherwise signs in anonymously; returns a stable random creator profile and HttpOnly session cookie. No paid call. This wrapper is the only anonymous sign-in surface; Better Auth's other HTTP endpoints are not exposed.",
"tags": [
"PunkGen community"
],
"security": [],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
},
"publicEnabled": {
"type": "boolean"
},
"publicationAcknowledged": {
"type": "boolean"
},
"publicCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"id",
"handle",
"publicEnabled",
"publicationAcknowledged",
"publicCount"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}GET/api/punkgen/meGet your creator profile
Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.
Access: PunkGenSession or PunkGenKey
Request and response schemas
{
"operationId": "getPunkGenProfile",
"summary": "Get your creator profile",
"description": "Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenSession": []
},
{
"PunkGenKey": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
},
"publicEnabled": {
"type": "boolean"
},
"publicationAcknowledged": {
"type": "boolean"
},
"publicCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"id",
"handle",
"publicEnabled",
"publicationAcknowledged",
"publicCount"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}PATCH/api/punkgen/meSet master publication preference
Master-off hides all previously public generations immediately. Re-enabling requires confirmRestore=true; only individually public items are restored. acknowledgePublication=true records the first-visit publication notice.
Access: PunkGenSession or PunkGenKey
Request and response schemas
{
"operationId": "updatePunkGenProfile",
"summary": "Set master publication preference",
"description": "Master-off hides all previously public generations immediately. Re-enabling requires confirmRestore=true; only individually public items are restored. acknowledgePublication=true records the first-visit publication notice.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenSession": []
},
{
"PunkGenKey": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"publicEnabled": {
"type": "boolean"
},
"confirmRestore": {
"type": "boolean"
},
"acknowledgePublication": {
"type": "boolean"
}
},
"required": [
"publicEnabled"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
},
"publicEnabled": {
"type": "boolean"
},
"publicationAcknowledged": {
"type": "boolean"
},
"publicCount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"id",
"handle",
"publicEnabled",
"publicationAcknowledged",
"publicCount"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}GET/api/punkgen/me/generationsGet your completed and active creations
Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.
Access: PunkGenSession or PunkGenKey
| Parameter | Location | Description |
|---|---|---|
| punkId | query | punkId parameter |
| creator | query | creator parameter |
| cursor | query | cursor parameter |
| limit | query | limit parameter |
| sort | query | sort parameter |
Request and response schemas
{
"operationId": "getPunkGenHistory",
"summary": "Get your completed and active creations",
"description": "Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenSession": []
},
{
"PunkGenKey": []
}
],
"parameters": [
{
"name": "punkId",
"in": "query",
"required": false,
"description": "punkId parameter",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
{
"name": "creator",
"in": "query",
"required": false,
"description": "creator parameter",
"schema": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "cursor parameter",
"schema": {
"type": "string",
"maxLength": 1000
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "limit parameter",
"schema": {
"default": 24,
"type": "integer",
"minimum": 1,
"maximum": 48
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "sort parameter",
"schema": {
"default": "latest",
"type": "string",
"enum": [
"latest",
"top"
]
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"shortId": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
"punkId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"variant": {
"type": "string",
"enum": [
"head",
"naked"
]
},
"prompt": {
"type": "string"
},
"creator": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
},
"required": [
"id",
"handle"
],
"additionalProperties": false
},
"status": {
"type": "string",
"enum": [
"queued",
"generating",
"processing",
"completed",
"failed",
"reconciliation_required"
]
},
"publication": {
"type": "string",
"enum": [
"pending",
"approved",
"blocked"
]
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
]
},
"public": {
"type": "boolean"
},
"owned": {
"type": "boolean"
},
"upvotes": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"upvoted": {
"default": false,
"type": "boolean"
},
"images": {
"description": "Saved image versions. The original is the model output before background removal and pixel processing, when retained. Images are loaded separately; the feed stays native-sized.",
"default": [],
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"presentation",
"original"
]
},
"url": {
"type": "string"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"kind",
"url",
"width",
"height"
],
"additionalProperties": false
}
},
"createdAt": {
"type": "string"
},
"completedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"width": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"parent": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
{
"type": "null"
}
]
},
"imageUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"previewUrl": {
"description": "Native 24×24 or 32×32 PNG data URL, with the Punk background. Present when cached; use imageUrl as fallback and for downloads. Access rules are identical to the creation.",
"anyOf": [
{
"type": "string",
"maxLength": 12000,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+=*$"
},
{
"type": "null"
}
]
},
"pageUrl": {
"type": "string"
},
"statusUrl": {
"type": "string"
},
"estimatedSeconds": {
"type": "object",
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number"
}
},
"required": [
"min",
"max"
],
"additionalProperties": false
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"method": {
"default": "image",
"type": "string",
"enum": [
"image",
"pixel-agent"
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"shortId",
"punkId",
"variant",
"prompt",
"creator",
"status",
"publication",
"visibility",
"public",
"owned",
"upvotes",
"upvoted",
"images",
"createdAt",
"completedAt",
"width",
"height",
"parent",
"imageUrl",
"pageUrl",
"statusUrl",
"estimatedSeconds",
"model",
"method",
"error"
],
"additionalProperties": false
}
},
"active": {
"type": "array",
"items": {
"type": "object",
"properties": {
"shortId": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
"punkId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"variant": {
"type": "string",
"enum": [
"head",
"naked"
]
},
"prompt": {
"type": "string"
},
"creator": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
},
"required": [
"id",
"handle"
],
"additionalProperties": false
},
"status": {
"type": "string",
"enum": [
"queued",
"generating",
"processing",
"completed",
"failed",
"reconciliation_required"
]
},
"publication": {
"type": "string",
"enum": [
"pending",
"approved",
"blocked"
]
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
]
},
"public": {
"type": "boolean"
},
"owned": {
"type": "boolean"
},
"upvotes": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"upvoted": {
"default": false,
"type": "boolean"
},
"images": {
"description": "Saved image versions. The original is the model output before background removal and pixel processing, when retained. Images are loaded separately; the feed stays native-sized.",
"default": [],
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"presentation",
"original"
]
},
"url": {
"type": "string"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"kind",
"url",
"width",
"height"
],
"additionalProperties": false
}
},
"createdAt": {
"type": "string"
},
"completedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"width": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"parent": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
{
"type": "null"
}
]
},
"imageUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"previewUrl": {
"description": "Native 24×24 or 32×32 PNG data URL, with the Punk background. Present when cached; use imageUrl as fallback and for downloads. Access rules are identical to the creation.",
"anyOf": [
{
"type": "string",
"maxLength": 12000,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+=*$"
},
{
"type": "null"
}
]
},
"pageUrl": {
"type": "string"
},
"statusUrl": {
"type": "string"
},
"estimatedSeconds": {
"type": "object",
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number"
}
},
"required": [
"min",
"max"
],
"additionalProperties": false
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"method": {
"default": "image",
"type": "string",
"enum": [
"image",
"pixel-agent"
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"shortId",
"punkId",
"variant",
"prompt",
"creator",
"status",
"publication",
"visibility",
"public",
"owned",
"upvotes",
"upvoted",
"images",
"createdAt",
"completedAt",
"width",
"height",
"parent",
"imageUrl",
"pageUrl",
"statusUrl",
"estimatedSeconds",
"model",
"method",
"error"
],
"additionalProperties": false
}
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"items",
"active",
"cursor"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}GET/api/punkgen/generationsBrowse public creations
sort=latest (default) returns newest completed creations first; the UI places newest at the bottom. sort=top returns highest upvotes first, then newest completion. Votes are live, so ranks may change between pages; refresh from the start to obtain current rankings. Punk ID and creator filters combine with AND. Cursor binds the filters and sort; default 24, max 48. Existing identities receive personalized upvoted state; no identity is created for public browsing.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| punkId | query | punkId parameter |
| creator | query | creator parameter |
| cursor | query | cursor parameter |
| limit | query | limit parameter |
| sort | query | sort parameter |
Request and response schemas
{
"operationId": "getPunkGenFeed",
"summary": "Browse public creations",
"description": "sort=latest (default) returns newest completed creations first; the UI places newest at the bottom. sort=top returns highest upvotes first, then newest completion. Votes are live, so ranks may change between pages; refresh from the start to obtain current rankings. Punk ID and creator filters combine with AND. Cursor binds the filters and sort; default 24, max 48. Existing identities receive personalized upvoted state; no identity is created for public browsing.",
"tags": [
"PunkGen community"
],
"security": [],
"parameters": [
{
"name": "punkId",
"in": "query",
"required": false,
"description": "punkId parameter",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
{
"name": "creator",
"in": "query",
"required": false,
"description": "creator parameter",
"schema": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "cursor parameter",
"schema": {
"type": "string",
"maxLength": 1000
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "limit parameter",
"schema": {
"default": 24,
"type": "integer",
"minimum": 1,
"maximum": 48
}
},
{
"name": "sort",
"in": "query",
"required": false,
"description": "sort parameter",
"schema": {
"default": "latest",
"type": "string",
"enum": [
"latest",
"top"
]
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"shortId": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
"punkId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"variant": {
"type": "string",
"enum": [
"head",
"naked"
]
},
"prompt": {
"type": "string"
},
"creator": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
},
"required": [
"id",
"handle"
],
"additionalProperties": false
},
"status": {
"type": "string",
"enum": [
"queued",
"generating",
"processing",
"completed",
"failed",
"reconciliation_required"
]
},
"publication": {
"type": "string",
"enum": [
"pending",
"approved",
"blocked"
]
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
]
},
"public": {
"type": "boolean"
},
"owned": {
"type": "boolean"
},
"upvotes": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"upvoted": {
"default": false,
"type": "boolean"
},
"images": {
"description": "Saved image versions. The original is the model output before background removal and pixel processing, when retained. Images are loaded separately; the feed stays native-sized.",
"default": [],
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"presentation",
"original"
]
},
"url": {
"type": "string"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"kind",
"url",
"width",
"height"
],
"additionalProperties": false
}
},
"createdAt": {
"type": "string"
},
"completedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"width": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"parent": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
{
"type": "null"
}
]
},
"imageUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"previewUrl": {
"description": "Native 24×24 or 32×32 PNG data URL, with the Punk background. Present when cached; use imageUrl as fallback and for downloads. Access rules are identical to the creation.",
"anyOf": [
{
"type": "string",
"maxLength": 12000,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+=*$"
},
{
"type": "null"
}
]
},
"pageUrl": {
"type": "string"
},
"statusUrl": {
"type": "string"
},
"estimatedSeconds": {
"type": "object",
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number"
}
},
"required": [
"min",
"max"
],
"additionalProperties": false
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"method": {
"default": "image",
"type": "string",
"enum": [
"image",
"pixel-agent"
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"shortId",
"punkId",
"variant",
"prompt",
"creator",
"status",
"publication",
"visibility",
"public",
"owned",
"upvotes",
"upvoted",
"images",
"createdAt",
"completedAt",
"width",
"height",
"parent",
"imageUrl",
"pageUrl",
"statusUrl",
"estimatedSeconds",
"model",
"method",
"error"
],
"additionalProperties": false
}
},
"active": {
"type": "array",
"items": {
"type": "object",
"properties": {
"shortId": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
"punkId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"variant": {
"type": "string",
"enum": [
"head",
"naked"
]
},
"prompt": {
"type": "string"
},
"creator": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
},
"required": [
"id",
"handle"
],
"additionalProperties": false
},
"status": {
"type": "string",
"enum": [
"queued",
"generating",
"processing",
"completed",
"failed",
"reconciliation_required"
]
},
"publication": {
"type": "string",
"enum": [
"pending",
"approved",
"blocked"
]
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
]
},
"public": {
"type": "boolean"
},
"owned": {
"type": "boolean"
},
"upvotes": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"upvoted": {
"default": false,
"type": "boolean"
},
"images": {
"description": "Saved image versions. The original is the model output before background removal and pixel processing, when retained. Images are loaded separately; the feed stays native-sized.",
"default": [],
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"presentation",
"original"
]
},
"url": {
"type": "string"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"kind",
"url",
"width",
"height"
],
"additionalProperties": false
}
},
"createdAt": {
"type": "string"
},
"completedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"width": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"parent": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
{
"type": "null"
}
]
},
"imageUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"previewUrl": {
"description": "Native 24×24 or 32×32 PNG data URL, with the Punk background. Present when cached; use imageUrl as fallback and for downloads. Access rules are identical to the creation.",
"anyOf": [
{
"type": "string",
"maxLength": 12000,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+=*$"
},
{
"type": "null"
}
]
},
"pageUrl": {
"type": "string"
},
"statusUrl": {
"type": "string"
},
"estimatedSeconds": {
"type": "object",
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number"
}
},
"required": [
"min",
"max"
],
"additionalProperties": false
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"method": {
"default": "image",
"type": "string",
"enum": [
"image",
"pixel-agent"
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"shortId",
"punkId",
"variant",
"prompt",
"creator",
"status",
"publication",
"visibility",
"public",
"owned",
"upvotes",
"upvoted",
"images",
"createdAt",
"completedAt",
"width",
"height",
"parent",
"imageUrl",
"pageUrl",
"statusUrl",
"estimatedSeconds",
"model",
"method",
"error"
],
"additionalProperties": false
}
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"items",
"active",
"cursor"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}POST/api/punkgen/generationsQueue and save a punk generation
Requires Idempotency-Key: 16–128 ASCII letters/digits/_/-. Reuse exactly that key and payload after transport failure; conflicting payload returns 409. Browser defaults follow the acknowledged profile setting. Scoped Bearer keys default to private; the legacy global x-api-key grants no community access. Agent keys (scope punkgen:create) cannot request visibility=public (403 insufficient_scope), and every Bearer key is admitted per key rather than per IP. parent edits the actual saved alpha sprite and must keep its Punk ID/variant. 10 creations per creator/hour, 10/IP/hour, 100 globally/hour. A provider outcome marked reconciliation_required is never automatically charged again.
Access: PunkGenSession or PunkGenKey
| Parameter | Location | Description |
|---|---|---|
| Idempotency-Key * | header | Idempotency-Key parameter |
Request and response schemas
{
"operationId": "createSavedPunk",
"summary": "Queue and save a punk generation",
"description": "Requires Idempotency-Key: 16–128 ASCII letters/digits/_/-. Reuse exactly that key and payload after transport failure; conflicting payload returns 409. Browser defaults follow the acknowledged profile setting. Scoped Bearer keys default to private; the legacy global x-api-key grants no community access. Agent keys (scope punkgen:create) cannot request visibility=public (403 insufficient_scope), and every Bearer key is admitted per key rather than per IP. parent edits the actual saved alpha sprite and must keep its Punk ID/variant. 10 creations per creator/hour, 10/IP/hour, 100 globally/hour. A provider outcome marked reconciliation_required is never automatically charged again.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenSession": []
},
{
"PunkGenKey": []
}
],
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"description": "Idempotency-Key parameter",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16,128}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"if": {
"required": [
"method"
],
"properties": {
"method": {
"const": "pixel-agent"
}
}
},
"then": {
"not": {
"required": [
"parent"
]
}
}
}
],
"type": "object",
"properties": {
"punkId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"variant": {
"default": "head",
"type": "string",
"enum": [
"head",
"naked"
]
},
"prompt": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"method": {
"type": "string",
"enum": [
"image",
"pixel-agent"
]
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
]
},
"parent": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
}
},
"required": [
"punkId",
"prompt"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Accepted durable job. Poll statusUrl (initially every 2.5 seconds), stopping when status and publication are terminal. Estimated time is not provider progress.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"shortId": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
"punkId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"variant": {
"type": "string",
"enum": [
"head",
"naked"
]
},
"prompt": {
"type": "string"
},
"creator": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
},
"required": [
"id",
"handle"
],
"additionalProperties": false
},
"status": {
"type": "string",
"enum": [
"queued",
"generating",
"processing",
"completed",
"failed",
"reconciliation_required"
]
},
"publication": {
"type": "string",
"enum": [
"pending",
"approved",
"blocked"
]
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
]
},
"public": {
"type": "boolean"
},
"owned": {
"type": "boolean"
},
"upvotes": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"upvoted": {
"default": false,
"type": "boolean"
},
"images": {
"description": "Saved image versions. The original is the model output before background removal and pixel processing, when retained. Images are loaded separately; the feed stays native-sized.",
"default": [],
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"presentation",
"original"
]
},
"url": {
"type": "string"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"kind",
"url",
"width",
"height"
],
"additionalProperties": false
}
},
"createdAt": {
"type": "string"
},
"completedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"width": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"parent": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
{
"type": "null"
}
]
},
"imageUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"previewUrl": {
"description": "Native 24×24 or 32×32 PNG data URL, with the Punk background. Present when cached; use imageUrl as fallback and for downloads. Access rules are identical to the creation.",
"anyOf": [
{
"type": "string",
"maxLength": 12000,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+=*$"
},
{
"type": "null"
}
]
},
"pageUrl": {
"type": "string"
},
"statusUrl": {
"type": "string"
},
"estimatedSeconds": {
"type": "object",
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number"
}
},
"required": [
"min",
"max"
],
"additionalProperties": false
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"method": {
"default": "image",
"type": "string",
"enum": [
"image",
"pixel-agent"
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"shortId",
"punkId",
"variant",
"prompt",
"creator",
"status",
"publication",
"visibility",
"public",
"owned",
"upvotes",
"upvoted",
"images",
"createdAt",
"completedAt",
"width",
"height",
"parent",
"imageUrl",
"pageUrl",
"statusUrl",
"estimatedSeconds",
"model",
"method",
"error"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}GET/api/punkgen/generations/{shortId}Get a creation and its job status
Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| shortId * | path | shortId parameter |
Request and response schemas
{
"operationId": "getSavedPunk",
"summary": "Get a creation and its job status",
"description": "Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.",
"tags": [
"PunkGen community"
],
"security": [],
"parameters": [
{
"name": "shortId",
"in": "path",
"required": true,
"description": "shortId parameter",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"shortId": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
"punkId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"variant": {
"type": "string",
"enum": [
"head",
"naked"
]
},
"prompt": {
"type": "string"
},
"creator": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
},
"required": [
"id",
"handle"
],
"additionalProperties": false
},
"status": {
"type": "string",
"enum": [
"queued",
"generating",
"processing",
"completed",
"failed",
"reconciliation_required"
]
},
"publication": {
"type": "string",
"enum": [
"pending",
"approved",
"blocked"
]
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
]
},
"public": {
"type": "boolean"
},
"owned": {
"type": "boolean"
},
"upvotes": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"upvoted": {
"default": false,
"type": "boolean"
},
"images": {
"description": "Saved image versions. The original is the model output before background removal and pixel processing, when retained. Images are loaded separately; the feed stays native-sized.",
"default": [],
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"presentation",
"original"
]
},
"url": {
"type": "string"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"kind",
"url",
"width",
"height"
],
"additionalProperties": false
}
},
"createdAt": {
"type": "string"
},
"completedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"width": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"parent": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
{
"type": "null"
}
]
},
"imageUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"previewUrl": {
"description": "Native 24×24 or 32×32 PNG data URL, with the Punk background. Present when cached; use imageUrl as fallback and for downloads. Access rules are identical to the creation.",
"anyOf": [
{
"type": "string",
"maxLength": 12000,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+=*$"
},
{
"type": "null"
}
]
},
"pageUrl": {
"type": "string"
},
"statusUrl": {
"type": "string"
},
"estimatedSeconds": {
"type": "object",
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number"
}
},
"required": [
"min",
"max"
],
"additionalProperties": false
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"method": {
"default": "image",
"type": "string",
"enum": [
"image",
"pixel-agent"
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"shortId",
"punkId",
"variant",
"prompt",
"creator",
"status",
"publication",
"visibility",
"public",
"owned",
"upvotes",
"upvoted",
"images",
"createdAt",
"completedAt",
"width",
"height",
"parent",
"imageUrl",
"pageUrl",
"statusUrl",
"estimatedSeconds",
"model",
"method",
"error"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}PATCH/api/punkgen/generations/{shortId}Publish or hide your creation
Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.
Access: PunkGenSession or PunkGenKey
| Parameter | Location | Description |
|---|---|---|
| shortId * | path | shortId parameter |
Request and response schemas
{
"operationId": "updateSavedPunkVisibility",
"summary": "Publish or hide your creation",
"description": "Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenSession": []
},
{
"PunkGenKey": []
}
],
"parameters": [
{
"name": "shortId",
"in": "path",
"required": true,
"description": "shortId parameter",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"visibility": {
"type": "string",
"enum": [
"public",
"private"
]
}
},
"required": [
"visibility"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"shortId": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
"punkId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"variant": {
"type": "string",
"enum": [
"head",
"naked"
]
},
"prompt": {
"type": "string"
},
"creator": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
},
"required": [
"id",
"handle"
],
"additionalProperties": false
},
"status": {
"type": "string",
"enum": [
"queued",
"generating",
"processing",
"completed",
"failed",
"reconciliation_required"
]
},
"publication": {
"type": "string",
"enum": [
"pending",
"approved",
"blocked"
]
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
]
},
"public": {
"type": "boolean"
},
"owned": {
"type": "boolean"
},
"upvotes": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"upvoted": {
"default": false,
"type": "boolean"
},
"images": {
"description": "Saved image versions. The original is the model output before background removal and pixel processing, when retained. Images are loaded separately; the feed stays native-sized.",
"default": [],
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"presentation",
"original"
]
},
"url": {
"type": "string"
},
"width": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"kind",
"url",
"width",
"height"
],
"additionalProperties": false
}
},
"createdAt": {
"type": "string"
},
"completedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"width": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"height": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"parent": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
},
{
"type": "null"
}
]
},
"imageUrl": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"previewUrl": {
"description": "Native 24×24 or 32×32 PNG data URL, with the Punk background. Present when cached; use imageUrl as fallback and for downloads. Access rules are identical to the creation.",
"anyOf": [
{
"type": "string",
"maxLength": 12000,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+=*$"
},
{
"type": "null"
}
]
},
"pageUrl": {
"type": "string"
},
"statusUrl": {
"type": "string"
},
"estimatedSeconds": {
"type": "object",
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number"
}
},
"required": [
"min",
"max"
],
"additionalProperties": false
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"method": {
"default": "image",
"type": "string",
"enum": [
"image",
"pixel-agent"
]
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"shortId",
"punkId",
"variant",
"prompt",
"creator",
"status",
"publication",
"visibility",
"public",
"owned",
"upvotes",
"upvoted",
"images",
"createdAt",
"completedAt",
"width",
"height",
"parent",
"imageUrl",
"pageUrl",
"statusUrl",
"estimatedSeconds",
"model",
"method",
"error"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}DELETE/api/punkgen/generations/{shortId}Delete your creation
Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.
Access: PunkGenSession or PunkGenKey
| Parameter | Location | Description |
|---|---|---|
| shortId * | path | shortId parameter |
Request and response schemas
{
"operationId": "deleteSavedPunk",
"summary": "Delete your creation",
"description": "Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenSession": []
},
{
"PunkGenKey": []
}
],
"parameters": [
{
"name": "shortId",
"in": "path",
"required": true,
"description": "shortId parameter",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
}
},
"required": [
"ok"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}GET/api/punkgen/generations/{shortId}/imageRead native or enlarged PNG pixels
Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| shortId * | path | shortId parameter |
| kind | query | kind parameter |
| download | query | download parameter |
| scale | query | scale parameter |
Request and response schemas
{
"operationId": "getSavedPunkImage",
"summary": "Read native or enlarged PNG pixels",
"description": "Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.",
"tags": [
"PunkGen community"
],
"security": [],
"parameters": [
{
"name": "shortId",
"in": "path",
"required": true,
"description": "shortId parameter",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
}
},
{
"name": "kind",
"in": "query",
"required": false,
"description": "kind parameter",
"schema": {
"default": "presentation",
"type": "string",
"enum": [
"alpha",
"presentation",
"thumbnail",
"original"
]
}
},
{
"name": "download",
"in": "query",
"required": false,
"description": "download parameter",
"schema": {
"type": "string",
"enum": [
"1"
]
}
},
{
"name": "scale",
"in": "query",
"required": false,
"description": "scale parameter",
"schema": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 32
}
}
],
"responses": {
"200": {
"description": "Native 24×24 head or 32×32 body. alpha retains transparency; presentation and thumbnail use #638596. scale=1 (default) keeps native pixels; integer scale=2..32 enlarges with nearest-neighbor sampling (maximum 1024px per side). scale=10 yields 240×240 heads or 320×320 bodies. download=1 adds Content-Disposition. kind=original serves the retained model PNG before background removal and quantization, in its original dimensions; scale must be 1. Available versions are listed in Creation.images; old generations and pixel-agent generations may have no original. Every read checks current visibility.",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}GET/api/punkgen/creators/{handle}Get a public creator
Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| handle * | path | handle parameter |
Request and response schemas
{
"operationId": "getPunkGenCreator",
"summary": "Get a public creator",
"description": "Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.",
"tags": [
"PunkGen community"
],
"security": [],
"parameters": [
{
"name": "handle",
"in": "path",
"required": true,
"description": "handle parameter",
"schema": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"handle": {
"type": "string",
"pattern": "^[a-z]+-[a-z]+-[0-9a-f]{8}$"
}
},
"required": [
"id",
"handle"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}POST/api/punkgen/generations/{shortId}/reportsReport a creation or lost-session removal concern
Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| shortId * | path | shortId parameter |
Request and response schemas
{
"operationId": "reportSavedPunk",
"summary": "Report a creation or lost-session removal concern",
"description": "Access-sensitive responses use private, no-store. Cookie mutations require the canonical Origin. Private, deleted or unapproved creations return 404 to outsiders. Community routes return 503 while rollout is disabled.",
"tags": [
"PunkGen community"
],
"security": [],
"parameters": [
{
"name": "shortId",
"in": "path",
"required": true,
"description": "shortId parameter",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9]{12}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"enum": [
"harmful",
"personal-information",
"rights",
"other"
]
},
"detail": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"reason"
],
"additionalProperties": false
}
}
}
},
"responses": {
"202": {
"description": "Report accepted without confirming whether the target exists. Max 10 per IP/hour. Review is manual; reports do not auto-hide content.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
}
},
"required": [
"ok"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}POST/api/punkgen/oauth/device_authorizationStart connecting an agent (device authorization)
Agents connect with the OAuth 2.0 Device Authorization Grant (RFC 8628); discovery at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/api/punkgen. The person approves in their own browser, so an agent never asks anyone for a key. Public client: client_id is the agent's short display name, shown to the person as self-declared. Send application/x-www-form-urlencoded (JSON is also accepted). scope, when present, must be punkgen:create. 30 requests per IP/hour.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "startPunkGenAgentConnection",
"summary": "Start connecting an agent (device authorization)",
"description": "Agents connect with the OAuth 2.0 Device Authorization Grant (RFC 8628); discovery at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/api/punkgen. The person approves in their own browser, so an agent never asks anyone for a key. Public client: client_id is the agent's short display name, shown to the person as self-declared. Send application/x-www-form-urlencoded (JSON is also accepted). scope, when present, must be punkgen:create. 30 requests per IP/hour.",
"tags": [
"PunkGen community"
],
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"client_id": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[\\p{L}\\p{N} ._'()@-]+$"
},
"scope": {
"type": "string",
"maxLength": 200
}
},
"required": [
"client_id"
]
}
}
}
},
"responses": {
"200": {
"description": "Show verification_uri_complete (or verification_uri and user_code) to the person, then poll the token endpoint every interval seconds until expires_in.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"device_code": {
"type": "string"
},
"user_code": {
"type": "string",
"pattern": "^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$"
},
"verification_uri": {
"type": "string"
},
"verification_uri_complete": {
"type": "string"
},
"expires_in": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"interval": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"device_code",
"user_code",
"verification_uri",
"verification_uri_complete",
"expires_in",
"interval"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "RFC 6749 error. authorization_pending: keep polling at the interval. slow_down: add 5 seconds. access_denied, expired_token and invalid_grant are final.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_request",
"invalid_grant",
"unsupported_grant_type",
"invalid_scope",
"authorization_pending",
"slow_down",
"access_denied",
"expired_token",
"temporarily_unavailable"
]
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "RFC 6749 error body; temporarily_unavailable on rate limit or outage.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_request",
"invalid_grant",
"unsupported_grant_type",
"invalid_scope",
"authorization_pending",
"slow_down",
"access_denied",
"expired_token",
"temporarily_unavailable"
]
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "RFC 6749 error body; temporarily_unavailable on rate limit or outage.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_request",
"invalid_grant",
"unsupported_grant_type",
"invalid_scope",
"authorization_pending",
"slow_down",
"access_denied",
"expired_token",
"temporarily_unavailable"
]
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "RFC 6749 error body; temporarily_unavailable on rate limit or outage.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_request",
"invalid_grant",
"unsupported_grant_type",
"invalid_scope",
"authorization_pending",
"slow_down",
"access_denied",
"expired_token",
"temporarily_unavailable"
]
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "RFC 6749 error body; temporarily_unavailable on rate limit or outage.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_request",
"invalid_grant",
"unsupported_grant_type",
"invalid_scope",
"authorization_pending",
"slow_down",
"access_denied",
"expired_token",
"temporarily_unavailable"
]
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}POST/api/punkgen/oauth/tokenPoll for the agent's key
Agents connect with the OAuth 2.0 Device Authorization Grant (RFC 8628); discovery at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/api/punkgen. The person approves in their own browser, so an agent never asks anyone for a key. Send grant_type=urn:ietf:params:oauth:grant-type:device_code with the device_code. A device code is single use.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "finishPunkGenAgentConnection",
"summary": "Poll for the agent's key",
"description": "Agents connect with the OAuth 2.0 Device Authorization Grant (RFC 8628); discovery at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/api/punkgen. The person approves in their own browser, so an agent never asks anyone for a key. Send grant_type=urn:ietf:params:oauth:grant-type:device_code with the device_code. A device code is single use.",
"tags": [
"PunkGen community"
],
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"grant_type": {
"type": "string",
"const": "urn:ietf:params:oauth:grant-type:device_code"
},
"device_code": {
"type": "string",
"minLength": 16,
"maxLength": 128
},
"client_id": {
"type": "string",
"maxLength": 64
}
},
"required": [
"grant_type",
"device_code"
]
}
}
}
},
"responses": {
"200": {
"description": "access_token is a pg_ Bearer key with scope punkgen:create, issued once. Store it outside model context; the person can disconnect it anytime.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"token_type": {
"type": "string",
"const": "Bearer"
},
"scope": {
"type": "string",
"const": "punkgen:create"
}
},
"required": [
"access_token",
"token_type",
"scope"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "RFC 6749 error. authorization_pending: keep polling at the interval. slow_down: add 5 seconds. access_denied, expired_token and invalid_grant are final.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_request",
"invalid_grant",
"unsupported_grant_type",
"invalid_scope",
"authorization_pending",
"slow_down",
"access_denied",
"expired_token",
"temporarily_unavailable"
]
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "RFC 6749 error body; temporarily_unavailable on rate limit or outage.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_request",
"invalid_grant",
"unsupported_grant_type",
"invalid_scope",
"authorization_pending",
"slow_down",
"access_denied",
"expired_token",
"temporarily_unavailable"
]
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "RFC 6749 error body; temporarily_unavailable on rate limit or outage.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_request",
"invalid_grant",
"unsupported_grant_type",
"invalid_scope",
"authorization_pending",
"slow_down",
"access_denied",
"expired_token",
"temporarily_unavailable"
]
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "RFC 6749 error body; temporarily_unavailable on rate limit or outage.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_request",
"invalid_grant",
"unsupported_grant_type",
"invalid_scope",
"authorization_pending",
"slow_down",
"access_denied",
"expired_token",
"temporarily_unavailable"
]
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "RFC 6749 error body; temporarily_unavailable on rate limit or outage.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"enum": [
"invalid_request",
"invalid_grant",
"unsupported_grant_type",
"invalid_scope",
"authorization_pending",
"slow_down",
"access_denied",
"expired_token",
"temporarily_unavailable"
]
},
"error_description": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}GET/api/punkgen/agents/requests/{userCode}Review an agent connection request
Browser data for /generate/link. Rejects Authorization headers. clientName is self-declared by the agent. Unknown, expired or decided codes return 404. 60 per IP/hour.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| userCode * | path | userCode parameter |
Request and response schemas
{
"operationId": "getPunkGenAgentRequest",
"summary": "Review an agent connection request",
"description": "Browser data for /generate/link. Rejects Authorization headers. clientName is self-declared by the agent. Unknown, expired or decided codes return 404. 60 per IP/hour.",
"tags": [
"PunkGen community"
],
"security": [],
"parameters": [
{
"name": "userCode",
"in": "path",
"required": true,
"description": "userCode parameter",
"schema": {
"type": "string",
"pattern": "^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"clientName": {
"description": "Self-declared by the agent; never proof of who operates it.",
"type": "string"
},
"userCode": {
"type": "string",
"pattern": "^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$"
},
"expiresAt": {
"type": "string"
},
"access": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"const": "punkgen:create"
},
"visibility": {
"type": "string",
"const": "private"
},
"hourlyLimit": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"scope",
"visibility",
"hourlyLimit"
],
"additionalProperties": false
}
},
"required": [
"clientName",
"userCode",
"expiresAt",
"access"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}POST/api/punkgen/agents/requests/{userCode}Approve or deny an agent
Browser session only: canonical Origin required, behind the browser challenge, and any Authorization header is rejected so no key can approve another agent. Approval binds the agent to this creator. 30 per IP/hour.
Access: PunkGenSession
| Parameter | Location | Description |
|---|---|---|
| userCode * | path | userCode parameter |
Request and response schemas
{
"operationId": "decidePunkGenAgentRequest",
"summary": "Approve or deny an agent",
"description": "Browser session only: canonical Origin required, behind the browser challenge, and any Authorization header is rejected so no key can approve another agent. Approval binds the agent to this creator. 30 per IP/hour.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenSession": []
}
],
"parameters": [
{
"name": "userCode",
"in": "path",
"required": true,
"description": "userCode parameter",
"schema": {
"type": "string",
"pattern": "^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"decision": {
"type": "string",
"enum": [
"approve",
"deny"
]
}
},
"required": [
"decision"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"approved",
"denied"
]
}
},
"required": [
"status"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}GET/api/punkgen/me/agentsList agents connected to you
Active device-grant connections, newest first. Agent keys receive 403 insufficient_scope.
Access: PunkGenSession or PunkGenKey
Request and response schemas
{
"operationId": "listPunkGenAgents",
"summary": "List agents connected to you",
"description": "Active device-grant connections, newest first. Agent keys receive 403 insufficient_scope.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenSession": []
},
{
"PunkGenKey": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{12}$"
},
"name": {
"type": "string"
},
"scope": {
"type": "string",
"const": "punkgen:create"
},
"createdAt": {
"type": "string"
}
},
"required": [
"id",
"name",
"scope",
"createdAt"
],
"additionalProperties": false
}
}
},
"required": [
"items"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}DELETE/api/punkgen/me/agents/{id}Disconnect an agent
Revokes the agent's key immediately. Agent keys receive 403 insufficient_scope.
Access: PunkGenSession or PunkGenKey
| Parameter | Location | Description |
|---|---|---|
| id * | path | id parameter |
Request and response schemas
{
"operationId": "disconnectPunkGenAgent",
"summary": "Disconnect an agent",
"description": "Revokes the agent's key immediately. Agent keys receive 403 insufficient_scope.",
"tags": [
"PunkGen community"
],
"security": [
{
"PunkGenSession": []
},
{
"PunkGenKey": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id parameter",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{12}$"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
}
},
"required": [
"ok"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"409": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Rate limit; honor Retry-After. A browser verification challenge may also precede the handler.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Machine-readable error code and user-facing message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"error",
"code"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}Generation
POST/api/nakedpunks/generateGenerate or edit a punk head, body or custom sprite
Stateless image editing. Supply a prompt and exactly one of punkId, imageDataUrl or imageUrl. variant=head selects a canonical head and exact 24x24 output; naked selects a body and 32x32. auto keeps the legacy naked punkId default, infers the grid from canonical URLs or PNGs no larger than 256x256, and otherwise detects the grid. An explicit canvas overrides auto detection. Grid guarantees apply when quantize=true (default). quantize=false returns provider resolution and the target canvas for local processing. Reuse response.image as the next request's imageDataUrl for conversational edits. All engines share the same canvas/postprocessing path. method=image (default) edits with an image engine then snaps to the grid. method=pixel-agent is experimental: an OpenAI reasoning model draws the exact grid from a punkId head or naked source, sees each render and revises up to agent.iterations times; engine, removeBackground, quantize and kColors do not apply, the response engine is null and response.agent carries every turn. Engines: nano2 = Nano 2 (fal-ai/nano-banana-2/edit); nano = Nano Pro (fal-ai/nano-banana-pro/edit); gpt25 = GPT Image 2.5 (gpt-image-2.5-sunburst-2026-09-08); gpt = GPT Image 2 (openai/gpt-image-2/edit); retro = Retro (RD_FLUX); pixellab = PixelLab (pixellab/v2/edit-image). Headless callers must supply x-api-key. The first-party UI also has a same-origin path gated by deployment configuration and firewall challenge; it is not a credential-free integration API. No CORS contract is provided; call from your server. Responses are no-store. Server deadline: 270 seconds. Configure clients for at least 280 seconds. No idempotency key or automatic retry is implemented; a cancelled request may already have incurred provider cost. Deployment firewall limits may return 429 or an HTML challenge before this handler.
Access: PunkApiKey
Request and response schemas
{
"operationId": "generatePunk",
"summary": "Generate or edit a punk head, body or custom sprite",
"description": "Stateless image editing. Supply a prompt and exactly one of punkId, imageDataUrl or imageUrl. variant=head selects a canonical head and exact 24x24 output; naked selects a body and 32x32. auto keeps the legacy naked punkId default, infers the grid from canonical URLs or PNGs no larger than 256x256, and otherwise detects the grid. An explicit canvas overrides auto detection. Grid guarantees apply when quantize=true (default). quantize=false returns provider resolution and the target canvas for local processing. Reuse response.image as the next request's imageDataUrl for conversational edits. All engines share the same canvas/postprocessing path. method=image (default) edits with an image engine then snaps to the grid. method=pixel-agent is experimental: an OpenAI reasoning model draws the exact grid from a punkId head or naked source, sees each render and revises up to agent.iterations times; engine, removeBackground, quantize and kColors do not apply, the response engine is null and response.agent carries every turn. Engines: nano2 = Nano 2 (fal-ai/nano-banana-2/edit); nano = Nano Pro (fal-ai/nano-banana-pro/edit); gpt25 = GPT Image 2.5 (gpt-image-2.5-sunburst-2026-09-08); gpt = GPT Image 2 (openai/gpt-image-2/edit); retro = Retro (RD_FLUX); pixellab = PixelLab (pixellab/v2/edit-image). Headless callers must supply x-api-key. The first-party UI also has a same-origin path gated by deployment configuration and firewall challenge; it is not a credential-free integration API. No CORS contract is provided; call from your server. Responses are no-store. Server deadline: 270 seconds. Configure clients for at least 280 seconds. No idempotency key or automatic retry is implemented; a cancelled request may already have incurred provider cost. Deployment firewall limits may return 429 or an HTML challenge before this handler.",
"tags": [
"Generation"
],
"security": [
{
"PunkApiKey": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OutfitRequest"
}
}
}
},
"responses": {
"200": {
"description": "PNG data URL, actual encoded dimensions, target grid, model provenance and timings in milliseconds.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OutfitResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Access denied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Request or image too large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Deployment firewall rate limit. Wait for the configured window; do not automatically retry a paid generation.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
},
"text/html": {
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Generation or upstream failure",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Service not configured",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"504": {
"description": "Request timed out or cancelled",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}POST/api/nakedpunks/judgeScore a generated punk against its source with a vision judge
Evaluation helper for comparing generation methods and models on the same prompt. Fetches the renderer's native source for punkId (head 24x24, naked 32x32), enlarges both images with square cells and asks gemini-3-flash-preview at temperature 0 to score adherence, identity, style, cleanliness and overall from 0 to 10. Send image=response.image from generatePunk with quantize=true. The judge writes its notes and a changeVisible yes/no before any score; adherence is 0 when the change is not visible. Omit image to run the negative control: the unchanged source judged as the result must get changeVisible=false and adherence at most 3; controlPassed=false means this judge's scores are not trustworthy. Requires x-api-key, even when generatePunk is open to browsers. Server deadline: 100 seconds. Every call is a paid model call and nothing is cached.
Access: PunkApiKey
Request and response schemas
{
"operationId": "judgePunk",
"summary": "Score a generated punk against its source with a vision judge",
"description": "Evaluation helper for comparing generation methods and models on the same prompt. Fetches the renderer's native source for punkId (head 24x24, naked 32x32), enlarges both images with square cells and asks gemini-3-flash-preview at temperature 0 to score adherence, identity, style, cleanliness and overall from 0 to 10. Send image=response.image from generatePunk with quantize=true. The judge writes its notes and a changeVisible yes/no before any score; adherence is 0 when the change is not visible. Omit image to run the negative control: the unchanged source judged as the result must get changeVisible=false and adherence at most 3; controlPassed=false means this judge's scores are not trustworthy. Requires x-api-key, even when generatePunk is open to browsers. Server deadline: 100 seconds. Every call is a paid model call and nothing is cached.",
"tags": [
"Generation"
],
"security": [
{
"PunkApiKey": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JudgeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Integer scores, a one-sentence note, and whether this was a passing control.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JudgeResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Access denied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Request or image too large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"415": {
"description": "Expected application/json",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"429": {
"description": "Deployment firewall rate limit. Wait for the configured window.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
},
"text/html": {
"schema": {
"type": "string"
}
}
}
},
"502": {
"description": "Generation or upstream failure",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Service not configured",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"504": {
"description": "Request timed out or cancelled",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "zod"
}POST/api/autonym/stencilGenerate a black-and-white QR stencil
Legacy public generation route using fal FLUX Schnell. Returns a data URL with the upstream image MIME type. Prompt limit 200 characters; deployment budget 30 seconds.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "generateStencil",
"summary": "Generate a black-and-white QR stencil",
"description": "Legacy public generation route using fal FLUX Schnell. Returns a data URL with the upstream image MIME type. Prompt limit 200 characters; deployment budget 30 seconds.",
"tags": [
"Generation"
],
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "\\S"
}
},
"required": [
"prompt"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"dataUrl": {
"type": "string",
"pattern": "^data:image\\/.+;base64,"
}
},
"required": [
"dataUrl"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"502": {
"description": "Generation or upstream failure",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"503": {
"description": "Service not configured",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}Photo matches
POST/api/matchFind punks resembling a photo
Streams analysis, results, optional market data and a saved-match edit token. Each SSE data line contains one JSON MatchEvent followed by two newlines. Keep editToken for subsequent edits/deletion. Authentication is optional and associates the saved match with a user. Images: JPEG/PNG/GIF/WebP, at most 10 MB decoded; body limit 15 MB. Duration budget 120 seconds. Errors after streaming begins are type=error events within HTTP 200.
Access: Optional authentication or SupabaseBearer
Request and response schemas
{
"operationId": "matchPhoto",
"summary": "Find punks resembling a photo",
"description": "Streams analysis, results, optional market data and a saved-match edit token. Each SSE data line contains one JSON MatchEvent followed by two newlines. Keep editToken for subsequent edits/deletion. Authentication is optional and associates the saved match with a user. Images: JPEG/PNG/GIF/WebP, at most 10 MB decoded; body limit 15 MB. Duration budget 120 seconds. Errors after streaming begins are type=error events within HTTP 200.",
"tags": [
"Photo matches"
],
"security": [
{},
{
"SupabaseBearer": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"image": {
"type": "string",
"pattern": "^data:image\\/(jpeg|png|gif|webp);base64,.+$"
},
"photoBlur": {
"type": "string"
},
"photoAspectRatio": {
"type": "number"
},
"includeMarketData": {
"default": true,
"type": "boolean"
}
},
"required": [
"image"
]
}
}
}
},
"responses": {
"200": {
"description": "SSE stream; schema describes one decoded data payload.",
"content": {
"text/event-stream": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "step"
},
"step": {
"type": "string",
"enum": [
"start",
"thinking",
"tool_call",
"tool_result"
]
},
"message": {
"type": "string"
},
"tool": {
"type": "string"
},
"input": {
"description": "Agent tool-call arguments, present for find_matching_punks.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"type",
"step",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "result"
},
"data": {
"type": "object",
"properties": {
"matches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tokenId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"matchPercent": {
"type": "number"
},
"explanation": {
"type": "string"
},
"nickname": {
"type": "string"
},
"traitsId": {
"type": "string"
},
"traits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"slug",
"name",
"category"
],
"additionalProperties": {}
}
}
},
"required": [
"tokenId",
"matchPercent",
"explanation",
"nickname",
"traits"
],
"additionalProperties": {}
}
}
},
"required": [
"matches"
],
"additionalProperties": false
}
},
"required": [
"type",
"data"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "market_data"
},
"data": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"market": {
"type": "object",
"properties": {
"ownerAddress": {
"type": "string"
},
"ownerEns": {
"type": "string"
},
"ownerLabel": {
"type": "string"
},
"isContract": {
"type": "boolean"
},
"isForSale": {
"type": "boolean"
},
"hasBid": {
"type": "boolean"
},
"wrapped": {
"type": "boolean"
}
},
"required": [
"isContract",
"isForSale",
"hasBid",
"wrapped"
],
"additionalProperties": false
},
"holder": {
"anyOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"bio": {
"type": "string"
},
"links": {
"type": "array",
"items": {
"type": "string"
}
},
"projectCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"name"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"market",
"holder"
],
"additionalProperties": false
}
}
},
"required": [
"type",
"data"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "match_saved"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"editToken": {
"type": "string"
}
},
"required": [
"id",
"editToken"
],
"additionalProperties": false
}
},
"required": [
"type",
"data"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "error"
},
"message": {
"type": "string"
}
},
"required": [
"type",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "timing"
},
"durationMs": {
"type": "number"
}
},
"required": [
"type",
"durationMs"
],
"additionalProperties": false
}
]
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"413": {
"description": "Request or image too large",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/match/{id}Read a public photo match
Private matches return 403; missing IDs return 404.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| id * | path | id parameter |
Request and response schemas
{
"operationId": "getPhotoMatch",
"summary": "Read a public photo match",
"description": "Private matches return 403; missing IDs return 404.",
"tags": [
"Photo matches"
],
"security": [],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id parameter",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"photo_url": {
"type": "string"
},
"results": {
"description": "Persisted match results; historical rows may use an older result shape. New results follow PhotoMatch.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"market_data": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"market": {
"type": "object",
"properties": {
"ownerAddress": {
"type": "string"
},
"ownerEns": {
"type": "string"
},
"ownerLabel": {
"type": "string"
},
"isContract": {
"type": "boolean"
},
"isForSale": {
"type": "boolean"
},
"hasBid": {
"type": "boolean"
},
"wrapped": {
"type": "boolean"
}
},
"required": [
"isContract",
"isForSale",
"hasBid",
"wrapped"
],
"additionalProperties": false
},
"holder": {
"anyOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"bio": {
"type": "string"
},
"links": {
"type": "array",
"items": {
"type": "string"
}
},
"projectCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"name"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"market",
"holder"
],
"additionalProperties": false
}
},
{
"type": "null"
}
]
},
"is_public": {
"type": "boolean"
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"photo_url",
"results",
"market_data",
"is_public",
"created_at"
],
"additionalProperties": false
}
},
"required": [
"success",
"data"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Access denied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}PATCH/api/match/{id}Update match visibility or selection
The per-match editToken is required in the JSON body. It is returned by the match_saved SSE event. Omitted fields retain their values.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| id * | path | id parameter |
Request and response schemas
{
"operationId": "updatePhotoMatch",
"summary": "Update match visibility or selection",
"description": "The per-match editToken is required in the JSON body. It is returned by the match_saved SSE event. Omitted fields retain their values.",
"tags": [
"Photo matches"
],
"security": [],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id parameter",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"editToken": {
"type": "string",
"minLength": 1
},
"isPublic": {
"type": "boolean"
},
"selectedTokenId": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9999
},
{
"type": "null"
}
]
}
},
"required": [
"editToken"
]
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
}
},
"required": [
"success"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}DELETE/api/match/{id}Delete an owned match and its photo
Requires the match's edit token in x-edit-token.
Access: MatchEditToken
| Parameter | Location | Description |
|---|---|---|
| id * | path | id parameter |
Request and response schemas
{
"operationId": "deletePhotoMatch",
"summary": "Delete an owned match and its photo",
"description": "Requires the match's edit token in x-edit-token.",
"tags": [
"Photo matches"
],
"security": [
{
"MatchEditToken": []
}
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "id parameter",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
}
},
"required": [
"success"
],
"additionalProperties": false
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/matches/recentList public matches
Pages contain up to 20 recent public matches.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| page | query | page parameter |
Request and response schemas
{
"operationId": "listRecentMatches",
"summary": "List public matches",
"description": "Pages contain up to 20 recent public matches.",
"tags": [
"Photo matches"
],
"security": [],
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"description": "page parameter",
"schema": {
"default": 1,
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"matches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"photo_url": {
"type": "string"
},
"results": {
"description": "Persisted match results; historical rows may use an older result shape. New results follow PhotoMatch.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"photo_blur": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"selected_token_id": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9999
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"photo_url",
"results",
"photo_blur",
"selected_token_id"
],
"additionalProperties": false
}
},
"page": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"hasMore": {
"type": "boolean"
}
},
"required": [
"matches",
"page",
"hasMore"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}POST/api/matches/mineList matches using their edit tokens
matchTokens maps match IDs to edit tokens. Only matching tokens return rows. A missing or invalid map returns an empty array. Tokens are never returned.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "listOwnedMatches",
"summary": "List matches using their edit tokens",
"description": "matchTokens maps match IDs to edit tokens. Only matching tokens return rows. A missing or invalid map returns an empty array. Tokens are never returned.",
"tags": [
"Photo matches"
],
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"matchTokens": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"photo_url": {
"type": "string"
},
"results": {
"description": "Persisted match results; historical rows may use an older result shape. New results follow PhotoMatch.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"photo_blur": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"selected_token_id": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9999
},
{
"type": "null"
}
]
},
"is_public": {
"type": "boolean"
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"photo_url",
"results",
"photo_blur",
"selected_token_id",
"is_public",
"created_at"
],
"additionalProperties": false
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/matches/adminList matches as an administrator
Requires a Supabase access token whose user email is authorized as an admin. Returns up to 200 rows.
Access: SupabaseBearer
Request and response schemas
{
"operationId": "adminListMatches",
"summary": "List matches as an administrator",
"description": "Requires a Supabase access token whose user email is authorized as an admin. Returns up to 200 rows.",
"tags": [
"Photo matches"
],
"security": [
{
"SupabaseBearer": []
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"photo_url": {
"type": "string"
},
"results": {
"description": "Persisted match results; historical rows may use an older result shape. New results follow PhotoMatch.",
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
{
"type": "null"
}
]
},
"is_public": {
"type": "boolean"
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"photo_url",
"results",
"is_public",
"created_at"
],
"additionalProperties": false
}
}
}
}
},
"403": {
"description": "Access denied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}DELETE/api/matches/adminDelete a match as an administrator
Deletes the selected database row and photo using an authorized admin Supabase access token.
Access: SupabaseBearer
| Parameter | Location | Description |
|---|---|---|
| id * | query | id parameter |
Request and response schemas
{
"operationId": "adminDeleteMatch",
"summary": "Delete a match as an administrator",
"description": "Deletes the selected database row and photo using an authorized admin Supabase access token.",
"tags": [
"Photo matches"
],
"security": [
{
"SupabaseBearer": []
}
],
"parameters": [
{
"name": "id",
"in": "query",
"required": true,
"description": "id parameter",
"schema": {
"type": "string",
"minLength": 1
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
}
},
"required": [
"success"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"403": {
"description": "Access denied",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}Exports
GET/api/cardRender a punk card
Renders a card for canonical id or a composed trait string p. Canonical id takes precedence.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| id | query | id parameter |
| p | query | p parameter |
Request and response schemas
{
"operationId": "renderPunkCard",
"summary": "Render a punk card",
"description": "Renders a card for canonical id or a composed trait string p. Canonical id takes precedence.",
"tags": [
"Exports"
],
"security": [],
"parameters": [
{
"name": "id",
"in": "query",
"required": false,
"description": "id parameter",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
{
"name": "p",
"in": "query",
"required": false,
"description": "p parameter",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Rendered PNG image.",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/diptychsRender a deterministic diptych
The seed and punkId determine the composition. PNG is the default. SVG uses native sizing; size overrides the rendered size.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| seed | query | seed parameter |
| punkId | query | punkId parameter |
| format | query | format parameter |
| size | query | size parameter |
Request and response schemas
{
"operationId": "renderDiptych",
"summary": "Render a deterministic diptych",
"description": "The seed and punkId determine the composition. PNG is the default. SVG uses native sizing; size overrides the rendered size.",
"tags": [
"Exports"
],
"security": [],
"parameters": [
{
"name": "seed",
"in": "query",
"required": false,
"description": "seed parameter",
"schema": {
"type": "string"
}
},
{
"name": "punkId",
"in": "query",
"required": false,
"description": "punkId parameter",
"schema": {
"type": "string"
}
},
{
"name": "format",
"in": "query",
"required": false,
"description": "format parameter",
"schema": {
"default": "png",
"type": "string",
"enum": [
"png",
"svg"
]
}
},
{
"name": "size",
"in": "query",
"required": false,
"description": "size parameter",
"schema": {
"type": "number",
"exclusiveMinimum": 0
}
}
],
"responses": {
"200": {
"description": "PNG or SVG selected by format.",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/svg+xml": {
"schema": {
"type": "string"
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/ogExport a composed punk image or model
Canonical id takes precedence over trait string p. Supports additional serialized pixels and face pose. background=0 is transparent; otherwise supply a hex color without #. PNG defaults to 1024px. GLTF and USDZ contain voxel geometry. mode=download sets Content-Disposition.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| id | query | id parameter |
| p | query | Hyphen-separated canonical trait IDs. |
| pixels | query | Additional pixels serialized as x,y,hex entries separated by hyphens; see the editor's pixel serializer. |
| pose | query | JSON-serialized partial PunkFacePose, as emitted by the editor. |
| format | query | format parameter |
| mode | query | mode parameter |
| size | query | size parameter |
| width | query | width parameter |
| height | query | height parameter |
| background | query | background parameter |
| bgstart | query | bgstart parameter |
| bgend | query | bgend parameter |
Request and response schemas
{
"operationId": "exportPunk",
"summary": "Export a composed punk image or model",
"description": "Canonical id takes precedence over trait string p. Supports additional serialized pixels and face pose. background=0 is transparent; otherwise supply a hex color without #. PNG defaults to 1024px. GLTF and USDZ contain voxel geometry. mode=download sets Content-Disposition.",
"tags": [
"Exports"
],
"security": [],
"parameters": [
{
"name": "id",
"in": "query",
"required": false,
"description": "id parameter",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
{
"name": "p",
"in": "query",
"required": false,
"description": "Hyphen-separated canonical trait IDs.",
"schema": {
"description": "Hyphen-separated canonical trait IDs.",
"type": "string"
}
},
{
"name": "pixels",
"in": "query",
"required": false,
"description": "Additional pixels serialized as x,y,hex entries separated by hyphens; see the editor's pixel serializer.",
"schema": {
"description": "Additional pixels serialized as x,y,hex entries separated by hyphens; see the editor's pixel serializer.",
"type": "string"
}
},
{
"name": "pose",
"in": "query",
"required": false,
"description": "JSON-serialized partial PunkFacePose, as emitted by the editor.",
"schema": {
"description": "JSON-serialized partial PunkFacePose, as emitted by the editor.",
"type": "string"
}
},
{
"name": "format",
"in": "query",
"required": false,
"description": "format parameter",
"schema": {
"default": "png",
"type": "string",
"enum": [
"png",
"svg",
"json",
"gltf",
"usdz"
]
}
},
{
"name": "mode",
"in": "query",
"required": false,
"description": "mode parameter",
"schema": {
"default": "download",
"type": "string",
"enum": [
"render",
"download"
]
}
},
{
"name": "size",
"in": "query",
"required": false,
"description": "size parameter",
"schema": {
"default": 1024,
"type": "number",
"exclusiveMinimum": 0
}
},
{
"name": "width",
"in": "query",
"required": false,
"description": "width parameter",
"schema": {
"type": "number",
"exclusiveMinimum": 0
}
},
{
"name": "height",
"in": "query",
"required": false,
"description": "height parameter",
"schema": {
"type": "number",
"exclusiveMinimum": 0
}
},
{
"name": "background",
"in": "query",
"required": false,
"description": "background parameter",
"schema": {
"type": "string"
}
},
{
"name": "bgstart",
"in": "query",
"required": false,
"description": "bgstart parameter",
"schema": {
"type": "string"
}
},
{
"name": "bgend",
"in": "query",
"required": false,
"description": "bgend parameter",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Export selected by format.",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/svg+xml": {
"schema": {
"type": "string"
}
},
"model/vnd.usdz+zip": {
"schema": {
"type": "string",
"format": "binary"
}
},
"application/json": {
"schema": {
"type": "object",
"properties": {
"newCleanPixels": {
"type": "array",
"items": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"hex": {
"type": "string"
}
},
"required": [
"x",
"y",
"hex"
],
"additionalProperties": {}
}
},
"cleanPixels": {
"type": "array",
"items": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"hex": {
"type": "string"
}
},
"required": [
"x",
"y",
"hex"
],
"additionalProperties": {}
}
}
},
"required": [
"newCleanPixels",
"cleanPixels"
],
"additionalProperties": false
}
},
"model/gltf+json": {
"schema": {
"description": "glTF 2.0 document produced by Three.js GLTFExporter.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/qrpunksGenerate QR modules with punk artwork
Deterministic QR solver. bits is base64-encoded n*n module bytes. Optional colors.map is base64-encoded palette indices; palette entries are r,g,b strings. verified reports scanner verification. URL validation can reject unsupported payloads. Style numbers are clamped to their documented ranges.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| punk | query | punk parameter |
| seed | query | seed parameter |
| id | query | id parameter |
| url | query | Defaults to https://qrpunks.com/{punk}. |
| shading | query | shading parameter |
| fog | query | fog parameter |
| outline | query | outline parameter |
| color | query | color parameter |
| skin | query | skin parameter |
| light | query | light parameter |
| halo | query | halo parameter |
| sg | query | sg parameter |
| lg | query | lg parameter |
| rot | query | rot parameter |
Request and response schemas
{
"operationId": "createQrPunk",
"summary": "Generate QR modules with punk artwork",
"description": "Deterministic QR solver. bits is base64-encoded n*n module bytes. Optional colors.map is base64-encoded palette indices; palette entries are r,g,b strings. verified reports scanner verification. URL validation can reject unsupported payloads. Style numbers are clamped to their documented ranges.",
"tags": [
"Exports"
],
"security": [],
"parameters": [
{
"name": "punk",
"in": "query",
"required": false,
"description": "punk parameter",
"schema": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9999
}
},
{
"name": "seed",
"in": "query",
"required": false,
"description": "seed parameter",
"schema": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
{
"name": "id",
"in": "query",
"required": false,
"description": "id parameter",
"schema": {
"default": "0",
"type": "string",
"enum": [
"0",
"1"
]
}
},
{
"name": "url",
"in": "query",
"required": false,
"description": "Defaults to https://qrpunks.com/{punk}.",
"schema": {
"description": "Defaults to https://qrpunks.com/{punk}.",
"type": "string"
}
},
{
"name": "shading",
"in": "query",
"required": false,
"description": "shading parameter",
"schema": {
"type": "string",
"enum": [
"flat",
"flat-sep",
"dither"
]
}
},
{
"name": "fog",
"in": "query",
"required": false,
"description": "fog parameter",
"schema": {
"type": "number",
"minimum": 0,
"maximum": 100
}
},
{
"name": "outline",
"in": "query",
"required": false,
"description": "outline parameter",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
},
{
"name": "color",
"in": "query",
"required": false,
"description": "color parameter",
"schema": {
"type": "string",
"enum": [
"0",
"1"
]
}
},
{
"name": "skin",
"in": "query",
"required": false,
"description": "skin parameter",
"schema": {
"type": "string",
"enum": [
"grain",
"white"
]
}
},
{
"name": "light",
"in": "query",
"required": false,
"description": "light parameter",
"schema": {
"type": "string",
"enum": [
"grain",
"checker",
"white"
]
}
},
{
"name": "halo",
"in": "query",
"required": false,
"description": "halo parameter",
"schema": {
"type": "number",
"minimum": 0,
"maximum": 4
}
},
{
"name": "sg",
"in": "query",
"required": false,
"description": "sg parameter",
"schema": {
"type": "number",
"minimum": 0,
"maximum": 40
}
},
{
"name": "lg",
"in": "query",
"required": false,
"description": "lg parameter",
"schema": {
"type": "number",
"minimum": 0,
"maximum": 60
}
},
{
"name": "rot",
"in": "query",
"required": false,
"description": "rot parameter",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 3
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"n": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"rotation": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"version": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"verified": {
"type": "boolean"
},
"bits": {
"type": "string"
},
"colors": {
"type": "object",
"properties": {
"palette": {
"type": "array",
"items": {
"type": "string"
}
},
"map": {
"type": "string"
}
},
"required": [
"palette",
"map"
],
"additionalProperties": false
}
},
"required": [
"n",
"rotation",
"version",
"verified",
"bits"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}Legacy
GET/api/imgProxy an image URL
Legacy image proxy. Streams upstream bytes with the upstream Content-Type. Fetch failures return a text body with status 500.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| src * | query | src parameter |
Request and response schemas
{
"operationId": "proxyImage",
"summary": "Proxy an image URL",
"description": "Legacy image proxy. Streams upstream bytes with the upstream Content-Type. Fetch failures return a text body with status 500.",
"tags": [
"Legacy"
],
"security": [],
"parameters": [
{
"name": "src",
"in": "query",
"required": true,
"description": "src parameter",
"schema": {
"type": "string",
"format": "uri"
}
}
],
"responses": {
"200": {
"description": "Upstream image bytes and content type.",
"content": {
"image/*": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"500": {
"description": "Fetch error.",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/realGenerate a legacy illustrated portrait (deprecated)
Legacy paid generation via GET. New headless integrations should use POST /api/nakedpunks/generate. p is a composed trait ID string. The success includes an upstream URL and a PNG data URL; legacy errors have no stable shape.
Access: Public / route-specific body credentials
| Parameter | Location | Description |
|---|---|---|
| p * | query | p parameter |
Request and response schemas
{
"operationId": "generateLegacyPortrait",
"summary": "Generate a legacy illustrated portrait",
"description": "Legacy paid generation via GET. New headless integrations should use POST /api/nakedpunks/generate. p is a composed trait ID string. The success includes an upstream URL and a PNG data URL; legacy errors have no stable shape.",
"tags": [
"Legacy"
],
"security": [],
"deprecated": true,
"parameters": [
{
"name": "p",
"in": "query",
"required": true,
"description": "p parameter",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"image": {
"type": "string"
},
"base64Image": {
"type": "string"
}
},
"required": [
"image",
"base64Image"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Legacy serialized error object.",
"content": {
"application/json": {
"schema": {
"description": "Provider-owned JSON payload, forwarded without reshaping. Consult the upstream API for its action-specific schema.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/punkifyLegacy punkify stub (deprecated)
This route currently returns a fixed greeting and performs no generation.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "punkifyStub",
"summary": "Legacy punkify stub",
"description": "This route currently returns a fixed greeting and performs no generation.",
"tags": [
"Legacy"
],
"security": [],
"deprecated": true,
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"text": {
"type": "string",
"const": "hello world"
}
},
"required": [
"text"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}GET/api/multiverseLegacy multiverse stub (deprecated)
This route currently returns a fixed success flag.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "multiverseStub",
"summary": "Legacy multiverse stub",
"description": "This route currently returns a fixed success flag.",
"tags": [
"Legacy"
],
"security": [],
"deprecated": true,
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "boolean",
"const": true
}
},
"required": [
"response"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}Development
POST/api/local/advance-timeAdvance a development EVM clock
Development helper targeting NEXT_PUBLIC_RPC_LOCAL (defaults to localhost:8545). Calls evm_increaseTime then evm_mine. No route-level authentication is implemented. ok=true means requests completed; JSON-RPC error bodies are not inspected.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "advanceLocalTime",
"summary": "Advance a development EVM clock",
"description": "Development helper targeting NEXT_PUBLIC_RPC_LOCAL (defaults to localhost:8545). Calls evm_increaseTime then evm_mine. No route-level authentication is implemented. ok=true means requests completed; JSON-RPC error bodies are not inspected.",
"tags": [
"Development"
],
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"seconds": {
"default": 0,
"type": "number"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
}
},
"required": [
"ok"
],
"additionalProperties": false
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"success": {
"type": "boolean",
"const": false
},
"message": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
}
}
}
},
"x-runtime-validation": "legacy"
}Documentation
GET/api/openapi.jsonDownload the API contract
OpenAPI 3.1 generated from the checked-in Zod schemas. Contains every explicit /api route method; Next.js implicit HEAD and OPTIONS are not separately listed. x-runtime-validation distinguishes Zod-validated generation from legacy handlers documented without changing their parsers.
Access: Public / route-specific body credentials
Request and response schemas
{
"operationId": "getOpenApi",
"summary": "Download the API contract",
"description": "OpenAPI 3.1 generated from the checked-in Zod schemas. Contains every explicit /api route method; Next.js implicit HEAD and OPTIONS are not separately listed. x-runtime-validation distinguishes Zod-validated generation from legacy handlers documented without changing their parsers.",
"tags": [
"Documentation"
],
"security": [],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"description": "OpenAPI 3.1 document; see https://spec.openapis.org/oas/v3.1.0 for the full meta-schema.",
"type": "object",
"properties": {
"openapi": {
"type": "string",
"const": "3.1.0"
},
"info": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"version": {
"type": "string"
}
},
"required": [
"title",
"version"
],
"additionalProperties": {}
},
"paths": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
}
},
"required": [
"openapi",
"info",
"paths"
],
"additionalProperties": {}
}
}
}
}
},
"x-runtime-validation": "zod"
}Shared schemas and authentication schemes
{
"securitySchemes": {
"PunkGenCron": {
"type": "http",
"scheme": "bearer",
"description": "Operator-only CRON_SECRET configured in Vercel. Never expose to browsers or third-party API clients."
},
"PunkGenSession": {
"type": "apiKey",
"in": "cookie",
"name": "__Secure-punkgen.session_token",
"description": "Better Auth HttpOnly browser session. Local HTTP uses punkgen.session_token. Bootstrap via POST /api/punkgen/session; send Origin on cookie mutations."
},
"PunkGenKey": {
"type": "http",
"scheme": "bearer",
"description": "pg_ key bound to one creator. Agents obtain one with the OAuth 2.0 Device Authorization Grant (RFC 8628, discovery at /.well-known/oauth-authorization-server): scope punkgen:create creates private punks and reads the creator's history only. Operator-issued keys keep full creator access. Defaults to private generation. Never put it in browser code or model context."
},
"PunkApiKey": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "Server-side integration key configured as NAKEDPUNKS_API_KEY. Never expose it in browser code."
},
"SupabaseBearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Supabase access token. Admin routes also verify the user's admin role."
},
"MatchEditToken": {
"type": "apiKey",
"in": "header",
"name": "x-edit-token",
"description": "Per-match edit token received in match_saved."
}
},
"schemas": {
"OutfitRequest": {
"oneOf": [
{
"required": [
"punkId"
],
"not": {
"anyOf": [
{
"required": [
"imageDataUrl"
]
},
{
"required": [
"imageUrl"
]
}
]
}
},
{
"required": [
"imageDataUrl"
],
"not": {
"anyOf": [
{
"required": [
"punkId"
]
},
{
"required": [
"imageUrl"
]
}
]
}
},
{
"required": [
"imageUrl"
],
"not": {
"anyOf": [
{
"required": [
"punkId"
]
},
{
"required": [
"imageDataUrl"
]
}
]
}
}
],
"allOf": [
{
"if": {
"required": [
"canvas"
]
},
"then": {
"properties": {
"variant": {
"const": "auto"
}
}
}
},
{
"if": {
"required": [
"method"
],
"properties": {
"method": {
"const": "pixel-agent"
}
}
},
"then": {
"required": [
"punkId",
"variant"
],
"properties": {
"variant": {
"enum": [
"head",
"naked"
]
}
}
},
"else": {
"not": {
"required": [
"agent"
]
}
}
}
],
"type": "object",
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"maxLength": 2000,
"pattern": "\\S"
},
"punkId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"imageDataUrl": {
"description": "PNG data URL, at most 3 MB of decoded image bytes. Dimensions must not exceed 4096 by 4096.",
"type": "string",
"maxLength": 4202496,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+={0,2}$"
},
"imageUrl": {
"description": "Canonical https://punks.art/api/punks/{id}?format=png URL. Use one literal format=png parameter and unescaped alphanumeric query keys. Other hosts, credentials, protocols and redirects are refused.",
"type": "string",
"pattern": "^https:\\/\\/punks\\.art(?::443)?\\/api\\/punks\\/\\d{1,4}\\?(?:(?!format=)[A-Za-z][A-Za-z0-9]*=[^\\s&#]*&)*format=png(?:&(?!format=)[A-Za-z][A-Za-z0-9]*=[^\\s&#]*)*(?:#[^\\s]*)?$"
},
"engine": {
"default": "gpt25",
"type": "string",
"enum": [
"nano2",
"nano",
"gpt25",
"gpt",
"retro",
"pixellab"
]
},
"variant": {
"description": "head: head-only source and 24x24 grid. naked: full body and 32x32 grid. auto preserves legacy naked punkId sources and infers small uploaded grids.",
"default": "auto",
"type": "string",
"enum": [
"auto",
"head",
"naked"
]
},
"canvas": {
"description": "Optional custom output grid. Only allowed with variant=auto.",
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 256
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 256
}
},
"required": [
"width",
"height"
],
"additionalProperties": false
},
"removeBackground": {
"default": true,
"type": "boolean"
},
"quantize": {
"description": "false returns the provider PNG at its actual resolution; canvas still describes the requested pixel grid.",
"default": true,
"type": "boolean"
},
"kColors": {
"default": 32,
"type": "integer",
"minimum": 1,
"maximum": 48
},
"method": {
"description": "image: an image model edits the render and the result is snapped to the grid (engine, removeBackground, quantize and kColors apply). pixel-agent: a reasoning model writes every cell of the native grid and reviews its own renders; needs punkId and variant head or naked, and ignores the image options.",
"default": "image",
"type": "string",
"enum": [
"image",
"pixel-agent"
]
},
"agent": {
"description": "pixel-agent settings. Only allowed with method=pixel-agent; omitted fields use defaults.",
"type": "object",
"properties": {
"model": {
"description": "OpenAI Responses model that draws and reviews.",
"default": "gpt-6-astra",
"type": "string",
"enum": [
"gpt-6-astra",
"gpt-5.5",
"gpt-5.4"
]
},
"reasoningEffort": {
"default": "high",
"type": "string",
"enum": [
"low",
"medium",
"high",
"xhigh",
"max"
]
},
"iterations": {
"description": "Review rounds after the first valid drawing. Each round shows the model its own render. The loop also stops when the model reports done or the time budget runs out.",
"default": 1,
"type": "integer",
"minimum": 0,
"maximum": 8
},
"strategy": {
"description": "redraw: the model returns the complete canvas. layers: it removes source traits (head only) and paints new trait layers over the punk.",
"default": "redraw",
"type": "string",
"enum": [
"redraw",
"layers"
]
},
"format": {
"description": "How drawings are written in the context and in the output: palette rows, pixel coordinates or rect-only SVG.",
"default": "rows",
"type": "string",
"enum": [
"rows",
"coords",
"svg"
]
},
"library": {
"description": "Official trait pixels given as reference: none, the source punk's traits, every trait of its gender, or all traits.",
"default": "compatible",
"type": "string",
"enum": [
"none",
"source",
"compatible",
"all"
]
}
},
"additionalProperties": false
}
},
"required": [
"prompt"
]
},
"OutfitResponse": {
"type": "object",
"properties": {
"image": {
"description": "PNG data URL, at most 3 MB of decoded image bytes. Dimensions must not exceed 4096 by 4096.",
"type": "string",
"maxLength": 4202496,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+={0,2}$"
},
"width": {
"type": "integer",
"minimum": 1,
"maximum": 4096
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 4096
},
"method": {
"type": "string",
"enum": [
"image",
"pixel-agent"
]
},
"engine": {
"description": "Image engine; null for method=pixel-agent.",
"anyOf": [
{
"type": "string",
"enum": [
"nano2",
"nano",
"gpt25",
"gpt",
"retro",
"pixellab"
]
},
{
"type": "null"
}
]
},
"model": {
"type": "string",
"minLength": 1
},
"promptVersion": {
"type": "string",
"minLength": 1
},
"quantizerVersion": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"canvas": {
"anyOf": [
{
"description": "Exact output grid when quantize=true; also returned for client-side quantization.",
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 256
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 256
}
},
"required": [
"width",
"height"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"timings": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number",
"minimum": 0
}
},
"agent": {
"anyOf": [
{
"description": "Every turn of the pixel agent, for inspection and evaluation.",
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1
},
"settings": {
"type": "object",
"properties": {
"model": {
"description": "OpenAI Responses model that draws and reviews.",
"default": "gpt-6-astra",
"type": "string",
"enum": [
"gpt-6-astra",
"gpt-5.5",
"gpt-5.4"
]
},
"reasoningEffort": {
"default": "high",
"type": "string",
"enum": [
"low",
"medium",
"high",
"xhigh",
"max"
]
},
"iterations": {
"description": "Review rounds after the first valid drawing. Each round shows the model its own render. The loop also stops when the model reports done or the time budget runs out.",
"default": 1,
"type": "integer",
"minimum": 0,
"maximum": 8
},
"strategy": {
"description": "redraw: the model returns the complete canvas. layers: it removes source traits (head only) and paints new trait layers over the punk.",
"default": "redraw",
"type": "string",
"enum": [
"redraw",
"layers"
]
},
"format": {
"description": "How drawings are written in the context and in the output: palette rows, pixel coordinates or rect-only SVG.",
"default": "rows",
"type": "string",
"enum": [
"rows",
"coords",
"svg"
]
},
"library": {
"description": "Official trait pixels given as reference: none, the source punk's traits, every trait of its gender, or all traits.",
"default": "compatible",
"type": "string",
"enum": [
"none",
"source",
"compatible",
"all"
]
}
},
"required": [
"model",
"reasoningEffort",
"iterations",
"strategy",
"format",
"library"
],
"additionalProperties": false
},
"stopReason": {
"description": "done: the model approved its render. iterations: review rounds exhausted. deadline: another turn would not fit the time budget. invalid: repair turns exhausted after a valid drawing. token_budget: the allocated output-token budget is exhausted. provider_error: a recoverable provider failure ended review; the last valid drawing is returned and token usage covers successful responses only.",
"type": "string",
"enum": [
"done",
"iterations",
"deadline",
"invalid",
"provider_error",
"token_budget"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"kind": {
"type": "string",
"enum": [
"draft",
"review",
"repair"
]
},
"ms": {
"type": "number",
"minimum": 0
},
"valid": {
"type": "boolean"
},
"errors": {
"maxItems": 24,
"type": "array",
"items": {
"type": "string"
}
},
"critique": {
"type": "string",
"maxLength": 4000
},
"done": {
"type": "boolean"
},
"image": {
"description": "Native-size PNG of this turn's drawing; null when it failed validation.",
"anyOf": [
{
"description": "PNG data URL, at most 3 MB of decoded image bytes. Dimensions must not exceed 4096 by 4096.",
"type": "string",
"maxLength": 4202496,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+={0,2}$"
},
{
"type": "null"
}
]
},
"colors": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"changedCells": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"usage": {
"type": "object",
"properties": {
"inputTokens": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"cachedTokens": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"outputTokens": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"reasoningTokens": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"inputTokens",
"cachedTokens",
"outputTokens",
"reasoningTokens"
],
"additionalProperties": false
}
},
"required": [
"index",
"kind",
"ms",
"valid",
"errors",
"critique",
"done",
"image",
"colors",
"changedCells",
"usage"
],
"additionalProperties": false
}
},
"usage": {
"type": "object",
"properties": {
"inputTokens": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"cachedTokens": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"outputTokens": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"reasoningTokens": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"inputTokens",
"cachedTokens",
"outputTokens",
"reasoningTokens"
],
"additionalProperties": false
}
},
"required": [
"version",
"settings",
"stopReason",
"steps",
"usage"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"image",
"width",
"height",
"method",
"engine",
"model",
"promptVersion",
"quantizerVersion",
"canvas",
"timings",
"agent"
],
"additionalProperties": false
},
"OutfitError": {
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
},
"JudgeRequest": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"punkId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"variant": {
"type": "string",
"enum": [
"head",
"naked"
]
},
"image": {
"description": "Generated punk to score. Omit it to score the unchanged source: the negative control, which must fail adherence.",
"type": "string",
"maxLength": 4202496,
"pattern": "^data:image\\/png;base64,[A-Za-z0-9+/]+={0,2}$"
}
},
"required": [
"prompt",
"punkId",
"variant"
],
"additionalProperties": false
},
"JudgeResponse": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1
},
"model": {
"type": "string",
"minLength": 1
},
"control": {
"description": "True when no image was sent and the source was judged against itself.",
"type": "boolean"
},
"controlPassed": {
"description": "For a control, whether the judge saw no change and adherence stayed at or below 3. A failed control means the scores are not trustworthy. Null otherwise.",
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"scores": {
"allOf": [
{
"if": {
"properties": {
"changeVisible": {
"const": false
}
},
"required": [
"changeVisible"
]
},
"then": {
"properties": {
"adherence": {
"const": 0
}
}
}
}
],
"type": "object",
"properties": {
"changeVisible": {
"description": "Whether RESULT shows the requested change at all, answered before any score.",
"type": "boolean"
},
"adherence": {
"description": "How well the requested change is shown. 0 whenever changeVisible is false.",
"type": "integer",
"minimum": 0,
"maximum": 10
},
"identity": {
"description": "The source face, skin, eyes, other traits and framing are kept, except what the request must change.",
"type": "integer",
"minimum": 0,
"maximum": 10
},
"style": {
"description": "Authentic CryptoPunks art: hard square pixels, flat colors, one-pixel dark outlines.",
"type": "integer",
"minimum": 0,
"maximum": 10
},
"cleanliness": {
"description": "No stray pixels, broken outlines, holes or misplaced shapes.",
"type": "integer",
"minimum": 0,
"maximum": 10
},
"overall": {
"description": "Quality as a finished punk for this request.",
"type": "integer",
"minimum": 0,
"maximum": 10
},
"notes": {
"type": "string",
"maxLength": 600
}
},
"required": [
"changeVisible",
"adherence",
"identity",
"style",
"cleanliness",
"overall",
"notes"
],
"additionalProperties": false
},
"ms": {
"type": "number",
"minimum": 0
}
},
"required": [
"version",
"model",
"control",
"controlPassed",
"scores",
"ms"
],
"additionalProperties": false
},
"Canvas": {
"description": "Exact output grid when quantize=true; also returned for client-side quantization.",
"type": "object",
"properties": {
"width": {
"type": "integer",
"minimum": 1,
"maximum": 256
},
"height": {
"type": "integer",
"minimum": 1,
"maximum": 256
}
},
"required": [
"width",
"height"
],
"additionalProperties": false
},
"MatchEvent": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "step"
},
"step": {
"type": "string",
"enum": [
"start",
"thinking",
"tool_call",
"tool_result"
]
},
"message": {
"type": "string"
},
"tool": {
"type": "string"
},
"input": {
"description": "Agent tool-call arguments, present for find_matching_punks.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"type",
"step",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "result"
},
"data": {
"type": "object",
"properties": {
"matches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tokenId": {
"type": "integer",
"minimum": 0,
"maximum": 9999
},
"matchPercent": {
"type": "number"
},
"explanation": {
"type": "string"
},
"nickname": {
"type": "string"
},
"traitsId": {
"type": "string"
},
"traits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"slug",
"name",
"category"
],
"additionalProperties": {}
}
}
},
"required": [
"tokenId",
"matchPercent",
"explanation",
"nickname",
"traits"
],
"additionalProperties": {}
}
}
},
"required": [
"matches"
],
"additionalProperties": false
}
},
"required": [
"type",
"data"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "market_data"
},
"data": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"market": {
"type": "object",
"properties": {
"ownerAddress": {
"type": "string"
},
"ownerEns": {
"type": "string"
},
"ownerLabel": {
"type": "string"
},
"isContract": {
"type": "boolean"
},
"isForSale": {
"type": "boolean"
},
"hasBid": {
"type": "boolean"
},
"wrapped": {
"type": "boolean"
}
},
"required": [
"isContract",
"isForSale",
"hasBid",
"wrapped"
],
"additionalProperties": false
},
"holder": {
"anyOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"bio": {
"type": "string"
},
"links": {
"type": "array",
"items": {
"type": "string"
}
},
"projectCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"name"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"market",
"holder"
],
"additionalProperties": false
}
}
},
"required": [
"type",
"data"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "match_saved"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"editToken": {
"type": "string"
}
},
"required": [
"id",
"editToken"
],
"additionalProperties": false
}
},
"required": [
"type",
"data"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "error"
},
"message": {
"type": "string"
}
},
"required": [
"type",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "timing"
},
"durationMs": {
"type": "number"
}
},
"required": [
"type",
"durationMs"
],
"additionalProperties": false
}
]
},
"ListingEvent": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"cached",
"complete"
]
},
"listings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tokenId": {
"type": "string"
},
"price": {
"description": "Display value in currency units; exact canonical value is payment.raw when provided.",
"type": "number"
},
"payment": {
"type": "object",
"properties": {
"raw": {
"type": "string"
},
"token": {
"type": "string"
},
"symbol": {
"type": "string"
},
"decimals": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"chainId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"raw",
"token",
"symbol",
"decimals",
"chainId"
],
"additionalProperties": false
},
"currency": {
"type": "string"
},
"maker": {
"type": "string"
},
"expirationTime": {
"type": "number"
}
},
"required": [
"tokenId",
"price",
"currency",
"maker"
],
"additionalProperties": false
}
},
"count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"type",
"listings",
"count"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "progress"
},
"percent": {
"type": "number"
},
"batchesCompleted": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"totalBatches": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"listingsFound": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"type",
"percent",
"batchesCompleted",
"totalBatches",
"listingsFound"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "string"
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}
}
}