---
title: "Create an artifact"
method: POST
path: "/api/v1/users/{user}/artifacts"
---

# Create an artifact

`POST /api/v1/users/{user}/artifacts`

Creates a new artifact and stores its file content. A file payload is required;
supply it via the `artifact.file_content` (Base64-encoded), `artifact.file_name`,
and `artifact.file_content_type` fields. The artifact is scoped to the owner
resolved from the request context — either a team or a user.

Optionally associate the artifact with an existing thread or agent by passing
`artifact.thread_id` or `artifact.agent_id`. Returns 201 with the created
artifact on success.

## Request body

- object
  - `artifact` object, required — Object containing the attributes for the new artifact.

## Response `200`

Successful response

- Artifact — A versioned artifact produced or managed by an agent, such as a generated file, report, or code output.
  - `agent` string — ID of the agent that produced this artifact (`agt_...`). `null` if not agent-produced.
  - `content_type` string — MIME type of the current version's file, e.g. `"text/csv"` or `"image/png"`. `null` if no file is attached.
  - `created_at` string, date-time — When the artifact was first created (ISO 8601).
  - `current_version` string — ID of the current (latest published) artifact version (`artv_...`). `null` if no version has been published.
  - `description` string — Optional longer description of the artifact's contents or purpose. `null` if not set.
  - `file` string — Storage file ID for the current version (`fil_...`). `null` if no file is attached.
  - `file_name` string — Original filename of the current version's file, e.g. `"output.csv"`. `null` if no file is attached.
  - `file_url` string — Short-lived signed URL for downloading the current version's file. `null` if no file is attached.
  - `id` string, required — Artifact ID (`art_...`).
  - `image_source` ImageSource — Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.
    - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
    - `height` integer — Height of the image in pixels. `null` if not known.
    - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
    - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
    - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
    - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
    - `width` integer — Width of the image in pixels. `null` if not known.
  - `name` string — Human-readable name for the artifact, e.g. `"Q2 Report"`. `null` if not set.
  - `org` string — ID of the organization this artifact belongs to (`org_...`).
  - `sandbox` string — Identifier of the sandbox environment associated with this artifact. `null` if not sandbox-scoped.
  - `team` string — ID of the team that owns this artifact (`tea_...`). `null` if not team-scoped.
  - `thread` string — ID of the thread in which this artifact was created (`thr_...`). `null` if not thread-scoped.
  - `updated_at` string, date-time — When the artifact record was last modified (ISO 8601).
  - `user` string — ID of the user who created this artifact (`usr_...`). `null` if not user-scoped.
  - `version` integer — Current version number of the artifact. Increments each time a new version is published.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `422` — Validation error

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)