Register an artifact

Register a produced piece of work against the entity it belongs to. One of artifact_url or external_url is required. The target entity determines the workspace. Statuses that assert a human ruling (approved, rejected) are refused on this path; an automated reviewer records eval_passed instead. Reuse the same Idempotency-Key and request body to safely retry a timed-out create; reusing a key with a different body returns a conflict.

POST /artifacts

Register an artifact

cURL

curl --request POST \
  --url https://useorgx.com/api/v1/artifacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "entity_type": "task",
  "entity_id": "7fbb727d-17c4-4bc7-9fc7-60eb15e9314d",
  "name": "Launch plan review notes",
  "artifact_type": "shared.project_handbook"
}
'

200

{
  "data": {
    "id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "workspace_id": "11111111-1111-4111-8111-111111111111",
    "name": "Launch plan review notes",
    "artifact_type": "shared.project_handbook",
    "artifact_url": "https://example.com/review.md",
    "entity_type": "task",
    "entity_id": "7fbb727d-17c4-4bc7-9fc7-60eb15e9314d",
    "status": "draft",
    "version": 1
  },
  "meta": {
    "apiVersion": "1",
    "artifactTypeFallback": false,
    "effectiveArtifactType": "shared.project_handbook",
    "duplicate": true
  }
}

Authorizations

Authorization · string · header · required

OrgX API key, sent as Authorization: Bearer oxk_...

Headers

Idempotency-Key · string · required

Workspace-scoped retry key for safe mutation replay.

Required string length: 1 - 200

Pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$

Body

application/json

One of artifact_url or external_url is required.

entity_type · enum<string> · required

Available options: project, initiative, workstream, milestone, task, decision

entity_id · string<uuid> · required

name · string · required

Required string length: 1 - 500

artifact_type · string · required

Required string length: 1 - 120

artifact_url · string

Maximum string length: 2000

external_url · string

Maximum string length: 2000

description · string | null

Maximum string length: 4000

preview_markdown · string

Maximum string length: 25000

initiative_id · string<uuid>

status · enum<string>

Available options: draft, in_review, changes_requested, superseded, archived

metadata · object

created_by_type · enum<string>

Available options: human, agent

created_by_id · string<uuid>

Response

200

application/json

The artifact returned for a safe replay with the same Idempotency-Key

data · object · required

A registered piece of produced work attached to a workspace entity.

Show child attributes

meta · object · required

Show child attributes