> ## 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 work against an OrgX entity, read it back, and keep machine verification separate from human acceptance.

An artifact is a produced deliverable: a document, pull request, design, or
report. It belongs to one OrgX entity and carries its own type, location, and
lifecycle status.

The API keeps two claims separate:

* A machine can record that work was produced or verified.
* A person records acceptance in Mission Control.

## Create an artifact

`POST /api/v1/artifacts` accepts an API key. The target entity determines the
workspace, so the request does not need a separate workspace field.

Every create requires an `Idempotency-Key`. Use one stable key for one logical
artifact and reuse it when retrying a timeout. OrgX returns the stored artifact
with `meta.duplicate: true` on a replay. Reusing that key with a different
payload returns `409 idempotency_key_conflict`.

`artifact_type` must be a registered type code. List the available codes first:

```bash theme={"dark"}
curl https://useorgx.com/api/v1/artifact-types
```

Then create the artifact:

```bash theme={"dark"}
curl https://useorgx.com/api/v1/artifacts \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H "Idempotency-Key: launch-plan-review-artifact-001" \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "initiative",
    "entity_id": "22222222-2222-4222-8222-222222222222",
    "name": "Launch plan review notes",
    "artifact_type": "shared.project_handbook",
    "external_url": "https://example.com/review.md"
  }'
```

The response contains the artifact in `data` and request-independent contract
metadata in `meta`:

```json theme={"dark"}
{
  "data": {
    "id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "workspace_id": "11111111-1111-4111-8111-111111111111",
    "entity_type": "initiative",
    "entity_id": "22222222-2222-4222-8222-222222222222",
    "name": "Launch plan review notes",
    "artifact_type": "shared.project_handbook",
    "artifact_url": "https://example.com/review.md",
    "status": "draft",
    "created_at": "2026-08-19T15:10:00.000Z",
    "updated_at": "2026-08-19T15:10:00.000Z"
  },
  "meta": {
    "apiVersion": "1",
    "artifactTypeFallback": false,
    "effectiveArtifactType": "shared.project_handbook",
    "duplicate": false
  }
}
```

If the same request is replayed with the same key, the status is `200` and the
artifact is unchanged:

```json theme={"dark"}
{
  "data": { "id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d" },
  "meta": {
    "apiVersion": "1",
    "artifactTypeFallback": false,
    "effectiveArtifactType": "shared.project_handbook",
    "duplicate": true
  }
}
```

Required fields:

| Field                            | Meaning                                                                   |
| -------------------------------- | ------------------------------------------------------------------------- |
| `entity_type`                    | `project`, `initiative`, `workstream`, `milestone`, `task`, or `decision` |
| `entity_id`                      | UUID of the entity that owns the artifact                                 |
| `name`                           | Human-readable artifact name                                              |
| `artifact_type`                  | Code returned by `GET /api/v1/artifact-types`                             |
| `artifact_url` or `external_url` | Where the artifact can be opened                                          |

Use `preview_markdown` for a small inline preview and `metadata` for
machine-readable context. New artifacts start in `draft` unless you provide a
different machine-appropriate status.

<Warning>
  The target entity must belong to a workspace you can access. If it has no
  workspace, OrgX rejects the write instead of assigning the artifact by
  creator alone.
</Warning>

## Read artifacts

All reads return the registered artifacts created by `POST /api/v1/artifacts`.
They use the same `{ data, meta }` response envelope.

| Operation           | Method and path                                                         | Use it for                               |
| ------------------- | ----------------------------------------------------------------------- | ---------------------------------------- |
| List in a workspace | `GET /api/v1/artifacts?workspace_id={id}`                               | Browse a workspace's artifacts           |
| Filter the list     | Add `entity_type`, `entity_id`, `status`, `since`, or `limit`           | Narrow the result                        |
| List for an entity  | `GET /api/v1/artifacts/by-entity?entity_type=initiative&entity_id={id}` | Show the evidence attached to one entity |
| Read one            | `GET /api/v1/artifacts/{artifactId}`                                    | Load the artifact and its relationships  |

The workspace list returns at most `limit` records (maximum 100) and reports
`hasMore` in `meta`:

```json theme={"dark"}
{
  "data": [
    {
      "id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "entity_type": "initiative",
      "entity_id": "22222222-2222-4222-8222-222222222222",
      "name": "Launch plan review notes",
      "artifact_type": "shared.project_handbook",
      "status": "draft"
    }
  ],
  "meta": {
    "apiVersion": "1",
    "workspaceId": "11111111-1111-4111-8111-111111111111",
    "count": 1,
    "hasMore": false
  }
}
```

## Verification and acceptance

Machine callers may create an artifact and record machine verification with
`eval_passed`. Human acceptance is a separate session-authenticated action in
Mission Control; an API key cannot claim `approved` or `rejected` at creation.

Draft review records used by the Command UI are a separate surface. They are
not returned by `/api/v1/artifacts` and are not part of the public artifact
resource.

## Artifact types

`GET /api/v1/artifact-types` returns the current global vocabulary, including
each code's label, domain, workflow, and whether it is a deliverable. Use a
returned `type_code`; values such as `document` or `pr` are not valid unless
they appear in that response.

## MCP equivalent

`orgx_attach` registers an artifact through the same resource contract.
`orgx_search` with `type=artifact` reads the resulting records.