Skip to main content

Artifacts

Read the Documents, Mockups, Images and Videos the agent wrote in a chat session. List them to get their ids, then read one for its content. Artifacts stay readable after the session ends, and reading them never wakes a sandbox.

MethodPathDescription
GET/api/projects/{projectId}/chat-sessions/{sessionId}/artifactsList the session's artifacts, most recently changed first. Rows only: a body or a file url comes from reading one.
POST/api/projects/{projectId}/chat-sessions/{sessionId}/artifactsCopy one of your Lead's Prototypes onto a Backlog session as its own artifacts: the variant named, or every variant.
GET/api/projects/{projectId}/chat-sessions/{sessionId}/artifacts/{artifactId}Read one artifact of the session: a markdown or html one carries its body, an image or a video a presigned url, its media type and its size.

Kinds​

kindIn the appWhere the content is
markdownDocumentMarkdown text in body.
htmlMockupA self-contained HTML page in body.
imageImageA file behind url, with its mediaType and byteSize.
videoVideoA file behind url, with its mediaType and byteSize.

The field a kind does not use comes back null.

List artifacts​

GET .../chat-sessions/{sessionId}/artifacts lists a session's artifacts, most recently changed first, without their content.

curl -s "https://app.kosuke.ai/api/projects/$PROJECT_ID/chat-sessions/$SESSION_ID/artifacts" \
  -H "Authorization: Bearer $KOSUKE_API_KEY"
{
  "data": {
    "artifacts": [
      {
        "id": "e2c79a10-5b4d-4f8e-a3c6-91d0b7f2e845",
        "slug": "checkout-investigation",
        "title": "Why checkout fails on Safari",
        "kind": "markdown",
        "version": 2,
        "createdAt": "2026-09-30T08:02:13.415Z",
        "updatedAt": "2026-09-30T08:47:55.902Z"
      }
    ]
  }
}

slug names the artifact within its session. When the agent writes the same slug again, it replaces the artifact and version goes up by one. A report that declares its own version in the page, such as the QA Report and the review report, gets that version instead. Only the current version is kept. The CLI command is kosuke sessions artifacts list <projectId> <sessionId>.

Read one artifact​

GET .../chat-sessions/{sessionId}/artifacts/{artifactId} returns the artifact with its content. A Document or a Mockup carries its text:

{
  "data": {
    "id": "e2c79a10-5b4d-4f8e-a3c6-91d0b7f2e845",
    "slug": "checkout-investigation",
    "title": "Why checkout fails on Safari",
    "kind": "markdown",
    "version": 2,
    "createdAt": "2026-09-30T08:02:13.415Z",
    "updatedAt": "2026-09-30T08:47:55.902Z",
    "body": "# Why checkout fails on Safari\n\nThe payment form posts before…",
    "url": null,
    "mediaType": null,
    "byteSize": null
  }
}

An Image or a Video carries a download URL instead:

{
  "data": {
    "id": "7d3f0b62-c18e-4a95-b2d7-4e6a8c1f09b3",
    "slug": "settings-dark-mode",
    "title": "Settings page in dark mode",
    "kind": "image",
    "version": 1,
    "createdAt": "2026-09-30T09:21:40.118Z",
    "updatedAt": "2026-09-30T09:21:40.118Z",
    "body": null,
    "url": "https://…",
    "mediaType": "image/png",
    "byteSize": 184233
  }
}

The download URL works for 24 hours. Read the artifact again for a fresh one. Request an artifact through its own session, because any other session answers 404. The CLI command is kosuke sessions artifacts get <projectId> <sessionId> <artifactId>.

Who can read them​

Any member of the workspace can read the artifacts of any session in it. A share link also opens a session's artifacts to people outside the workspace, as Previews describes.

The agent writes artifacts during a turn. To get one, ask for it in a message, such as "Write your findings up as a document."

Errors​

StatusCodeWhen
404NOT_FOUNDThe project, session or artifact does not exist, or the artifact belongs to another session.

Responses and errors has the full table.

Next steps​