Artifacts

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:

curl https://useorgx.com/api/v1/artifact-types

Then create the artifact:

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:

{
  "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:

{
  "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.

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.

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:

{
  "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.

Getting Started

Connect Your Tools

Agent Ops

Platform

Build with the API

REST API v1 Reference

Entity Reference

Content Studio API

MCP and Plugins

Resources

Create an artifact

Read artifacts

Verification and acceptance

Artifact types

MCP equivalent

​Create an artifact

​Read artifacts

​Verification and acceptance

​Artifact types

​MCP equivalent

Create an artifact

Read artifacts

Verification and acceptance

Artifact types

MCP equivalent