Artifacts
Read what runs produced. For what an artifact is — classes, statuses, provenance — see Artifacts.
GET /v1/artifacts
List artifacts, newest first, with filters and full-text search.
curl -s "https://api.esy.com/v1/artifacts?workspaceId=$WS&class=visual&status=ready&limit=20" \
-H "Authorization: Bearer $ESY_API_KEY"Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
workspaceId | uuid | optional | Limit to one workspace. |
projectId | uuid | optional | Limit to one project. |
runId | string | optional | Everything one run produced. |
templateId | string | optional | Everything one workflow produced. |
class | enum | optional | visual, research, video, knowledge. |
artifactType | string | optional | For example illustration, coloring-page, clip-art. |
status | string | optional | ready, review, approved, rejected, … |
q | string | optional | Free-text search over titles and metadata. |
createdAfter / createdBefore | datetime | optional | ISO-8601 bounds. |
workerId | string | optional | Produced by one worker. |
includeStage | boolean | optional | Include intermediate stage artifacts emitted mid-run. Off by default. |
offset / limit | integer | optional | Pagination. limit is capped at 100. |
GET /v1/artifacts/{artifact_id}
Read one artifact with its content, QA record, and cost ledger.
{
"id": "artifact-5a6a9501",
"runId": "run-fb0677b2",
"templateId": "generate-illustration",
"title": "Lighthouse at Dusk with Storm Rolling In",
"status": "ready",
"artifactClass": "visual",
"artifactType": "illustration",
"version": 1,
"content": {
"type": "image",
"url": "https://images.esy.com/artifacts/illustration/run-fb0677b2/image.webp",
"mimeType": "image/webp",
"model": "gpt-image-2.5-sunburst",
"transparencyMechanism": "…"
},
"qa": { "status": "pending_review", "checks": [ … ] },
"costLedger": [ … ]
}content.url is the file, served from images.esy.com. Everything under content beyond url and mimeType depends on the artifact type — treat unknown keys as additive.
GET /v1/artifacts/{artifact_id}/family
Walk the pack an artifact belongs to — its plan, its siblings, and its cover.
Artifacts made by a Generation Order that carried a planArtifactId form a family. Call this from any member to get the rest.
GET /v1/artifacts/counts
Artifact counts bucketed over time, for charts.
Accepts the same filters as the list, plus periodGranularity to choose the bucket size.
POST /v1/artifacts/{artifact_id}/comments
Attach a comment to an artifact.
curl -X POST https://api.esy.com/v1/artifacts/artifact-5a6a9501/comments \
-H "Authorization: Bearer $ESY_API_KEY" \
-H "content-type: application/json" \
-d '{ "body": "Crop tighter on the lighthouse for the pack cover." }'DELETE /v1/artifacts/{artifact_id}
Retract an artifact.