# Artifacts

> The Artifacts operations of the Hub REST API (3 operations).

URL: https://docs.synap.live/docs/reference/hub-api/artifacts · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## GET /artifacts

List artifacts visible to the caller

Workspace rows follow membership; NULL-workspace (pod-personal) rows keep the caller's owner floor. `workspaceId` NARROWS the lens — omit it to list every artifact the caller can see, which is the only way to reach a pod-personal session's outputs.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `workspaceId` | query | string |  |  |
| `state` | query | "working" \| "kept" \| "swept" \| "all" |  |  |
| `placement` | query | "desk" \| "home" \| "sidebar" \| "library" \| "all" |  |  |
| `sessionId` | query | string |  |  |
| `limit` | query | integer |  |  |

Responses:

- `200`: Artifacts
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## POST /artifacts

Create an artifact

IS/agent creates an artifact. originKind defaults to 'agent' for hub-authenticated requests. Goes through the governance membrane — may return { status: 'proposed', proposalId } for agent callers.

Request body (`application/json`): object

| Field | Type | Required | Description |
|---|---|---|---|
| `workspaceId` | string | yes |  |
| `userId` | string | yes |  |
| `kind` | "view" \| "cell" \| "document" \| "entity" \| "url" \| "automation" \| "playbook" | yes |  |
| `refId` | string |  |  |
| `cellKey` | string |  |  |
| `props` | object |  |  |
| `title` | string | yes |  |
| `originKind` | "user" \| "agent" \| "deeplink" \| "system" |  |  |
| `actorId` | string |  |  |
| `sessionId` | string |  |  |
| `placement` | "desk" \| "home" \| "sidebar" \| "library" |  |  |
| `agentUserId` | string |  |  |
| `reasoning` | string |  |  |

Responses:

- `200`: Created artifact or proposal
- `400`: Bad request
- `403`: Forbidden
- `500`: Internal error

## PATCH /artifacts/:id

Update artifact state / placement

Loads the row by id, verifies the caller's workspace membership against the row's workspace, then gates through the governance membrane.

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

Request body (`application/json`): object

| Field | Type | Required | Description |
|---|---|---|---|
| `state` | "working" \| "kept" \| "swept" |  |  |
| `placement` | "desk" \| "home" \| "sidebar" \| "library" |  |  |
| `agentUserId` | string |  |  |
| `reasoning` | string |  |  |

Responses:

- `200`: Updated artifact or proposal
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `500`: Internal error