---
title: "Attach artifacts to an agent session"
method: POST
path: "/agentSession/{id}/artifacts"
tags: ["AgentSession"]
---

# Attach artifacts to an agent session

`POST /agentSession/{id}/artifacts`

Attaches artifacts to an agent session without writing a message. Additive: each supplied artifact is merged into the session's `related_artifacts` under the same identity rule the message endpoints use — inline artifacts by `name`, remote artifacts by `entity_kind` + `entity_id` — with the supplied artifact winning on a collision and everything else left untouched. Re-sending the same artifact is therefore idempotent. Returns the session's merged artifact list, not the whole session. Use this, rather than the message endpoints, to record a link (a deployment event, a test run, another agent session) onto a session that is not otherwise being written to.

## Path parameters

- `id` string, required

## Request body

- UpsertAgentSessionArtifactsRequest — Request to attach artifacts to an agent session without writing a message. Object-wrapped rather than a bare array because Swagger Inflector cannot bind a top-level array of a polymorphic schema to its generated model and degrades it to raw JSON nodes.
  - `related_artifacts` Artifact[], required — The artifacts to attach. MERGED into the session's existing artifacts: inline artifacts dedupe by `name`, remote artifacts by `entity_kind` + `entity_id`, and the ones in this request win on a collision, so re-sending one is idempotent and nothing already on the session is dropped.
    - union
      - BaseArtifact
        - `artifact_type` 'inline' | 'remote', required — The type of artifact
      - BaseArtifact
        - `artifact_type` 'inline' | 'remote', required — The type of artifact

## Response `200`

The session's related artifacts after the merge

- AgentSessionArtifacts — An agent session's artifacts, without the rest of the session.
  - `related_artifacts` Artifact[], required — The session's complete artifact list after the merge.
    - union
      - BaseArtifact
        - `artifact_type` 'inline' | 'remote', required — The type of artifact
      - BaseArtifact
        - `artifact_type` 'inline' | 'remote', required — The type of artifact
  - `warning` string — Present when the write succeeded but did not store everything it was sent — today, only when the session is already at its related-artifact limit, where excess incoming artifacts are dropped rather than failing a write that may also carry messages.

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `404` — Entity not found
- `default` — Unknown error

## Changes

- **2026-09-18** `daadc556ff0d` — 1 warning, 1 info
  - added the new `PlanRun` enum value to the `related_artifacts/items/anyOf[#/components/schemas/RemoteArtifact]/entity_kind` response property for the response status `200`
  - added the new `PlanRun` enum value to the request property `related_artifacts/items/anyOf[#/components/schemas/RemoteArtifact]/entity_kind`
- **2026-09-18** `e5b6d95d50a1` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/mabl/apis/mabl-api/changes/agentSession/:id/artifacts/post.md)

---

[API](https://skmtc.dev/mabl/apis/mabl-api.md) · [All operations](https://skmtc.dev/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mabl/apis/mabl-api/revisions/24dd8c2933df?raw)