> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifacts

> Register and fetch OrgX artifacts and entity-linked outputs.

Artifacts are durable work products created by agents or humans: briefs,
plans, PR summaries, research, runbooks, campaign drafts, decision packets, and
other approved outputs.

## Register an Artifact

```http theme={"dark"}
POST /api/client/artifacts
```

```bash theme={"dark"}
curl https://useorgx.com/api/client/artifacts \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "task",
    "entity_id": "2f7b2f47-2d7a-4d65-81d0-5c4b0f9b7e01",
    "name": "Launch brief",
    "artifact_type": "brief",
    "artifact_url": "https://example.com/launch-brief",
    "status": "approved"
  }'
```

The artifact registration contract accepts workspace entity IDs for
`project`, `initiative`, `workstream`, `milestone`, `task`, and `decision`.
Send either `artifact_url` or `external_url`.

### Request Fields

| Field              | Type   | Required    | Description                                                                         |
| ------------------ | ------ | ----------- | ----------------------------------------------------------------------------------- |
| `entity_type`      | string | Yes         | Owning entity type.                                                                 |
| `entity_id`        | UUID   | Yes         | Owning OrgX entity ID.                                                              |
| `initiative_id`    | UUID   | No          | Related initiative ID.                                                              |
| `name`             | string | Yes         | Artifact title.                                                                     |
| `artifact_type`    | string | Yes         | Integration-defined artifact kind.                                                  |
| `artifact_url`     | string | Conditional | URL to the artifact. Required when `external_url` is omitted.                       |
| `external_url`     | string | Conditional | External URL. Required when `artifact_url` is omitted.                              |
| `preview_markdown` | string | No          | Short preview content for review surfaces.                                          |
| `status`           | string | No          | `draft`, `in_review`, `approved`, `changes_requested`, `superseded`, or `archived`. |
| `metadata`         | object | No          | Integration metadata.                                                               |

## Get an Artifact

```http theme={"dark"}
GET /api/client/artifacts/{artifactId}
```

```bash theme={"dark"}
curl https://useorgx.com/api/client/artifacts/6ed5e8b1-5e4d-4dcb-8a7f-9f4f5482ecb1 \
  -H "Authorization: Bearer $ORGX_API_KEY"
```

## List Artifacts by Entity

```http theme={"dark"}
GET /api/client/artifacts/by-entity
```

```bash theme={"dark"}
curl "https://useorgx.com/api/client/artifacts/by-entity?entity_type=task&entity_id=2f7b2f47-2d7a-4d65-81d0-5c4b0f9b7e01&limit=10" \
  -H "Authorization: Bearer $ORGX_API_KEY"
```

## Response Shape

Artifact responses are JSON and include workspace-scoped metadata, status, and
content references when available.

```json theme={"dark"}
{
  "ok": true,
  "artifact": {
    "id": "6ed5e8b1-5e4d-4dcb-8a7f-9f4f5482ecb1",
    "title": "Launch brief",
    "artifact_type": "brief",
    "status": "approved",
    "artifact_url": "https://example.com/launch-brief"
  },
  "contract_version": "2026-02-18"
}
```

## Approval and Shipping

Approval-sensitive artifact actions are MCP-first in Public Preview. Use:

* `orgx_decide`
* `orgx_decide`
* `orgx_decide`

REST write endpoints for artifact lifecycle actions will be documented as they
graduate.