v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Create an artifact

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.

post/api/v1/users/{user}/artifacts

Request body

artifactobject required

Object containing the attributes for the new artifact.

Example request

{
  "artifact": {}
}

Response

Successful response

agentstring

ID of the agent that produced this artifact (agt_...). null if not agent-produced.

content_typestring

MIME type of the current version's file, e.g. "text/csv" or "image/png". null if no file is attached.

created_atstring date-time

When the artifact was first created (ISO 8601).

current_versionstring

ID of the current (latest published) artifact version (artv_...). null if no version has been published.

descriptionstring

Optional longer description of the artifact's contents or purpose. null if not set.

filestring

Storage file ID for the current version (fil_...). null if no file is attached.

file_namestring

Original filename of the current version's file, e.g. "output.csv". null if no file is attached.

file_urlstring

Short-lived signed URL for downloading the current version's file. null if no file is attached.

idstring required

Artifact ID (art_...).

namestring

Human-readable name for the artifact, e.g. "Q2 Report". null if not set.

orgstring

ID of the organization this artifact belongs to (org_...).

sandboxstring

Identifier of the sandbox environment associated with this artifact. null if not sandbox-scoped.

teamstring

ID of the team that owns this artifact (tea_...). null if not team-scoped.

threadstring

ID of the thread in which this artifact was created (thr_...). null if not thread-scoped.

updated_atstring date-time

When the artifact record was last modified (ISO 8601).

userstring

ID of the user who created this artifact (usr_...). null if not user-scoped.

versioninteger

Current version number of the artifact. Increments each time a new version is published.

Example response

{
  "agent": "agt_0aBcDeFgHiJkLmNoPqRsTu",
  "content_type": "application/json",
  "created_at": "2024-01-01T00:00:00Z",
  "current_version": "afv_0aBcDeFgHiJkLmNoPqRsTu",
  "description": "An example description.",
  "file": "string",
  "file_name": "Example Name",
  "file_url": "https://example.com",
  "id": "art_0aBcDeFgHiJkLmNoPqRsTu",
  "image_source": {
    "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
    "height": 600,
    "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
    "mime_type": "application/json",
    "refresh_url": "https://example.com",
    "url": "https://example.com",
    "width": 800
  },
  "name": "Example Name",
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "sandbox": "string",
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu",
  "version": 1
}